Invoice lifecycle
Every invoice carries a status that describes where it is in the issuing and
reporting flow, driven by a state machine.
Status list
status | Meaning |
|---|---|
draft | saved as a draft, not yet sent |
queued | accepted for sending, waiting to be transmitted |
sending | being transmitted to AEAT |
accepted | AEAT accepted the billing record |
accepted_with_errors | AEAT registered the record but flagged issues to correct (subsanación) |
rejected | AEAT rejected the record; it was not registered |
failed | AEAT returned a negative processing outcome (incidencia) |
error | no usable response from AEAT (transport error, timeout, envelope fault) |
When the status is not a clean accepted, errorReason carries a machine-readable
detail (see the table below).
State machine
An invoice created directly with POST /invoices briefly enters at queued; one
created as a draft enters at draft and moves to queued when you call
POST /invoices/draft/{uuid}/send.
Today, the sandbox resolves queued → sending → a terminal status synchronously
within the same request — the 202 Accepted response already carries the final
status (see Send invoice). Treat the
intermediate states as part of the model rather than something you need to poll for
today; still read status from the response rather than assuming accepted, since it
can come back as any of the terminal values.
errorReason values
errorReason | Ends in status | What it means |
|---|---|---|
INVALID_RECIPIENT_FISCAL_ID | rejected | the recipient NIF is not valid / not in the AEAT census |
DUPLICATE_INVOICE_NUMBER | rejected | a record with the same series+number already exists |
SCHEMA_VALIDATION_FAILED | rejected | the record failed AEAT schema validation |
UNAUTHORIZED_RECIPIENT | rejected | the issuer is not allowed to invoice this recipient |
PROCESSING_INCIDENT | failed | AEAT reported a processing incidencia |
FINGERPRINT_MISMATCH | accepted_with_errors | registered, but the huella calculation was flagged |
GATEWAY_TIMEOUT | error | no response received from AEAT |
SUBMISSION_REJECTED | error | the submission envelope was rejected before processing |
In the sandbox, each of these can be triggered on demand with a reserved recipient tax id.