Esmena de registres VeriFactu
Corregeix i reenvia registres de facturació VeriFactu rebutjats per l'AEAT — quan aplica l'esmena (subsanación), quan necessites una anul·lació o una rectificativa, i el flux exacte de l'API.
Quan l'AEAT rebutja un registre de facturació VeriFactu per un error de
dades (registre amb status: rejected), la normativa VeriFactu (Reial
decret 1007/2023, art. 11) et permet esmenar (subsanar) el registre:
reenviar el mateix registre amb el contingut corregit. No és una factura
nova, ni una rectificativa, ni una anul·lació — el mateix registre rebutjat es
repara i es transmet de nou.
POST /v1/verifactu/records/{record}/subsanar- Scope:
verifactu:write - Body de la request: cap — el contingut esmenable es regenera al servidor des de la factura origen i les dades mestres actuals.
- Resposta:
202 Accepted— el reenviament s'encua i s'envia a l'AEAT en uns segons.
L'esmena mai no recalcula la huella original, la baula d'encadenament amb el registre anterior ni el segell de generació original: l'AEAT casa el reenviament amb el registre rebutjat precisament perquè es conserven. No hi ha límit d'intents d'esmena — el límit de reintents tècnic aplica només als reintents cecs de fallades de transmissió.
Quan fer-la servir — i quan no
| Situació | Què fer |
|---|---|
Registre rejected per l'AEAT per un error de dades — NIF del destinatari no identificat al cens, raó social incorrecta, problemes a la descripció… | Esmena. Corregeix les dades al seu origen i crida POST …/subsanar. |
Registre en error (fallada tècnica de transmissió: timeout, AEAT caiguda). | Res — la transmissió es reintenta automàticament (reintent manual disponible). L'esmena respon record_not_rejected. |
Registre accepted però la factura porta dades incorrectes. | Una factura rectificativa (R1–R5). Un registre acceptat és immutable — l'esmena respon record_not_rejected. |
| La correcció canvia un camp de la huella: NIF de l'emissor, sèrie + número, data d'expedició, tipus de factura, quota total o import total. | Anul·lació + registre nou (factura nova o rectificativa). L'esmena respon requires_annulment sense modificar res. |
El flux
Detecta el rebuig. Subscriu-te a l'esdeveniment de webhook
invoice.verifactu_failed, o consulta el
llistat de registres
cercant status: rejected. El registre porta el detall del rebuig de l'AEAT.
Corregeix les dades al seu origen. El contingut reenviat es regenera des de la factura origen i les dades mestres actuals — p. ex. corregeix el NIF o la raó social del client i els valors nous es recullen automàticament. El snapshot legal congelat de la factura es refresca deliberadament perquè el PDF coincideixi amb el que rep l'AEAT.
Crida l'endpoint. El registre torna a entrar a la cua de transmissió amb una ronda d'intents nova:
curl -X POST https://api.factuarea.com/v1/verifactu/records/0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42/subsanar \
-H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"Resposta (202):
{
"data": {
"id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
"message": "Subsanación encolada. El registro se reenviará a la AEAT en unos segundos."
}
}Vigila el resultat. El registre es transmet de nou i acaba en accepted
— o en rejected un altre cop si les dades continuen malament, i en aquest
cas pots tornar 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 concreta la causa:
{
"error": {
"type": "invalid_request_error",
"code": "business_rule_violation",
"subcode": "record_not_rejected",
"message": "El registro #842 no está rechazado por la AEAT (estado actual: accepted). Solo los registros rechazados 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 està en rejected (està acceptat, pendent, enviat — o en error tècnic, que ja 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 d'alta, o no té factura origen des de la qual regenerar. |
| 403 | insufficient_scope | La key no té el scope verifactu:write. |
Evita el rebuig abans que passi
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/clients/census-verification
abans d'emetre-li factures VeriFactu — així l'esmena es queda en el que ha
de ser: una xarxa de seguretat, no una rutina.
Verificació censal AEAT
Contrasta el parell raó social + NIF de la teva empresa — i el dels teus clients — contra el cens de l'AEAT abans d'emetre factures VeriFactu — estats deterministes, NIFs màgics del sandbox i comportament fail-open.
Facturació FACe (B2G)
Envia factures FacturaE 3.2.2 a FACe — codis DIR3, XML signat XAdES-EPES, estats de tramitació, anul·lació, simulació en sandbox i l'scope facturae:write.