Esmena de registres VeriFactu

Quan l'AEAT rebutja un registre de facturació VeriFactu per un error de dades (registre amb status: rejected), o quan un registre acceptat resulta portar dades errònies per a les quals les regles de facturació no exigeixen una factura rectificativa, la normativa VeriFactu (Reial decret 1007/2023, art. 11) et permet esmenar-lo (subsanar). L'AEAT no admet una edició al seu lloc: la correcció és sempre un registre nou, i l'original queda intacte (descripció dels serveis web de l'AEAT, §9.1.2 i §9.1.3). No és una factura nova, ni una rectificativa, ni una anul·lació.

POST /v1/companies/{company}/verifactu/records/{record}/subsanar

Scope: verifactu:write
Cos de la petició: cap — el contingut es regenera al servidor a partir de la factura d'origen i de les dades mestres actuals.
Resposta: 202 Accepted amb data.id, l'id del registre nou, que és el que es transmet. El registre nou comença en pending; llegeix-lo amb GET /v1/companies/{company}/verifactu/records/{id}.

El registre nou té la mateixa clau de factura (NIF de l'emissor, sèrie, número i data) que el que corregeix, la seva pròpia huella (huella) i la seva pròpia posició a la cadena, després de l'últim registre de l'empresa: la cadena no es reescriu mai. Sempre declara Subsanacion=S, i el seu RechazoPrevio depèn del cas: cap per a un registre acceptat (§9.1.2); X per a un registre rebutjat la factura del qual l'AEAT no té, perquè el registre rebutjat mai no va existir allà (§9.1.3); S per a una esmena rebutjada d'una factura que l'AEAT sí que té. No hi ha topall d'intents d'esmena.

Quan fer-la servir — i quan no

El mateix registre et diu si admet esmena: can_subsanar a l'objecte registre és true quan el registre és una alta, està acceptat, acceptat amb errors o rebutjat, és l'última alta de la seva factura i la factura no està anul·lada.

Situació	Què fer
Registre `rejected` per l'AEAT per un error de dades — NIF del destinatari no identificat al cens, nom del destinatari erroni, problemes de descripció…	Esmena. Corregeix la dada al seu origen i crida `POST …/subsanar`.
Registre `rejected` amb `aeat_error_code: SCHEMA_INVALID`: no complia l'esquema de l'AEAT i mai no es va enviar.	Esmena, després de corregir la dada culpable. No atura la resta de la cadena.
Registre `accepted` (o acceptat amb errors) amb un error de dades intern per al qual les regles de facturació no exigeixen una rectificativa.	Esmena: una alta nova succeeix l'acceptada.
Registre `accepted` i les regles de facturació exigeixen una rectificativa (un error que s'ha de corregir amb una factura rectificativa, una devolució, un import diferent…).	Una factura rectificativa (R1–R5).
Registre en `error` (fallada tècnica: timeout, AEAT caiguda) o `pending`.	Res — la transmissió es reintenta sola (reintent manual disponible). L'esmena respon `record_not_rejected`.
La correcció canvia un camp de la huella: NIF de l'emissor, sèrie + número, data d'emissió, tipus de factura, quota total o import total.	Anul·lació + registre nou (factura nova o rectificativa). L'esmena respon `requires_annulment` sense crear res.

El flux

Detecta-ho. Per a un rebuig, subscriu-te a l'esdeveniment de webhook invoice.verifactu_failed, o consulta el llistat de registres buscant status: rejected (o fes servir el filtre «requereix atenció» de l'aplicació). El registre porta el detall del rebuig de l'AEAT a aeat_error_code.

Corregeix la dada al seu origen. El registre nou es regenera a partir de la factura d'origen i de les dades mestres actuals — per exemple, corregeix el NIF o el nom registrat del client i els valors nous es recullen automàticament. El snapshot legal congelat de la factura es refresca a propòsit perquè el PDF coincideixi amb el que rep l'AEAT.

Crida l'endpoint. Un registre nou s'incorpora a la cua de transmissió de l'empresa:

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

Resposta (202):

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d11",
    "message": "Subsanación encolada. El registro se reenviará a la AEAT en unos segundos."
  }
}

data.id és el registre nou, mai el que vas enviar.

Observa el resultat. El registre nou es transmet i acaba accepted — o rejected una altra vegada si les dades continuen malament, i en aquest cas tornes a esmenar (no hi ha límit d'intents).

Errors

Les violacions de regla de negoci retornen 422 amb code: business_rule_violation i un subcode que assenyala la causa:

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "record_not_rejected",
    "message": "El registro no está rechazado ni aceptado por la AEAT (estado actual: pending). Solo los registros rechazados o aceptados admiten subsanación; para fallos técnicos usa el reintento."
  }
}

HTTP	`code` / `subcode`	Quan
404	`resource_not_found`	El registre no existeix o pertany a una altra empresa.
422	`business_rule_violation` / `record_not_rejected`	El registre no és ni acceptat ni rebutjat: és pendent, enviat — o en `error` tècnic, que cobreix el reintent automàtic.
422	`business_rule_violation` / `requires_annulment`	La correcció toca camps de la huella. Anul·la el registre i emet una factura nova o una rectificativa.
422	`business_rule_violation` / `record_not_subsanable`	El registre no és una alta; no és l'última alta de la seva factura (una esmena posterior ja la substitueix); la factura està anul·lada; o no té factura d'origen des de la qual regenerar.
403	`insufficient_scope`	La clau no té el scope `verifactu:write`.

Evita el rebuig des del principi

El rebuig de dades més freqüent és un destinatari que el cens de l'AEAT no identifica (rebuig 1239). Verifica el parell nom + NIF d'un client amb POST /v1/companies/{company}/contacts/census-verification abans d'emetre-li factures VeriFactu — així l'esmena continua sent el que ha de ser: una xarxa de seguretat, no una rutina.

Un camp de dades que no cap a l'esquema de l'AEAT ni tan sols arriba tan lluny: la factura no s'emet (422 verifactu_not_eligible, consulta Alta automàtica a VeriFactu).

Esmena de registres VeriFactu

Quan fer-la servir — i quan no

El flux

Errors

Evita el rebuig des del principi

En aquesta pàgina