Skip to main content

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​

statusMeaning
draftsaved as a draft, not yet sent
queuedaccepted for sending, waiting to be transmitted
sendingbeing transmitted to AEAT
acceptedAEAT accepted the billing record
accepted_with_errorsAEAT registered the record but flagged issues to correct, see Correct an invoice
rejectedAEAT rejected the record; it was not registered
failedAEAT returned a negative processing outcome (incidencia)
errorno 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​

errorReasonEnds in statusWhat it means
INVALID_RECIPIENT_FISCAL_IDrejectedthe recipient NIF is not valid / not in the AEAT census
DUPLICATE_INVOICE_NUMBERrejecteda record with the same series+number already exists
SCHEMA_VALIDATION_FAILEDrejectedthe record failed AEAT schema validation
UNAUTHORIZED_RECIPIENTrejectedthe issuer is not allowed to invoice this recipient
PROCESSING_INCIDENTfailedAEAT reported a processing incidencia
FINGERPRINT_MISMATCHaccepted_with_errorsregistered, but the huella calculation was flagged
GATEWAY_TIMEOUTerrorno response received from AEAT
SUBMISSION_REJECTEDerror or failedthe submission envelope was rejected before processing
UNREADABLE_RESPONSEerrorAEAT 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:

FieldTypeMeaning
aeatErrorCodestring, nullablethe raw AEAT error code of the last submission (CodigoErrorRegistro, or the SOAP Fault code), when AEAT returned one
aeatErrorDescriptionstring, nullablethe AEAT description of that error, when AEAT returned one
sendAttemptsintegerhow many times the invoice has been sent to AEAT; 0 while it is a draft
lastSendAttemptAtstring, nullablewhen the invoice was last sent to AEAT (ISO 8601), null if it has not been sent yet
sentWithIncidentbooleantrue 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.