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, see Correct an invoice |
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); A-Cube sends it again |
When the status is not a clean accepted, errorReason carries a machine-readable
detail (see the table below), and the AEAT response fields
carry the raw AEAT code and description.
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.
accepted_with_errors is the only status you can leave by yourself: sending a
correction (subsanación) with
POST /invoices/{uuid}/correction
moves the invoice back to queued, and the correction is reported like a new record.
If AEAT accepts it the invoice ends in accepted; if AEAT rejects it
(reject_correction) the invoice returns to accepted_with_errors, because AEAT keeps
the record it already had, and you can correct it again.
error is not final either: it marks a transient failure that starts a
VERI*FACTU incident for the issuer,
and A-Cube sends the record again until it reaches another status.
Get notified
Subscribe to webhooks to learn the outcome without
polling: invoice.sent, invoice.rejected and invoice.failed are delivered when an
invoice reaches its outcome, and verifactu.incident when an incident starts or ends.
See Event types for which event each status produces.
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 or failed | the submission envelope was rejected before processing |
UNREADABLE_RESPONSE | error | AEAT answered, but the response could not be read |
errorReason is A-Cube's own category and is null when an AEAT code has no specific
category; the exact AEAT code is always available in aeatErrorCode.
In the sandbox, each of these can be triggered on demand with a reserved recipient tax id.
AEAT response fields
Every invoice resource returned by POST /invoices, GET /invoices/{uuid} and the
other invoice endpoints carries the details of its last submission to AEAT:
| Field | Type | Meaning |
|---|---|---|
aeatErrorCode | string, nullable | the raw AEAT error code of the last submission (CodigoErrorRegistro, or the SOAP Fault code), when AEAT returned one |
aeatErrorDescription | string, nullable | the AEAT description of that error, when AEAT returned one |
sendAttempts | integer | how many times the invoice has been sent to AEAT; 0 while it is a draft |
lastSendAttemptAt | string, nullable | when the invoice was last sent to AEAT (ISO 8601), null if it has not been sent yet |
sentWithIncident | boolean | true when the record reached AEAT late because of a technical incident and was flagged as such (Incidencia) in the submission |
Use errorReason to drive your error handling, and aeatErrorCode /
aeatErrorDescription when you need the exact AEAT diagnosis, for example to show it
to the issuer or to open a ticket. After a
correction, these fields describe the
submission of the correction.
The recipient object is null for a
simplified invoice, which has no
identified recipient.