Alta automàtica a VeriFactu

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 quan la factura s'emet — incloses les factures que neixen ja emeses: rectificatives, substitutives F3, generacions de recurrents i creacions que passen options.issue_directly. (Abans de la versió d'API 2026-10-01 una factura emesa es publica com a sent; consulta Versionat.)

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/companies/{company}/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.

Dades del registre vàlides. Abans d'emetre una factura, Factuarea comprova que el registre que generarà cap a l'esquema de l'AEAT: un nom de client de com a màxim 120 caràcters, un NIF espanyol de 9 caràcters, un número de factura d'ASCII imprimible de com a màxim 60 caràcters, com a molt 12 desglossaments fiscals, imports que càpiguen en 12 xifres enteres i 2 decimals. Si alguna cosa no hi cap, l'operació respon 422 verifactu_not_eligible amb el camp a error.param, la factura no s'emet i no es consumeix número. S'aplica a tota operació que emet una factura i a tota empresa amb VeriFactu activat. La taula de camps és a Facturació des de terminals desatesos.

Un certificat que pugui presentar o signar el registre. El que cal depèn del mode:

Mode VERI*FACTU. El certificat que remet els registres autentica la connexió amb l'AEAT; el registre en si no se signa. Si no hi ha un certificat utilitzable, o una representació activa en els modes de tercer, la factura sí que s'emet i el seu registre es genera, però neix bloquejat (MISSING_CERTIFICATE o MISSING_REPRESENTATION) i s'allibera quan puges el certificat o registres la representació. Consulta Registres bloquejats.
Mode NO VERI*FACTU amb VeriFactu activat. Cada registre se signa, i un registre només compta com a generat quan està signat. Sense un certificat de signatura utilitzable, l'operació que el generaria es rebutja abans d'executar-se: emetre, i també anul·lar, responen 422 verifactu_not_eligible amb subcode: signing_certificate_unavailable i error.param certificate, representation o system_certificate. La factura queda com estava. Afecta les vuit operacions que emeten o anul·len (create amb options, issue, send, mark-sent, corrective, substitute-simplified, annul i void); can-annul t'ho anticipa.
VeriFactu desactivat. No canvia res: una empresa que no ha activat VeriFactu emet i anul·la sense certificat, encara que el seu mode per defecte sigui no_verifactu.

Comprova has_active_certificate i presenter_certificate_status a l'endpoint de configuració abans de sortir a producció.

Si passen les sis, 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/companies/{company}/invoices que decideixi si es crea una alta. 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/companies/{company}/invoices/{id}/send o POST /v1/companies/{company}/invoices/{id}/mark-sent.
O crea-la i emet-la de manera atòmica passant options.issue_directly a la crida de creació.
O, des d'un terminal que necessita el QR a la mateixa resposta, passa options.register_verifactu: l'alta es genera de manera síncrona, abans de respondre, i la resposta porta la seva huella i el seu QR. Si no es pot generar (sense certificat, sense representació, rellotge desfasat) la factura queda emesa i el bloc respon status: failed; repetir el mateix external_id la completa. Consulta Facturació des de terminals desatesos.

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/companies/{company}/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/companies/{company}/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 tres operacions hi actuen, i totes s'expliquen a Estats d'enviament VeriFactu:

retry — programa el lot de l'empresa perquè un registre fallit hi surti, per a fallades tècniques. No hi ha límit d'intents.
retry-blocked — reactiva alhora tots els registres bloquejats de l'empresa, després que hagis resolt el que els bloquejava. Respon 202 amb data.reactivated.
subsanar — genera un registre nou que corregeix un d'acceptat o un de rebutjat; l'original no s'edita mai.

No existeix cap operació que retransmeti un registre acceptat ni que l'editi al seu lloc. L'acceptació és terminal per a aquest registre per norma; un error de dades en ell es corregeix amb un registre nou (subsanar), o amb una factura rectificativa quan les regles de facturació l'exigeixen.

Com arriben els registres a l'AEAT

La remissió segueix l'article 16 de l'Ordre HAC/1177/2024. No la governes tu, però explica el que veuràs en un registre i a les estadístiques.

Lots, en ordre. Els registres d'una empresa s'envien junts, sense barrejar-los mai amb els d'una altra, fins a 1.000 per enviament i sempre en l'ordre de la cadena: un registre mai no avança un d'anterior. Només hi ha un enviament en vol per empresa.
Temps d'espera. A cada resposta l'AEAT indica quant esperar abans del següent enviament (TiempoEsperaEnvio). Factuarea ho respecta (60 segons si l'AEAT no n'ha indicat cap), tret que ja hi hagi 1.000 registres esperant. Un registre creat dins de la finestra espera el següent enviament.
Resposta per registre. Acceptat, acceptat amb errors (el registre queda acceptat, amb un avís) o rebutjat. L'error 3000 de l'AEAT, «registre duplicat», compta com a confirmació que l'AEAT l'ha rebut.
Reintents sense topall. Si un enviament no obté resposta, obté una fallada de servidor o falla la xarxa, els seus registres continuen pendents, marcats com a incidència (Incidencia=S al següent enviament), i es reintenten amb intervals creixents —1, 5, 15, 30 minuts i després cada 55— de manera que mai no passi més d'una hora entre dos intents, sense nombre màxim d'intents, mentre duri la incidència. Els registres generats entretant esperen darrere dels anteriors.
Avís de pendents. GET /v1/companies/{company}/verifactu/stats informa de pending_incident_count (registres que encara esperen arribar a l'AEAT), blocked_incident_count (d'aquests, els bloquejats) i oldest_pending_at. Els filtres de la consulta no els afecten. L'aplicació mostra el mateix avís, i el correu de resum diari l'inclou.
Un registre que no cap a l'esquema es genera rejected amb aeat_error_code: SCHEMA_INVALID i mai no s'envia: l'AEAT rebutja un enviament sencer quan un registre incompleix el seu esquema, així que es detecta abans. El corregeixes amb una subsanar, i no atura la resta de la cadena.
Les empreses de prova (claus fact_test_) mai no remeten.

Registres bloquejats

Un registre en error sense reintent automàtic està bloquejat: alguna cosa necessita la teva acció, no es reintenta sol i atura els registres que van darrere. El registre ho indica amb is_blocked: true i la causa a block_reason:

`block_reason`	Què falta
`MISSING_CERTIFICATE`	L'empresa no té un certificat utilitzable (absent, caducat, revocat o d'un altre NIF).
`MISSING_REPRESENTATION`	El mode és de tercer i no hi ha una representació activa del tipus que necessita.
`PRESENTER_NOT_ENABLED`	L'AEAT diu que el presentador no està habilitat (`4112` o `3003`).
`SUBMISSION_REJECTED`	L'AEAT va rebutjar l'enviament per una fallada del costat del client.

aeat_error_code porta l'últim codi de l'AEAT (o l'intern). Una cinquena causa, SYSTEM_CERTIFICATE_UNAVAILABLE (el certificat de Factuarea en els modes de tercer), és del costat de Factuarea: no bloqueja i el registre es reintenta sol.

Resoldre la causa allibera els registres per si sol: pujar o activar un certificat, registrar una representació o canviar el mode reactiva el que aquest succés pot alliberar. Per alliberar-los tots a mà, crida retry-blocked.

Remetre a través de Factuarea: els modes de tercer

Per defecte cada empresa remet amb el seu propi certificat. Una empresa pot, en canvi, autoritzar Factuarea a remetre en nom seu, per no lliurar el seu certificat. El mode és remission_mode, que es llegeix a GET /v1/companies/{company}/verifactu/config i es canvia amb PATCH /v1/companies/{company}/verifactu/settings:

`remission_mode`	Qui remet	Representació necessària
`own_certificate` (per defecte)	L'empresa, amb el seu certificat.	Cap.
`social_collaborator`	Factuarea, com a col·laborador social.	L'annex I signat de la Resolució de 18-12-2024 (`social_collaboration_annex_i`).
`power_of_attorney`	Factuarea, a l'empara d'un apoderament.	Un apoderament inscrit a l'AEAT (`aeat_power_of_attorney`).

social_collaborator només està disponible mentre l'acord de col·laboració social amb l'AEAT estigui en vigor a la instància: comprova social_collaborator_available. Fins aleshores, power_of_attorney cobreix el mateix cas.

La representació es registra amb POST /v1/companies/{company}/verifactu/representation (multipart/form-data: kind, signer_name, signer_tax_id, granted_on, el PDF document o, per a un apoderament, power_of_attorney_reference, i un valid_until opcional), es llegeix amb GET i es revoca amb DELETE (reason opcional de 3 a 500 caràcters). Convé saber:

Només hi ha una representació vigent. Registrar-ne una altra revoca l'anterior, que es conserva a l'historial; el document signat es custodia xifrat i mai no es retorna. Revocar és definitiu i retorna l'empresa a own_certificate.
Vigència. valid_until és l'últim dia (hora de Madrid) i no pot superar cinc anys des de granted_on. Se t'avisa 30 i 7 dies abans i en caducar. Una representació caducada es continua retornant (is_expired: true) però ja no habilita la remissió: els registres nous queden bloquejats amb MISSING_REPRESENTATION fins que en registris una altra.
El mode segueix la representació. Registrar una representació de l'altre tipus mentre l'empresa remet per un tercer mou el mode al que aquest tipus necessita, o de tornada a own_certificate si aquest mode no es pot fer servir. Amb own_certificate, registrar no canvia res: canvia amb PATCH …/settings, que exigeix una representació activa (422 representation_required).
L'emissor és sempre l'empresa. Qui presenti el lot, cada registre porta el NIF i el nom de l'empresa, mai els del certificat.
Presentador. En mode NO VERI*FACTU els registres se signen amb el certificat del presentador: el propi de l'empresa o, amb una representació activa, el de Factuarea.

Cada registre, revocació i caducitat d'una representació, i cada canvi de mode, queden auditats.

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/companies/{company}/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. Els registres van en els lots que descriu Com arriben els registres a l'AEAT, i una factura simplificada qualificada viatja com una F1 marcada amb FacturaSimplificadaArt7273 (consulta Factures simplificades o completes).

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 — mode no_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 a instància I empresa.
BR-INV-011 — l'excepció de la importació històrica, vista des de la facturació.

Alta automàtica a VeriFactu

En aquesta pàgina