Skip to main content

Spain — Verifactu Readiness and Records

This page describes six calls for Verifactu, Spain's regime for billing records sent to the Spanish tax agency (the Agencia Estatal de Administración Tributaria, AEAT):

GET  /api/v1/jurisdictions/es/status
POST /api/v1/jurisdictions/es/connection-check
POST /api/v1/jurisdictions/es/test-invoice
GET /api/v1/jurisdictions/es/records
POST /api/v1/jurisdictions/es/annul
GET /api/v1/jurisdictions/es/annul/{transaction_id}

The first reports how far your setup has got. The second proves a certificate end to end against AEAT's test service. The third issues a test invoice and cancels it at once: of these first four, it is the only one that adds records to your real sequence and sends them to AEAT. The fourth exports the records GoRoute has already made, with AEAT's answer on each. The last two cancel an invoice you issued in error and report how that cancellation stands; the cancellation is a real record, sent to AEAT. Further down, the page also explains how to correct an invoice you have already issued by replacing it.

On production, records go to AEAT's production service

Since 16 October 2026 GoRoute's Spain pack is switched on for both the production service (https://app.goroute.ai/peppol-api) and the test service (https://peppol-api-test.goroute.ai/peppol-api). The calls on this page answer on both.

On production, Verifactu records are real submissions. Every invoice and credit note sent by a Spanish organisation (country ES) enrolled in Verifactu becomes a record, and that record goes to AEAT's production service. That is true whether the document is sent to the buyer over Peppol or to the tax authority only.

On test, records go to AEAT's test service. That service has no tax effect: nothing sent through it is a filing, settles anything, or discharges any obligation a Spanish business has.

An organisation that is not enrolled in Verifactu is unaffected on either service.

Do not take any of this from this page — read it from the service. GET /status returns aeat_environment, which is test or production. That field is the service telling you which AEAT endpoint it uses. Believe it over anything written here, and check it again before you treat any Verifactu record as filed.

This page does not tell you what Spanish law requires of you. Verifactu obligations fall on the business issuing the invoices, and who is in scope, from when, is a question for your tax adviser or AEAT — not for GoRoute's documentation.

GET /api/v1/jurisdictions/es/status​

Readiness, the stored certificate's public facts, and the counts of your Verifactu records.

Permission: an authenticated organisation. No further permission is needed, so any working API key for the organisation can read it.

The response is a fixed object. Every field is always present; several are null until the setup that fills them has happened.

FieldWhat it is
readytrue when nothing is outstanding, otherwise false.
missingnull when ready is true. Otherwise one sentence, in Spanish, naming the next thing to do — Verifactu not enabled for the account, the NIF missing, the legal name missing, the two declarations not confirmed, or the certificate not uploaded. One at a time, in that order. For example: "Suba el certificado digital del negocio."
simulatedtrue only for an organisation GoRoute has set up as a review or demo account, and only on the test service: AEAT's answers for it are simulated and nothing is sent to AEAT. Such an account counts as having a certificate. Always false wherever records go to AEAT's production service.
nifThe business's Spanish tax number as stored, or null.
legal_nameThe business's registered name as stored, or null.
tax_territorypeninsula (mainland Spain and the Balearics, IVA) or canarias (the Canary Islands, IGIC).
aeat_environmenttest or production: which AEAT service this deployment sends to. Read this one.
certificatenull when none is stored. Otherwise an object — see below.
recordsYour Verifactu records counted by state, as an object keyed by state name. A state with no records is simply absent, so an empty object means no records at all. The states are pending (written, not sent), sent (sent, answer awaited), accepted, accepted_with_errors and rejected.
last_csvThe reference AEAT returned for the most recent submission (its código seguro de verificación), or null.
next_send_atWhen the next submission may go, as an ISO 8601 timestamp, or null if nothing is waiting.

certificate, when one is stored:

FieldWhat it is
subjectThe certificate's subject, as the certificate itself states it.
holder_idsThe tax numbers the certificate identifies as its holder, as a list.
not_afterWhen it expires, as an ISO 8601 timestamp.
days_leftWhole days from now until not_after. Negative once it has expired.
expiredtrue once not_after has passed.

Nothing in this response contains the certificate itself or its password. Both live in an encrypted store, and this call reads only the public facts above.

POST /api/v1/jurisdictions/es/connection-check​

One end-to-end test of your setup against AEAT's test service: the certificate, the network path, and the shape of the message GoRoute builds. It sends a single throwaway record that is not part of your real sequence of invoice records, so running it does not disturb anything and does not create a filing.

It uses AEAT's test service on every GoRoute service, production included. That makes it the one call here that never files anything, wherever you run it.

Permission: settings:manage or authority:manage, the same pair that replacing an opt-in country's settings accepts. authority:manage is the permission a connected store app's key carries, so a store app can run the check too.

Body: none. There is nothing to pass.

It needs the NIF, the legal name and an uploaded certificate first; without them it refuses with the 422 below.

The reply always carries ok and stage. stage says how far the check got, and the rest of the fields depend on it:

stageMeansAlso returned
answeredAEAT answered. With simulated (below), the only stage where ok: true is possible.aeat_state (the answer for the submission), record_state (for the one record), error_code and message if AEAT objected to it, and csv, AEAT's reference for the submission.
certificate_expiredThe stored certificate has expired. Nothing was sent to AEAT. ok is false.message only, naming the expiry date.
certificate_not_yet_validThe stored certificate is not valid yet. Nothing was sent to AEAT. ok is false.message only, naming the date it becomes valid.
aeat_refused_messageAEAT rejected the message itself rather than the record in it. ok is false.code and message, as AEAT gave them.
aeat_refused_certificateAEAT refused the certificate during the connection, on both of its services (the one for personal certificates and the one for seals), so nothing reached it. ok is false.message, a fixed sentence asking for a valid qualified certificate issued for the business's NIF, and detail, the refusal as the connection reported it.
aeat_unreachableGoRoute could not reach AEAT's test service. ok is false.message, a fixed sentence asking you to try again in a few minutes, and detail, the network's own description of what failed.
simulatedThe organisation is a GoRoute review or demo account (simulated: true in the status call). Nothing was sent; the answer is simulated. ok is true.aeat_state and record_state (both Correcto), error_code and message (both null), csv, which starts with SIMULADO-, and simulated: true.

Treat ok: false with stage: aeat_unreachable as "try again" and ok: false with any other stage as "something in the setup or the data is wrong". message is written to be shown to the person fixing it, and it is in Spanish, except on aeat_refused_message and answered, where it is AEAT's own text. detail is for your logs and for us; it is not written for a merchant.

POST /api/v1/jurisdictions/es/test-invoice​

AEAT's own "invoice in test mode" method: one test invoice and its cancellation, made in your real sequence of records. The Shopify Verifactu app's Factura de prueba button uses this call.

This writes two permanent records, sent to AEAT

Unlike the connection check, this is not a throwaway. GoRoute writes an invoice record numbered PRU-<yyyymmddhhmmss> (the time in Madrid) in your own Verifactu sequence, and a record cancelling it one second later. Both stay in your sequence for good and both are sent to AEAT, to whichever AEAT service this deployment uses: on production, AEAT's production service. Read aeat_environment from the status call before you run it. Both records appear in the records export below.

Permission: settings:manage or authority:manage, the same as the connection check.

Body: none.

It needs the same setup as everything else: Verifactu enabled, the NIF, the legal name, the two declarations and the certificate. Without them it refuses with the 422 below, and nothing is written.

GoRoute writes the two records, then sends what is waiting in your sequence at once. If AEAT cannot be reached, it tries once more straight away. The answer is always these fields:

FieldWhat it is
numberThe test invoice's number, PRU- followed by the date and time.
qr_urlThe address the test invoice's Verifactu QR code points to.
stateWhat the send did. See the next table.
senttrue once AEAT has given its answer on the test invoice, whether it accepted or rejected it. false if the test invoice has not been answered yet.
messagenull when sent is true. Otherwise one sentence, in Spanish, saying why it has not gone and, where known, from what time it can.
aeat_stateAEAT's answer for the whole submission, Correcto, ParcialmenteCorrecto or Incorrecto, or null if AEAT did not answer. The submission can include older records that were waiting, so this is not the verdict on the test invoice alone; the records export has that.
reason_codenull, or a code naming why nothing was sent: C5_ES_CERT_MISSING, C5_ES_CERT_EXPIRED, C5_ES_CERT_NOT_YET_VALID or C5_ES_CERT_REJECTED (the certificate), C5_ES_AEAT_UNREACHABLE, or C5_ES_AEAT_REJECTED (AEAT refused the whole message).
detailnull when sent is true. Otherwise message, followed in brackets by AEAT's or the network's own words when there are any. This is the text the app shows.
retry_atWhen the next send may go, as an ISO 8601 timestamp, or null.

state is one of these:

stateMeans
sentA submission went and AEAT answered it. Normally sent is then true. If older records were waiting, they went first and the test invoice may not have been in this submission: sent is then false.
waitingAEAT asks for a pause between submissions, and the pause has not ended. Nothing was sent.
busyOther records of this NIF were being sent at that moment. Nothing was sent.
heldThe certificate stops the send: missing, expired, not yet valid, or refused. reason_code says which.
unreachableGoRoute could not reach AEAT, twice.
unavailableGoRoute's certificate store could not be reached. Nothing is wrong with the certificate.
faultAEAT refused the whole message.

When sent is false the two records are not lost. They stay in your sequence and go with the next send: your next invoice, or another test invoice. message says so, in Spanish.

On the test service, a GoRoute review or demo account (simulated: true in the status call) gets a simulated answer: state sent, sent true, aeat_state Correcto, and nothing reaches AEAT.

When setup is incomplete: one 422 for all four calls​

All four calls report a setup problem the same way, with HTTP 422 and this body:

{
"error": "verifactu_setup",
"message": "Suba primero el certificado digital del negocio.",
"request_id": "6f1c0b2e-6b1a-4a44-9f41-2b0f5a7c8e13"
}

message is a sentence in Spanish, written to be shown to the person doing the setup, so pass it through rather than mapping it to your own wording. error is always verifactu_setup, and request_id is the identifier GoRoute adds to a refusal — quote it if you ask us about one. Note that this shape carries error, not the error_code that most of the API's refusals use, so match on error here.

The connection check and the test invoice are the calls that normally produce this, when the NIF, the legal name or the certificate is not in place yet. The test invoice also produces it when its two records cannot be written, with a message that starts "No se pudo registrar la factura de prueba", and when your sequence of records is not intact. In that last case the message asks you to write to support@goroute.ai before you issue any more invoices: do that. The status call and the records export produce it only if the organisation's stored Spanish settings cannot be read at all, which is why you should treat ready and missing as the normal way of asking "is setup finished?".

GET /api/v1/jurisdictions/es/records​

A file of your Verifactu records for a period, with AEAT's answer on each. It is a plain read: it sends nothing to AEAT and changes nothing.

Permission: an authenticated organisation. No further permission is needed, so any working API key for the organisation can download it.

Query parameterRequiredWhat it is
startYesFirst day of the period, as YYYY-MM-DD.
endYesLast day of the period, as YYYY-MM-DD. That day is included.
formatNocsv (the default) or xml. Any other value is refused with HTTP 422.

A record is included when its invoice's issue date falls between start and end, both days included. Records come in the order they were made in your sequence. The test invoice's PRU- records are part of that sequence, so they appear too; the connection check's record is not, so it never does.

The answer is a file download, not JSON. Its name is verifactu-YYYYMMDD-YYYYMMDD.csv or .xml, from start and end, and its content type is text/csv or application/xml.

curl -G https://app.goroute.ai/peppol-api/api/v1/jurisdictions/es/records \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "start=2026-10-01" \
--data-urlencode "end=2026-10-31" \
-o verifactu-october.csv

The CSV has one header row and one row per record:

ColumnWhat it is
seqThe record's place in your sequence.
tipoalta for an invoice record, anulacion for a cancellation record.
numeroThe invoice number. On a cancellation record, the number of the invoice it cancels.
fechaThat invoice's issue date, YYYY-MM-DD.
huellaThe record's fingerprint (hash).
huella_anteriorThe fingerprint of the record before it. Empty for the first record.
estado_aeatpending (written, not sent), sent (sent, answer awaited), accepted, accepted_with_errors or rejected — the same states as records in the status call.
csvAEAT's verification code (código seguro de verificación) for the submission that carried the record. Records sent together share one. Empty until AEAT has accepted the record or found it already registered.
codigo_errorAEAT's error code for this record, if it gave one.
descripcion_errorAEAT's description of that error.

The XML is each record exactly as GoRoute sent it, one after another, inside a <RegistrosFacturacion nif="…"> element. That outer element is GoRoute's own wrapper, not an AEAT message. Do not upload the file to AEAT; it is for reading and keeping.

The export follows the NIF in your current settings. Only records made under that NIF are included. If the NIF has changed, records made under the earlier one do not appear. With no NIF stored, the CSV holds only its header row.

The API reference is wrong about this response. The generated reference lists the successful response as application/json. The call returns CSV or XML as described here.

Sending a document to the tax authority instead of the buyer​

Verifactu's consumer ticket is a sale that is recorded with AEAT and never transmitted to a buyer. The buyer is a member of the public, has no Peppol address, and gets a PDF carrying the tax agency's QR code instead of a network document.

One field on POST /api/v1/invoices asks for that: destination. It sits at the top level of the body, beside invoice, document_format and delivery_channel.

{
"invoice": { "...": "your canonical invoice" },
"destination": "authority"
}
ValueWhat happens
peppolThe default, and what every call did before this field existed. The document is delivered to the buyer the way delivery_channel says.
authorityThe document goes to the tax authority only. No buyer receives it over any channel.

Those are the only two values POST /api/v1/invoices accepts; anything else is rejected by request validation before the send rule runs. The raw-XML route POST /api/v1/documents accepts a third, peppol_authority — see Send XML You Already Generate.

What authority changes​

No lookup, and no email decision. GoRoute does not ask the Peppol network whether the buyer is registered and does not consider sending by email. The delivery object in the response comes back with channel: "authority" and the reason "Sent to the tax authority only; the buyer receives the PDF."

Exactly one validation rule is waived: BUS_009, the rule that requires a buyer Peppol identifier before a document can be sent. A document going nowhere near the network has no buyer Access Point to address, so that rule does not apply to it. Every other rule still blocks the send — a Verifactu record is built from the same invoice as a Peppol document and has to be as correct.

It changes how an Idempotency-Key is matched. destination is added to the request fingerprint only when it is not peppol. So a key you reused before this field existed still matches exactly as it did, and the same key sent once as an ordinary invoice and once as an authority-only document counts as two different requests rather than a replay.

Where it works, and where it is refused​

This is the part to read before you build on it. destination is accepted by the request schema everywhere, on every GoRoute service. Whether anything can serve it is a separate question, answered per service by which jurisdiction packs are switched on there.

Servicedestination: "authority"
Production, https://app.goroute.ai/peppol-apiWorks, for an organisation whose country is ES, which is enrolled in Verifactu and whose Verifactu setup is complete. Its records go to AEAT's production service.
Test, https://peppol-api-test.goroute.ai/peppol-apiWorks, for an organisation whose country is ES and whose Verifactu setup is complete. The Spain pack is switched on and its submit leg runs against AEAT's test service, so nothing sent through it is a filing.

The send endpoint is the ordinary one, and it exists on every service. Where no pack serves the route for you — an organisation no pack serves, such as one that is neither Spanish nor Polish, or one not enrolled in its country's pack — you get the 400 refusal below, with a reason, not a 404. Poland's pack serves this route too, for an enrolled Polish organisation; see Poland — KSeF.

The refusal is HTTP 400, and its message is always this sentence:

destination 'authority' is not available for this document: no tax-authority pack enabled on
this platform, for which this organisation is enrolled, applies to it

The two send routes label that same refusal with two different codes. There is no difference in meaning; handle whichever route you call.

RouteStatuserrorerror_code
POST /api/v1/invoices400authority_refusedAUTHORITY_REFUSED
POST /api/v1/documents400validation_errorINVALID_REQUEST

AUTHORITY_REFUSED on POST /api/v1/invoices covers one more case besides "nothing here serves this": a pack that does serve the route refusing this particular document. For Spain the common one is a sale above the simplified-invoice limit — €3,000, or €400 where the organisation's settings say so — with no buyer tax number on it. Read message; it is written for a person and says which of the two happened.

An Omani import ignores the field​

There is one case where the platform overrides what you ask for. Where Oman's import leg is live, an import that an Omani buyer records is filed with the Oman Tax Authority and never transmitted to a buyer, whatever destination says — including the default peppol. The import path is described in the Oman country guide.

Correcting an invoice by substitution​

When an invoice you have already issued is wrong — for example, it charged VAT at the wrong rate — you can issue a corrective invoice that replaces it: a factura rectificativa por sustitución. The correction carries every line at its corrected values. GoRoute records it with AEAT as a correction of the original.

It is the ordinary send call, POST /api/v1/invoices. Two fields on the invoice ask for it:

FieldValue
invoice_type_code"384", the UNTDID 1001 code for "Corrected invoice".
preceding_invoiceThe original invoice: its number and its issue_date, as it was issued.

document_type stays invoice. The correction needs an invoice number of its own, not the original's. Leave billing_references empty: a correction names one original, and only one.

{
"invoice": {
"document_type": "invoice",
"number": "YOUR_NEW_INVOICE_NUMBER",
"issue_date": "YYYY-MM-DD",
"invoice_type_code": "384",
"preceding_invoice": {
"number": "ORIGINAL_INVOICE_NUMBER",
"issue_date": "YYYY-MM-DD"
},
"...": "the parties, and every line at its corrected values"
}
}

It works with either destination: sent to the buyer, or with "destination": "authority" to the tax authority only.

What GoRoute records with AEAT​

  • The record type. If the original was a simplified invoice (recorded as F2, or as R5), the correction is recorded as R5. For any other original, it is recorded as R1.
  • TipoRectificativa S, for substitution, in every case.
  • The corrected amounts, in full, as on any invoice.
  • The original's taxable base and VAT, in ImporteRectificacion. GoRoute reads these from its own stored record of the original, never from your request, so you do not send them.
  • The original's number and issue date, in FacturasRectificadas.
  • The buyer. An R5 record never names a buyer, because the simplified original did not. A correction of a full invoice must identify the buyer by tax number, as the original did. Without it, the send is refused with C5_ES_RECORD_REFUSED.

The original's record is not cancelled. The correction's record names it.

A credit note is still the other way to correct an invoice: a correction by differences. It is recorded with TipoRectificativa I and its amounts negated. Its record type is decided differently from a substitution's. GoRoute does not look up the original's record for a credit note: the type follows the credit note itself. A credit note that identifies the buyer by tax number is recorded as R1. A credit note with no buyer tax number is recorded as R5, with no buyer, whatever the original was. So a credit note for a full invoice should carry the buyer's tax number, as the invoice did.

For a substitution, GoRoute records R1 for every correction of a full invoice, whatever the reason. A credit note that carries the buyer's tax number is also recorded as R1, whatever the reason. There is no field in the request to choose another code. AEAT's FAQ describes R1 as "Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA": an error in law, or one of the causes in article 80, sections one, two and six, of the Spanish VAT law, such as returned goods or a price change after the sale. It gives other codes for other reasons, among them R4, "Factura Rectificativa (Resto)". Read the definitions in AEAT's Preguntas frecuentes — Procedimientos de facturación. If your correction is for another reason, ask your tax adviser before you use this call.

Refusals before anything is recorded​

In each of these cases nothing is recorded and nothing is sent. The original must be an invoice GoRoute recorded for your organisation, under the NIF in your current settings.

CodeWhenThe sentence GoRoute shows
C5_ES_RECTIFICATION_INVALIDNot exactly one original is named; the original's number or issue date is missing; or the correction reuses the original's number.A corrective invoice by substitution (type code 384) must name exactly one original invoice, with its number and issue date, and carry a new invoice number of its own; fix the request and issue again.
C5_ES_RECTIFIED_NOT_FOUNDYour organisation has no Verifactu record of an invoice with that number and issue date.The invoice being corrected is not among this account's Verifactu records; check its number and issue date and issue the correction again.
C5_ES_RECTIFIED_CANCELLEDThe original was cancelled.The invoice being corrected was cancelled in Verifactu, so it cannot be corrected; issue a new invoice instead.
C5_ES_RECTIFIED_REJECTEDAEAT rejected the original, so it holds no accepted record to replace.The invoice it corrects was rejected by the AEAT, so there is no accepted record to substitute; correct and issue it again instead.

How each send route answers these refusals:

RouteStatuserror_code
POST /api/v1/invoices422JURISDICTION_REFUSED, with regime ES and the reason_code
POST /api/v1/invoices with "destination": "authority"400AUTHORITY_REFUSED
POST /api/v1/documents400INVALID_REQUEST

In each case message carries the reason code, in square brackets, and its sentence.

Check what was recorded​

Check the PDF. GET /api/v1/transactions/{transaction_id}/pdf returns the invoice PDF. A correction by substitution is titled FACTURA RECTIFICATIVA, or FACTURA RECTIFICATIVA (SIMPLIFICADA) when it corrects a simplified invoice. It also carries the line "Rectificativa por sustitución de la factura" followed by the original's number and its issue date (DD-MM-YYYY). If the title is FACTURA or FACTURA SIMPLIFICADA, the document was recorded as an ordinary invoice, not as a correction.

An email sent in Spanish calls the document a factura rectificativa.

The records export above, with format=xml, contains each record as GoRoute sent it. A correction's TipoFactura, TipoRectificativa and ImporteRectificacion elements show what was filed. The authority object on the transaction shows the submission's state and AEAT's reference, not the record type, so do not look for the type there.

Cancelling an invoice issued in error​

When an invoice should never have been issued at all, you can cancel it in Verifactu. GoRoute adds a cancellation record (a registro de facturación de anulación, RegistroAnulacion) to the same sequence as the invoice's own record, and sends it to AEAT.

POST /api/v1/jurisdictions/es/annul
GET /api/v1/jurisdictions/es/annul/{transaction_id}
A cancellation on production reaches AEAT and cannot be undone

On production, the cancellation record goes to AEAT's production service, like every other record. There is no call that takes it back. Read aeat_environment from the status call before you use this, and be sure you have the right invoice.

To change an amount or a VAT rate, do not cancel: correct the invoice by substitution instead. Once an invoice is cancelled, it can no longer be corrected that way (C5_ES_RECTIFIED_CANCELLED).

AEAT's Preguntas frecuentes — Registros de facturación: anulación describes the cancellation record as the way to deal with an invoice issued in error. It also says that the cancelled invoice keeps its number in your series of issued invoices, and that both records, the invoice's and its cancellation, stay in the chain. GoRoute works that way: the invoice's own record is never deleted, and the cancellation names it by your NIF, the invoice number and the issue date. If there is a correct invoice to replace it, issue that as a new invoice. As elsewhere on this page, whether and when to cancel is a question for you and your tax adviser, not for this documentation.

A cancellation is a record with AEAT only. GoRoute sends nothing to the buyer, so an invoice already delivered over Peppol is not recalled. Tell the buyer yourself.

POST /api/v1/jurisdictions/es/annul​

Permission: settings:manage or authority:manage, the same as the test invoice.

Body: the transaction GoRoute returned when the invoice was sent.

{
"transaction_id": "TRANSACTION_ID_OF_THE_INVOICE"
}

The invoice can be cancelled whatever AEAT has answered on it so far, except a rejection: accepted, accepted with errors, or still waiting for AEAT's answer. A cancellation of an invoice still waiting goes after it in the sequence.

GoRoute writes the cancellation record and then sends what is waiting in your sequence at once. If it cannot be sent at once — AEAT asks for a pause between submissions, another send of your records is under way, AEAT cannot be reached, or the certificate stops the send — the record stays pending and is not lost. It goes with the next send of your records. If it is still pending five minutes after it was written, a background run that GoRoute repeats every few minutes sends it, so it does not wait for your next invoice.

Asking twice cancels once. A second request for the same invoice writes nothing new: it answers with the cancellation already recorded and already_cancelled: true, and if AEAT has not answered that cancellation yet, it tries to send it once more. A client can therefore repeat the call to learn AEAT's verdict, or use the read-only call below.

The answer is these fields:

FieldWhat it is
numberThe cancelled invoice's number.
issue_dateThe cancelled invoice's issue date, YYYY-MM-DD.
record_idThe identifier of the cancellation record.
cancelledAlways true in this answer.
already_cancelledfalse when this request wrote the cancellation; true when it had already been written.
statepending, accepted, accepted_with_errors or rejected: AEAT's answer on the cancellation record. pending means AEAT has not answered yet.
aeat_referenceAEAT's reference (the CSV) for the submission that carried the cancellation, or null before one has been answered.
error_codeAEAT's own error code on the cancellation record, or null.
error_textAEAT's own error text on the cancellation record, or null.
simulatedtrue for a GoRoute review or demo account on the test service: AEAT's answer is simulated and nothing reaches AEAT.
reason_codenull, C5_ES_AEAT_REJECTED when state is rejected, or, when state is pending, the code for why this request could not get an answer, where there is one: C5_ES_AEAT_UNREACHABLE; C5_ES_AEAT_REJECTED when AEAT refused the whole message, which is sent again later; or C5_ES_CERT_MISSING, C5_ES_CERT_EXPIRED, C5_ES_CERT_NOT_YET_VALID or C5_ES_CERT_REJECTED for the certificate. A pause or a send already under way gives no code.
reasonThe sentence for reason_code, or null.
retry_atWhen state is pending, the earliest time the next send may go, as an ISO 8601 timestamp, where known; otherwise null.

If AEAT rejects the cancellation itself, state is rejected and error_code and error_text carry AEAT's words. Asking again returns that same record; it does not write a second cancellation.

GET /api/v1/jurisdictions/es/annul/{transaction_id}​

Read only: it writes nothing and sends nothing. Any authenticated caller of the organisation can use it.

If the invoice has not been cancelled, the answer is:

{
"cancelled": false,
"number": "ORIGINAL_INVOICE_NUMBER",
"issue_date": "YYYY-MM-DD"
}

If it has, the answer is the same object as the POST above, with already_cancelled: true. Because this call sends nothing, reason_code and retry_at stay null while the cancellation is pending.

The cancellation also appears in the records export as a record of its own, after the invoice's.

Refusals​

Both calls refuse in the same way, and a refusal writes and sends nothing:

Statuserror_codeWhenThe sentence GoRoute shows
404C5_ES_ANNUL_NOT_FOUNDThe transaction is not your organisation's, or it has no Verifactu record (for example, it was issued before Verifactu was active for your account).This invoice has no Verifactu record in this account, so there is nothing to cancel.
409C5_ES_ANNUL_REJECTEDAEAT rejected the invoice's record, so it holds nothing to cancel. Correct the invoice and issue it again instead.The AEAT rejected this invoice, so it holds no record to cancel; correct the invoice and issue it again instead.
422C5_ES_NOT_READYYour organisation's Spanish settings have no business NIF, or cannot be read.Verifactu setup is not complete for this account; finish setup in the app.

These refusals do not use the verifactu_setup shape of the setup 422 above. Their body is:

{
"error": "C5_ES_NOT_READY",
"error_code": "C5_ES_NOT_READY",
"message": "Verifactu setup is not complete for this account; finish setup in the app. (business NIF is required)",
"request_id": "6f1c0b2e-6b1a-4a44-9f41-2b0f5a7c8e13"
}

Match on error_code. message is the sentence in the table, in English, sometimes followed in brackets by a detail; request_id is the identifier to quote if you ask us about a refusal.

What this page does not cover​

The Spain pack has nine routes. The three not described above are deliberately left out, and each needs more than a paragraph alongside something else:

  • POST /api/v1/jurisdictions/es/certificate and DELETE /api/v1/jurisdictions/es/certificate — uploading and removing the business's own qualified signing certificate. Handing a signing certificate and its password to a service deserves its own page about how it is held, not a mention here. The stored certificate's status and expiry can be read with one call: see Your stored tax-authority credentials.
  • GET /api/v1/public/verifactu/declaracion-responsable — the formal statement a billing software producer makes about its own product. That is a compliance document, not an integration feature.

Settings for Spain, like any other country's, go through the generic PUT /api/v1/jurisdictions/{code}/settings with ES as the code — see Jurisdiction Settings.