e-Transport API¶
The client, its value types, and the bidirectional flat models. The generated
XSD models (anafpy.etransport.schema) are intentionally not documented here —
their nomenclature enums (CodJudetType, CodTaraType, …) mirror ANAF's code
lists one-to-one.
anafpy.etransport.client ¶
Async client for the RO e-Transport web services (ETRANSPORT/ws/v1).
Design mirrors anafpy.efactura.client with four key differences:
1. Upload path embeds standard, cif, and versiune as path segments
(POST /upload/ETRANSP/{cif}/{versiune}), not query params; the body must be the
declaration XML (application/xml — there is no JSON request format).
2. Responses are JSON, not e-Factura's XML <header> (per the vendored swagger
specs); errors ride an Errors[{errorMessage}] array, including lista's
no-results note.
3. Status uses a path param (GET stareMesaj/{id_incarcare}), not a query param.
4. No download step — the UIT code is returned in the upload response; state is
tracked via lista / stareMesaj.
ETransportClient ¶
ETransportClient(provider: TokenProvider, *, environment: Environment = PROD, http: AsyncClient | None = None, timeout: float = 60.0)
Bases: HttpClientBase
Talks to ANAF e-Transport over OAuth2.
Construct with an authenticated :class:~anafpy.auth.provider.TokenProvider; the
client owns an httpx.AsyncClient (unless one is injected — it must then
carry :class:~anafpy.auth.oauth.AnafAuth and a non-empty base_url;
an empty one raises :class:~anafpy.exceptions.AnafConfigError, since
injected clients are never mutated) and should
be used as an async context manager so it is closed cleanly.
upload
async
¶
upload(xml: str | bytes, *, cif: str, version: int = 2) -> UploadResult
Submit a transport declaration XML for processing.
Returns an :class:UploadResult whose upload_id feeds get_status and
uit is the transport declaration code returned on acceptance. A document
rejected at submission comes back with accepted is False and errors
populated — not as an exception.
upload_document
async
¶
upload_document(document: FlatSubmission, *, cif: str, version: int = 2) -> UploadResult
Compose a flat e-Transport document and file it — no XML handling needed.
Accepts any of the four flat documents (a :class:FlatTransport
declaration/correction, :class:FlatDeletion, :class:FlatConfirmation, or
:class:FlatVehicleChange from :mod:anafpy.etransport.models), renders it
to the ANAF declaration XML with cod_declarant taken from cif (unless
the document sets declarant_code itself), and uploads it. One call, one
result-or-raise, same as :meth:upload.
get_status
async
¶
get_status(upload_id: str) -> MessageStatus
Poll the processing state for an upload_id (index_incarcare).
list_notifications ¶
list_notifications(*, days: int, cif: str) -> AsyncIterator[Notification]
Iterate transport notifications from the last days (1-60) for cif.
Yields each :class:Notification; an empty window yields nothing. The
lista endpoint is not paginated, so this is a single request under the hood.
Consume with async for. Raises :class:AnafConfigError for a bad days
(eagerly), and :class:AnafResponseError if ANAF reports a genuine list error
(a benign "no notifications" note yields an empty iterator instead).
info
async
¶
info(*, organizer_cui: str, declarant_cui: str | None = None, uit: str | None = None, declarant_ref: str | None = None) -> InfoList
Look up active notifications where organizer_cui (ANAF: cui_op)
is the transport organizer.
A benign "no results" note comes back as an empty :class:InfoList with
error carrying ANAF's wording; a genuine query error (missing SPV
rights, daily limit, unknown CUI) raises :class:AnafResponseError —
the same split the list endpoints apply.
upload_and_wait
async
¶
upload_and_wait(xml: str | bytes, *, cif: str, version: int = 2, timeout: float = 300.0, initial_wait: float = 2.0, max_wait: float = 30.0) -> MessageStatus
Upload, then poll get_status until a terminal state or timeout.
Raises :class:TimeoutError if the declaration is still processing when the
budget is exhausted. A nok or rejected result is returned, not raised.
anafpy.etransport.models ¶
Value types returned by :class:anafpy.etransport.client.ETransportClient.
Key differences from e-Factura:
- Responses are JSON, not e-Factura's XML <header> (per the vendored swagger
specs); the private _*Envelope models validate the wire shapes.
- UploadResult carries both upload_id (index_incarcare) and uit
(the transport declaration code returned at upload time — no separate download step).
- MessageStatus has no download_id; the UIT is already in UploadResult.
- Notification mirrors the richer JSON returned by lista/{zile}/{cif}, and
InfoList / InfoItem cover the transporter-lookup endpoint; both read ANAF's
terse wire names via aliases and expose descriptive field names instead.
- The flat models are bidirectional — like e-Factura's authoring models, the
Flat* shapes here both view a parsed declaration
(:func:read_flat_transport) and author one (:func:build_etransport /
:func:render_etransport): e-Transport has no upstream authoring software the way
invoicing does, and ANAF's XSD is small and fully enumerated, so anafpy translates
the whole schema instead of passing XML through.
FlatSubmission ¶
FlatSubmission = FlatTransport | FlatDeletion | FlatConfirmation | FlatVehicleChange
The four documents that can be filed with e-Transport.
MessageState ¶
Bases: StrEnum
Terminal/non-terminal states reported by stareMesaj.
UploadResult ¶
Bases: BaseModel
Outcome of POST /upload/ETRANSP/{cif}/{versiune}.
upload_id (index_incarcare) feeds get_status; uit is the transport
declaration code available immediately on acceptance; there is no separate download.
MessageStatus ¶
Bases: BaseModel
Outcome of GET stareMesaj/{id_incarcare}.
NotificationMessage ¶
Bases: _AliasedReadModel
One entry in a notification's mesaje array.
Notification ¶
Bases: _AliasedReadModel
One entry from GET lista/{zile}/{cif}.
Field names follow the flat-model vocabulary (operation_type, carrier_*,
plate, ...); ANAF's wire names remain as aliases.
Location ¶
Bases: _AliasedReadModel
A loc_start or loc_final from an info record.
InfoItem ¶
Bases: _AliasedReadModel
One record from GET info?cui_op=....
InfoList ¶
Bases: BaseModel
Response from GET info?cui_op=....
error carries ANAF's benign "no results" note (with items empty);
genuine query errors are raised by the client, never returned here.
FlatTransportPartner ¶
Bases: BaseModel
Commercial partner of the transport.
FlatTransportVehicle ¶
Bases: BaseModel
Vehicle, carrier, and transport-date details.
FlatTransportAddress ¶
Bases: BaseModel
A national address at one end of the road route.
FlatTransportLocation ¶
Bases: BaseModel
One end of the road route: exactly one of border_point (PTF),
customs_office (BV), or a national address.
Which one ANAF expects depends on the operation type: a domestic TTN uses
addresses at both ends; inbound operations (AIC/LHI/SCI/IMP/DIN) start at a
border point or customs office, outbound ones (LIC/LHE/SCE/EXP/DIE) end at
one; a customs office is only valid at the start of an import (IMP) or the
end of an export (EXP). ANAF validates all of that on upload.
FlatTransportGood ¶
Bases: BaseModel
One transported-goods line.
FlatTransportDocument ¶
Bases: BaseModel
A transport document reference (CMR, invoice, ...).
FlatPriorNotification ¶
Bases: BaseModel
A reference to a prior declaration (notificareAnterioara).
FlatTransport ¶
Bases: _FlatSubmissionBase
An e-Transport declaration in an easy-to-read shape.
The same model authors a declaration (see :func:build_etransport /
:func:render_etransport, or the client's upload_document) and views a
parsed one (:func:read_flat_transport). Set correction_of_uit to file it
as a correction of an already-issued UIT.
FlatDeletion ¶
Bases: _FlatSubmissionBase
Deletion (stergere) of an issued UIT.
FlatConfirmation ¶
Bases: _FlatSubmissionBase
Confirmation (confirmare) of an issued UIT.
FlatVehicleChange ¶
Bases: _FlatSubmissionBase
Vehicle change (modifVehicul) on an issued UIT.
parse_etransport_document ¶
parse_etransport_document(xml: bytes) -> ETransport | None
Parse e-Transport wire XML into its :class:ETransport model, or None when
the bytes are not a parseable declaration. Never raises on bad input.
read_flat_transport ¶
read_flat_transport(doc: ETransport) -> FlatSubmission
Translate a parsed :class:ETransport document to its flat model.
Full translation: every XSD field maps onto the flat shape (only the schema's
unused xs:any extension hooks are not carried). Raises :class:ValueError
(or a pydantic ValidationError) for a document that carries none of the four
operations or otherwise cannot be represented.
build_etransport ¶
build_etransport(document: FlatSubmission, *, declarant_code: str | None = None) -> ETransport
Compose a flat document into the :class:ETransport wire model.
cod_declarant comes from the model's declarant_code or the
declarant_code argument (typically the upload CIF); setting both to
different values raises :class:AnafConfigError, as does setting neither.
render_etransport ¶
render_etransport(document: FlatSubmission, *, declarant_code: str | None = None) -> bytes
Compose a flat document and serialize it to upload-ready UTF-8 XML bytes.