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. Tots els altres estats admeten una transició nova, i això és el que fa possibles el reintent i l'esmena.

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/verifactu/records/{id}, GET /v1/verifactu/records i, indexat per factura, a GET /v1/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/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"
  }
}

El pressupost de reintents existeix, i no viatja al payload

Darrere d'error hi ha un comptador i una planificació. Una transmissió fallida es torna a encuar amb retrocés exponencial, i el nombre de reintents tècnics a cegues està limitat per ronda de transmissió; esgotat el límit, un reintent manual addicional respon amb un error de regla de negoci en lloc de tornar a encuar (BR-VFC-006). Al costat del comptador, el registre porta una marca d'incidència tècnica, que s'aixeca quan va ser la mateixa AEAT la que va estar inaccessible i es va haver de declarar la incidència — es conserva fins i tot després d'una acceptació posterior, a efectes d'auditoria.

Cap d'aquests tres valors — el comptador d'intents, el reintent programat següent i la marca d'incidència — no s'exposa a l'objecte registre de la v1. Governen el comportament que observes, però avui no els pots llegir per l'API pública. El que sí que pots observar és l'estat mateix, transmitted_at i la cronologia d'auditoria del registre via GET /v1/verifactu/records/{id}/activities. No construeixis al teu client un model endevinat de la planificació de reintents: consulta l'estat.

Reintentar o esmenar

Totes dues operacions actuen sobre un registre que ja existeix. No són intercanviables.

Reintentar a cegues consumeix el pressupost de reintents tècnics. L'esmena no: és una correcció manual deliberada amb dades noves, la norma no li posa límit i executar-la reinicia la ronda de transmissió — el comptador d'intents torna a zero i la retransmissió automàtica del contingut corregit recupera el pressupost íntegre (BR-VFC-006, BR-VFC-020).

L'esmena regenera el payload però hi incrusta la huella original, la baula de cadena original i la marca de temps de generació original, perquè són les que permeten a l'AEAT casar el reenviament amb el registre que va rebutjar. Abans de persistir 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 modifica 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).

Quan un reenviament segueix un rebuig, la declaració regenerada porta a més les marques AEAT que declaren que l'enviament anterior va ser rebutjat i que, per tant, el registre no va arribar mai a registrar-se. Cap de les dues no entra al càlcul de la huella, així que declarar-les no pertorba la cadena (BR-VFC-026).

Pots verificar la cadena sencera pel teu compte amb GET /v1/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 — política de reintents: retrocés exponencial, intents limitats per ronda, i el límit que explícitament no aplica a l'esmena.
• 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 rebutjats, guarda de la huella i reinici de la ronda de transmissió.
• BR-VFC-026 — les marques AEAT per a un reenviament després d'un rebuig.
• 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.