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.
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.
| Field | What it is |
|---|---|
ready | true when nothing is outstanding, otherwise false. |
missing | null 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." |
simulated | true 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. |
nif | The business's Spanish tax number as stored, or null. |
legal_name | The business's registered name as stored, or null. |
tax_territory | peninsula (mainland Spain and the Balearics, IVA) or canarias (the Canary Islands, IGIC). |
aeat_environment | test or production: which AEAT service this deployment sends to. Read this one. |
certificate | null when none is stored. Otherwise an object — see below. |
records | Your 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_csv | The reference AEAT returned for the most recent submission (its código seguro de verificación), or null. |
next_send_at | When the next submission may go, as an ISO 8601 timestamp, or null if nothing is waiting. |
certificate, when one is stored:
| Field | What it is |
|---|---|
subject | The certificate's subject, as the certificate itself states it. |
holder_ids | The tax numbers the certificate identifies as its holder, as a list. |
not_after | When it expires, as an ISO 8601 timestamp. |
days_left | Whole days from now until not_after. Negative once it has expired. |
expired | true 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:
stage | Means | Also returned |
|---|---|---|
answered | AEAT 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_expired | The stored certificate has expired. Nothing was sent to AEAT. ok is false. | message only, naming the expiry date. |
certificate_not_yet_valid | The stored certificate is not valid yet. Nothing was sent to AEAT. ok is false. | message only, naming the date it becomes valid. |
aeat_refused_message | AEAT rejected the message itself rather than the record in it. ok is false. | code and message, as AEAT gave them. |
aeat_refused_certificate | AEAT 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_unreachable | GoRoute 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. |
simulated | The 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.
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:
| Field | What it is |
|---|---|
number | The test invoice's number, PRU- followed by the date and time. |
qr_url | The address the test invoice's Verifactu QR code points to. |
state | What the send did. See the next table. |
sent | true 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. |
message | null when sent is true. Otherwise one sentence, in Spanish, saying why it has not gone and, where known, from what time it can. |
aeat_state | AEAT'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_code | null, 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). |
detail | null 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_at | When the next send may go, as an ISO 8601 timestamp, or null. |
state is one of these:
state | Means |
|---|---|
sent | A 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. |
waiting | AEAT asks for a pause between submissions, and the pause has not ended. Nothing was sent. |
busy | Other records of this NIF were being sent at that moment. Nothing was sent. |
held | The certificate stops the send: missing, expired, not yet valid, or refused. reason_code says which. |
unreachable | GoRoute could not reach AEAT, twice. |
unavailable | GoRoute's certificate store could not be reached. Nothing is wrong with the certificate. |
fault | AEAT 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 parameter | Required | What it is |
|---|---|---|
start | Yes | First day of the period, as YYYY-MM-DD. |
end | Yes | Last day of the period, as YYYY-MM-DD. That day is included. |
format | No | csv (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:
| Column | What it is |
|---|---|
seq | The record's place in your sequence. |
tipo | alta for an invoice record, anulacion for a cancellation record. |
numero | The invoice number. On a cancellation record, the number of the invoice it cancels. |
fecha | That invoice's issue date, YYYY-MM-DD. |
huella | The record's fingerprint (hash). |
huella_anterior | The fingerprint of the record before it. Empty for the first record. |
estado_aeat | pending (written, not sent), sent (sent, answer awaited), accepted, accepted_with_errors or rejected — the same states as records in the status call. |
csv | AEAT'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_error | AEAT's error code for this record, if it gave one. |
descripcion_error | AEAT'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"
}
| Value | What happens |
|---|---|
peppol | The default, and what every call did before this field existed. The document is delivered to the buyer the way delivery_channel says. |
authority | The 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.
| Service | destination: "authority" |
|---|---|
Production, https://app.goroute.ai/peppol-api | Works, 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-api | Works, 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.
| Route | Status | error | error_code |
|---|---|---|---|
POST /api/v1/invoices | 400 | authority_refused | AUTHORITY_REFUSED |
POST /api/v1/documents | 400 | validation_error | INVALID_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:
| Field | Value |
|---|---|
invoice_type_code | "384", the UNTDID 1001 code for "Corrected invoice". |
preceding_invoice | The 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 asR5), the correction is recorded asR5. For any other original, it is recorded asR1. TipoRectificativaS, 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
R5record 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 withC5_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.
| Code | When | The sentence GoRoute shows |
|---|---|---|
C5_ES_RECTIFICATION_INVALID | Not 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_FOUND | Your 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_CANCELLED | The original was cancelled. | The invoice being corrected was cancelled in Verifactu, so it cannot be corrected; issue a new invoice instead. |
C5_ES_RECTIFIED_REJECTED | AEAT 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:
| Route | Status | error_code |
|---|---|---|
POST /api/v1/invoices | 422 | JURISDICTION_REFUSED, with regime ES and the reason_code |
POST /api/v1/invoices with "destination": "authority" | 400 | AUTHORITY_REFUSED |
POST /api/v1/documents | 400 | INVALID_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}
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:
| Field | What it is |
|---|---|
number | The cancelled invoice's number. |
issue_date | The cancelled invoice's issue date, YYYY-MM-DD. |
record_id | The identifier of the cancellation record. |
cancelled | Always true in this answer. |
already_cancelled | false when this request wrote the cancellation; true when it had already been written. |
state | pending, accepted, accepted_with_errors or rejected: AEAT's answer on the cancellation record. pending means AEAT has not answered yet. |
aeat_reference | AEAT's reference (the CSV) for the submission that carried the cancellation, or null before one has been answered. |
error_code | AEAT's own error code on the cancellation record, or null. |
error_text | AEAT's own error text on the cancellation record, or null. |
simulated | true for a GoRoute review or demo account on the test service: AEAT's answer is simulated and nothing reaches AEAT. |
reason_code | null, 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. |
reason | The sentence for reason_code, or null. |
retry_at | When 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:
| Status | error_code | When | The sentence GoRoute shows |
|---|---|---|---|
| 404 | C5_ES_ANNUL_NOT_FOUND | The 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. |
| 409 | C5_ES_ANNUL_REJECTED | AEAT 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. |
| 422 | C5_ES_NOT_READY | Your 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/certificateandDELETE /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.