Alta automàtica a VeriFactu
No hi ha cap botó d'«enviar a l'AEAT». L'alta es crea quan la factura surt de draft — aquesta és la llista de comportes que decideixen si passa, i les úniques palanques manuals que existeixen després.
Qui integra venint d'altres plataformes de facturació busca l'operació que envia una factura a l'Administració tributària, no la troba i dona per fet que la funcionalitat falta. No falta: l'alta no és un pas que executis tu. El registre es crea com a conseqüència d'emetre la factura, i el transmet una canonada en segon pla.
Aquesta pàgina respon a «per què la meva factura no ha arribat a l'AEAT?», que gairebé sempre és una de les comportes de baix i no una fallada.
Quan aplica
A tota factura que surt de draft en una empresa amb l'activació de VeriFactu
efectiva. En concret, l'alta es crea en la transició a sent — incloses les
factures que neixen ja emeses: rectificatives, substitutives F3, generacions de
recurrents i creacions que passen status: sent directament.
L'etapa draft queda deliberadament fora del mecanisme. Un esborrany no té número
definitiu, ni snapshot congelat del destinatari, ni existència fiscal; no se'n
declara res.
Les comportes, en l'ordre en què s'avaluen
Interruptor d'emergència de la instància. Una bandera global pot desactivar VeriFactu per a tota la instal·lació. És un interruptor d'emergència, mai una activació: tota sola no habilita res.
Activació per empresa. Aquesta és la que controles tu. Ve desactivada de
fàbrica en un compte acabat de crear — una empresa nova no dona d'alta les
seves factures fins que algú activa VeriFactu. L'activació efectiva és
instància I empresa (BR-VFC-025).
Llegeix-la amb
GET /v1/verifactu/config:
el camp enabled ja és el valor efectiu, no la bandera crua de l'empresa.
Mode de funcionament. Amb l'activació posada, l'empresa encara tria entre
transmetre i no transmetre. En mode no_verifactu els registres encadenats es
continuen generant i desant en local — el mode canvia la transmissió, no
l'encadenament — i han de quedar disponibles per a inspecció, però no s'envia res
en temps real (BR-VFC-018, RD 1007/2023 art. 16).
Excepció de la importació històrica. Les factures carregades per la
importació massiva d'històric previ a l'adhesió porten una marca transitòria que
fa que els gestors de VeriFactu retornin sense crear cap registre
(BR-INV-011, BR-VFC-009). Sense ella,
importar anys d'històric declararia milers d'altes amb dates d'expedició
anteriors a la incorporació de l'empresa al sistema. La marca la força
l'importador i no s'exposa als endpoints ordinaris de creació — no la pots
activar des de l'API pública.
Certificat actiu. Signar requereix el certificat FNMT propi de l'empresa. Si
no n'hi ha cap, o està caducat, revocat, o el seu NIF no coincideix amb el de
l'empresa, la creació de l'alta falla amb un error de regla de negoci. Comprova
has_active_certificate a l'endpoint de configuració abans de sortir a
producció.
Si passen les cinc, el registre es crea, s'encadena i s'encua per transmetre. Que
la cua transmeti automàticament és al seu torn un ajust d'instància, exposat en
només lectura com a auto_transmit a l'endpoint de configuració.
Què envia l'API
Res que escriguis tu. No hi ha cos de petició per a «enviar», ni cap camp a
POST /v1/invoices que
ho controli. El que sí que controles és quan s'emet la factura, i d'aquí se'n
deriva tota la resta:
- Crea la factura com a esborrany i després emet-la amb
POST /v1/invoices/{id}/sendoPOST /v1/invoices/{id}/mark-sent. - O crea-la i emet-la de manera atòmica passant
options.issue_directlya la crida de creació.
Com que el camí de «crear i emetre en una sola crida» emet alhora un esdeveniment
de creació i un d'emissió, dos gestors competeixen per crear la mateixa alta. La
comanda és idempotent per factura: el segon detecta l'alta existent i no fa
res en silenci, de manera que existeix exactament un registre per factura
(BR-VFC-008). No cal que dedupliquis pel teu costat.
L'única via d'escapament explícita
Sí que existeix una operació que força la creació d'una alta per a una factura
ja emesa:
POST /v1/invoices/{id}/verifactu,
scope verifactu:write. Crea l'alta i encua la seva transmissió, responent 201
amb el registre nou.
Existeix per al cas en què una factura es va emetre amb una comporta tancada —un certificat que encara no s'havia pujat, per exemple— i vols l'alta així que la comporta s'obre. No és un reenviament:
| Situació | Resposta |
|---|---|
| La factura ja té una alta | 422 verifactu_already_submitted |
| La factura continua en esborrany, VeriFactu està desactivat a la instància, o el certificat falta, està caducat, revocat o amb un NIF que no casa | 422 verifactu_not_eligible |
| La factura no existeix, o pertany a una altra empresa | 404 invoice_not_found |
curl -X POST https://api.factuarea.com/v1/invoices/0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42/verifactu \
-H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"Les úniques palanques manuals sobre un registre que ja existeix
Creada l'alta, exactament dues operacions hi actuen, i totes dues s'expliquen a Estats d'enviament VeriFactu:
retry— reenvia sense canvis la declaració emmagatzemada, per a fallades tècniques.subsanar— regenera la declaració a partir de dades mestres corregides, per a rebutjos de l'AEAT.
No existeix cap operació que retransmeti un registre acceptat. L'acceptació és terminal per norma.
Activar és un compromís, no un interruptor
Encendre VeriFactu és asimètric, i una integració que ho tracti com un
interruptor reversible ensopegarà amb un 422 en producció.
Passar al mode verificable sempre està permès. Tornar enrere està bloquejat
fins al 31 de desembre de l'any en què es va activar
(BR-VFC-001, BR-VFC-023, RD 1007/2023
art. 13). La integritat d'una cadena declarada a l'AEAT en temps real no es pot
degradar a programari autocertificat a mitjan exercici fiscal.
Hi ha una escapatòria deliberada: mentre la cadena continuï buida —l'empresa no ha emès ni un sol registre de facturació en cap estat— l'empresa pot canviar d'idea i tornar enrere, i el bloqueig s'aixeca. El primer registre emès, encara que sigui un de rebutjat o amb error, arma el bloqueig fins a final d'any. Apagar la bandera d'activació per empresa ho impedeix la mateixa guarda, així que no serveix per esquivar el compromís.
GET /v1/verifactu/config exposa is_locked_until perquè ho puguis ensenyar als
teus usuaris abans que es comprometin.
Sandbox i producció no són intercanviables
Cada empresa opera contra un únic entorn AEAT, exposat com a environment tant a
l'objecte de configuració com a cada registre. Un CSV obtingut contra l'entorn de
proves de l'AEAT no és una alta: els CSV de proves porten un prefix
recognoscible, i una base de dades de producció que en contingui significa que es
va simular alguna cosa que s'hauria d'haver transmès
(BR-VFC-017).
La regla que et protegeix és que el sistema no ha de caure mai en simulació de
manera silenciosa — un endpoint inaccessible ha d'aflorar com a estat tècnic
error, no com una acceptació fabricada. Quan concilies, tracta el camp
environment com a part de la identitat del registre.
Què surt al PDF
L'alta automàtica en si no afegeix res al document; el que s'imprimeix depèn de
l'existència d'un registre, no de com es va crear. Així que existeix un
registre, la factura porta el bloc QR legal (BR-VFC-015), i la
llegenda sota el codi difereix segons el mode de funcionament: la marca curta
VERI*FACTU en mode verificable, i la frase completa que declara que la factura
és verificable a la seu electrònica de l'AEAT en l'altre.
Una factura importada amb l'excepció d'històric no té registre i per tant no imprimeix QR. És el que toca: les factures anteriors a l'adhesió no són verificables a l'AEAT.
Què arriba a l'AEAT
Una declaració d'alta per factura emesa, encadenada al registre anterior de l'empresa, més una declaració d'anul·lació si la factura s'anul·la després (vegeu Anul·lar o rectificar). No es transmet res més com a conseqüència d'emetre.
En mode no_verifactu no arriba res a l'AEAT en temps real; l'empresa conserva
la cadena local per a inspecció i el sistema registra periòdicament resums dels
seus propis esdeveniments operatius, que la norma tracta com a evidència separada
(BR-VFC-018).
Traçabilitat
Derivat de les regles de domini del backend de Factuarea:
BR-VFC-001— l'adhesió al mode verificable és irrevocable fins a final d'any natural, amb l'excepció de la cadena buida.BR-VFC-008— idempotència: una alta per factura, fins i tot quan el flux de crear i emetre dispara dos esdeveniments.BR-VFC-009— l'excepció de la importació històrica, vista des de VeriFactu.BR-VFC-015— el bloc QR i les seves dues llegendes.BR-VFC-017— la frontera entre sandbox i producció, i la prohibició de simular en silenci.BR-VFC-018— modeno_verifactu: cadena local, resums d'esdeveniments, sense transmissió en temps real.BR-VFC-023— el canvi de mode asimètric i el bloqueig fins a final d'any, inclosa la guarda que impedeix esquivar-lo amb la bandera d'activació.BR-VFC-025— activació per empresa, desactivada de fàbrica, valor efectiu com ainstància I empresa.BR-INV-011— l'excepció de la importació històrica, vista des de la facturació.