Estats d'enviament VeriFactu

Cada factura que emet la teva empresa sota VeriFactu produeix un registre de facturació: una declaració XML signada que es transmet a l'AEAT i queda encadenada criptogràficament al registre anterior de la mateixa empresa. La factura i el seu registre són dos objectes diferents amb dos cicles de vida diferents — una factura pot estar sent i cobrada mentre el seu registre continua rejected per l'AEAT.

Aquesta pàgina tracta del registre. Si integres contra Factuarea i només vigiles l'estat de la factura, no t'assabentaràs que l'Administració tributària ha rebutjat una declaració.

Quan aplica

El cicle de vida del registre aplica a tota empresa amb VeriFactu efectivament activat, des del moment en què una factura surt de draft. No aplica a:

• Empreses encara en mode no_verifactu: els registres es continuen creant i encadenant en local, però no es transmeten mai, de manera que queden fora del cicle acceptat/rebutjat (BR-VFC-018, RD 1007/2023 art. 16).
• Factures històriques importades saltant-se el pas de VeriFactu — no es crea cap registre, així que no hi ha res a consultar (BR-VFC-009).

Consulta Alta automàtica a VeriFactu per a les comportes que decideixen si el registre arriba a crear-se.

Els cinc estats

La distinció que importa és rejected davant error. rejected és l'AEAT dient «he llegit la teva declaració i està malament». error és la declaració que no va arribar mai. Es reparen amb operacions diferents, i confondre-les és l'error d'integració més habitual en aquest endpoint.

accepted és l'únic estat genuïnament immutable: la matriu de transicions rebutja qualsevol sortida d'aquest estat, perquè el RD 1007/2023 fa inalterable un registre ja registrat. Corregir un registre acceptat no l'edita mai: subsanar genera un registre nou que el succeeix. Tots els altres estats admeten una transició nova, i això és el que fa possible el reintent.

Què envia l'API

No crees mai un registre amb un payload — es crea per tu. El que fas és llegir-lo. L'API v1 retorna l'objecte registre a GET /v1/companies/{company}/verifactu/records/{id}, GET /v1/companies/{company}/verifactu/records i, indexat per factura, a GET /v1/companies/{company}/invoices/{id}/verifactu:

Dos camps mereixen el seu propi avís.

La huella és identitat, no una suma de control que puguis recalcular. Es calcula a partir del NIF de l'emissor, la sèrie i el número, la data d'expedició, el tipus de factura, la quota total, l'import total, la huella del registre anterior i la marca de temps de generació — en aquest ordre i format exactes. Si qualsevol d'aquests valors canvia, la cadena es trenca i falla la prova d'integritat de tota l'empresa (BR-VFC-013). Per això hi ha correccions que no es poden reparar al lloc; vegeu Reintentar o esmenar.

L'aeat_csv s'escriu una sola vegada. En acceptar-se es persisteix i no se sobreescriu mai, ni tan sols si l'AEAT retorna el mateix CSV en una transmissió posterior. Un registre que passa a rejected després d'haver estat submitted conserva el CSV anterior a efectes d'auditoria, així que un aeat_csv no nul en un registre rejected és el que s'espera, no una fallada (BR-VFC-016).

curl https://api.factuarea.com/v1/companies/{company}/invoices/0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42/verifactu \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"

{
  "data": {
    "id": "0197b3c9-1de2-7c40-8b71-a4d5e6f70123",
    "object": "verifactu_record",
    "type": "ALTA",
    "invoice_type": "F1",
    "invoice_number": "F-2026-0042",
    "date": "2026-05-15",
    "amount": 121.0,
    "status": "accepted",
    "huella": "9F2C1A0B7E4D6835A1C0B9E8D7F6A5B43C2D1E0F9A8B7C6D5E4F3A2B1C0D9E8F",
    "aeat_submission_id": "sub_0197b3c9",
    "aeat_csv": "FCT-2026-A1B2C3D4-E5F6",
    "environment": "production",
    "transmitted_at": "2026-05-15T09:41:02Z",
    "is_simplificada": false,
    "is_substitute_for_simplified": false,
    "created_at": "2026-05-15T09:40:58Z"
  }
}

Els reintents no tenen topall, i alguns registres estan bloquejats

Darrere d'error hi ha dues situacions molt diferents.

Una fallada tècnica es reintenta sola, sense límit. Si un enviament no obté resposta, obté una fallada de servidor o falla la xarxa, els seus registres es reintenten amb intervals creixents —1, 5, 15 i 30 minuts i després cada 55— de manera que no passi més d'una hora entre dos intents, mentre duri la incidència (art. 16.4 de l'Ordre HAC/1177/2024). No hi ha nombre màxim d'intents, així que max_retries_exceeded ja no es retorna per als registres de facturació (continua aplicant al reintent d'un esdeveniment en mode no_verifactu). Mentre hi ha una incidència, el següent enviament porta la marca d'incidència, i els registres generats entretant esperen darrere dels anteriors.

Un registre bloquejat no es reintenta, perquè reintentar tornaria a fallar fins que actuïs: cap certificat utilitzable, cap representació activa, un presentador que l'AEAT no ha habilitat o un rebuig del costat del client. Mostra is_blocked: true i el seu block_reason, i atura tots els registres que van darrere a la cadena de l'empresa. Resol la causa i s'allibera sol (pujar el certificat, registrar la representació o canviar el mode reactiva el que aquest succés pot alliberar) o amb una crida a POST /v1/companies/{company}/verifactu/records/retry-blocked, que respon 202 amb quants registres ha reactivat. Les causes i el seu significat són a Alta automàtica a VeriFactu.

GET /v1/companies/{company}/verifactu/stats informa de quants registres continuen esperant (pending_incident_count), quants d'ells estan bloquejats (blocked_incident_count) i l'antiguitat del més antic (oldest_pending_at).

El comptador d'intents i la planificació del següent reintent continuen sense exposar-se a l'objecte registre; el que consultes és l'estat. La cronologia d'auditoria és a GET /v1/companies/{company}/verifactu/records/{id}/activities.

Reintentar o esmenar

Les dues operacions actuen sobre un registre que ja existeix, i una tercera allibera els bloquejats. No són intercanviables.

Reintentar a cegues tampoc no té límit d'intents. L'esmena és una correcció manual deliberada amb dades noves, la norma no hi posa topall i no edita mai un registre: genera una alta nova, amb la mateixa clau de factura que la que corregeix, la seva pròpia huella i la seva pròpia posició a la cadena, i l'original queda intacte (BR-VFC-020, BR-VFC-046). Abans de crear res compara els camps regenerats que entren a la huella amb els emmagatzemats; si algun difereix, respon 422 amb el subcodi que t'indica que cal anul·lar, i no es crea res. El flux complet, els subcodis d'error i els consells de prevenció són a Esmena de registres VeriFactu.

Què surt al PDF

L'estat del registre no canvia el PDF. Sigui quin sigui l'estat, la factura imprimeix el mateix bloc QR legal a la cantonada superior dreta de la primera pàgina: l'etiqueta QR tributario:, un codi de 30×30 mm que apunta al servei de verificació de l'AEAT amb el NIF de l'emissor, la sèrie i el número, la data i el total, i la llegenda a sota (BR-VFC-015).

Tres conseqüències que convé contemplar en el disseny:

• El QR s'imprimeix així que existeix un registre — fins i tot mentre està pending, error o rejected. Un destinatari que l'escanegi abans de l'acceptació veurà que l'AEAT no informa de cap alta. És el comportament correcte, no un defecte.
• El CSV no s'imprimeix al PDF. Només està disponible per l'API i al tauler.
• La huella i la marca de temps de l'alta també van deixar d'imprimir-se. Si els estaves extraient del PDF, llegeix-los del registre.

L'esmena és l'única operació que a més toca el document imprès: torna a congelar deliberadament els snapshots immutables de destinatari i emissor a partir de les dades mestres actuals, perquè el PDF coincideixi amb el que es va tornar a declarar a l'AEAT (BR-INV-024, BR-VFC-020). És l'únic camí que reescriu un snapshot ja congelat.

Què arriba a l'AEAT

Cada registre transmet una declaració, encadenada per la seva huella al registre anterior de la mateixa empresa. Existeixen tres classes de registre, i no comparteixen una sola cadena: les altes (ALTA) i les anul·lacions (ANULACION) comparteixen la cadena de facturació, mentre que els registres d'esdeveniments del sistema mantenen una cadena pròpia a part, perquè la norma tracta els esdeveniments operatius com a evidència separada (BR-VFC-014).

Una esmena es declara com una alta nova que porta sempre Subsanacion=S, més RechazoPrevio quan segueix un rebuig: X per a una alta rebutjada d'una factura que l'AEAT no té, S per a una esmena rebutjada d'una factura que sí que té, i cap per a l'esmena d'un registre acceptat. Cap de les dues marques no entra al càlcul de la huella, així que declarar-les no pertorba la cadena (BR-VFC-026, BR-VFC-046). Els registres d'una empresa arriben a l'AEAT en lots ordenats de fins a 1.000, respectant el temps d'espera que indica l'AEAT (BR-VFC-056).

Pots verificar la cadena sencera pel teu compte amb GET /v1/companies/{company}/verifactu/chain/validate, que recalcula totes les huellas i informa de les anomalies. Està limitat a una crida per minut i empresa perquè recorre el llibre registre complet.

Traçabilitat

Derivat de les regles de domini del backend de Factuarea:

• BR-VFC-006 — la política anterior de reintents amb topall; per als registres de facturació la substitueix BR-VFC-040.
• BR-VFC-040 — reintent periòdic, almenys cada hora, sense topall d'intents, en l'ordre de la cadena i amb l'avís de pendents.
• BR-VFC-048 — un registre bloquejat (sense reintent automàtic) i el seu alliberament, per la seva causa o amb retry-blocked.
• BR-VFC-049 — un registre que incompleix l'esquema de l'AEAT s'aïlla com a rejected (SCHEMA_INVALID) i no s'envia mai.
• BR-VFC-013 — la cadena de huellas és immutable i verificable; qualsevol alteració invalida la garantia d'integritat davant l'AEAT.
• BR-VFC-014 — les tres classes de registre i les seves cadenes independents.
• BR-VFC-015 — el bloc QR obligatori a la factura impresa.
• BR-VFC-016 — el CSV com a identitat pública del registre, persistit sense alterar.
• BR-VFC-018 — mode no_verifactu: cadena local, sense transmissió.
• BR-VFC-020 — esmena de registres acceptats o rebutjats com una alta nova, i guarda de la huella.
• BR-VFC-046 — diverses altes per factura: ordinal, RechazoPrevio i l'última alta.
• BR-VFC-026 — les marques AEAT d'una alta d'esmena (Subsanacion, RechazoPrevio).
• BR-VFC-056 — remissió en lots ordenats amb control de flux.
• BR-INV-024 — el snapshot immutable del destinatari i l'única excepció que el refresca.

Derivat també de la màquina d'estats de transmissió documentada al costat d'aquestes regles (AeatTransmissionStatus), que és la font de veritat de la matriu de transicions citada a Els cinc estats.