Compliment del component de l'integrador

Quan un caixer, un punt de venda o un ERP emet factures a través de l'API de Factuarea, en cada venda intervenen dues peces de programari: Factuarea, que genera, numera, encadena i remet el registre de facturació, i el teu component, que el demana i imprimeix o mostra la factura i el seu QR. Cadascuna té la seva pròpia declaració responsable.

Aquesta pàgina és la lectura que fa Factuarea de la FAQ de desenvolupadors de l'AEAT de 4 de desembre de 2025 (secció 5) i de l'Ordre HAC/1177/2024, escrita per ajudar-te a preparar la teva integració. És orientativa: el productor del component és qui signa, i respon de, la seva declaració. No substitueix l'assessorament legal.

Quan aplica

El teu programari és un component quan, en cada operació, crida l'API de Factuarea per obtenir la factura i el seu registre de facturació i no genera, numera, encadena, signa ni remet registres de facturació propis. El flux del cobrament desatès n'és el cas típic.

Si el teu programari sí que genera els seus propis registres, és en si mateix un sistema de facturació amb obligacions pròpies i aquesta pàgina no aplica.

Qui fa què

El que ha de fer el teu component

1. No lliurar mai una factura sense el seu registre. Una operació està facturada quan l'API ha respost amb la factura i verifactu.status: "registered". Si la resposta és failed, encara no: tracta la venda com a pendent i repeteix la crida amb el mateix external_id (consulta quan verifactu.status és failed).
2. No alterar el registre ni el QR que has rebut. Imprimeix qr_png_base64 i huella tal com arriben. No els recalculis ni canviïs imports, número o data després de la resposta. Si una xifra és errònia, la manera de corregir-la és una factura rectificativa o una anul·lació, mai una edició al terminal.
3. Mantenir la connexió indefectible. Crida l'API en cada operació, sense numeració local i sense un pla B que emeti sense resposta. Sense connexió el terminal no emet: Factuarea no té mode sense connexió (consulta sense connexió no hi ha factura).
4. Tractar els errors i els reintents. Reenvia la mateixa petició, amb el mateix external_id, fins a rebre una resposta definitiva. Tracta 409 resource_locked com «torna-ho a provar d'aquí a uns segons», 409 idempotency_key_reused com un error en els teus identificadors i un 422 com alguna cosa que cal corregir abans de repetir. Desa el request_id de cada fallada per a suport. Consulta Errors que el terminal ha de tractar.
5. Mostrar o imprimir el QR com exigeix l'especificació. Entre 30 × 30 mm i 40 × 40 mm, nivell de correcció d'errors M, almenys 2 mm de marge en blanc, el rètol QR tributario: a sobre i la legend de la resposta a sota, amb una lletra no més petita que la de la resta de dades, al principi del document. Consulta Mostrar el QR. El PDF de tiquet (GET /v1/invoices/{invoice}/pdf?format=ticket_80) ja el maqueta.
6. Declarar el que és. El productor del teu component emet una declaració responsable que indica, entre el seu contingut, que crida l'API de Factuarea i en quina versió.

La teva pròpia declaració responsable

La declaració segueix el contingut de l'article 15 de l'Ordre, en aquest ordre. L'última columna indica què aplica a un component:

Afegeix un annex que digui com s'integra el component amb Factuarea: quina API crida, en quina versió, i que no genera, numera, encadena, signa ni remet res. La versió de Factuarea és a la seva pròpia declaració, que llegeixes amb GET /v1/verifactu/declaracion-responsable (system_name, system_id, version); fixa la versió de l'API amb la capçalera Factuarea-Version (consulta Versionat).

El model següent és orientatiu: completa els camps entre claudàtors sota la teva responsabilitat i fes servir el text literal de l'Ordre per a l'apartat k). Està en castellà, l'idioma de la declaració que emet la mateixa Factuarea i que llegeix l'administració tributària espanyola.

DECLARACIÓN RESPONSABLE DEL SISTEMA INFORMÁTICO DE FACTURACIÓN

a) Nombre del sistema informático: [nombre del componente]
b) Código identificador del sistema informático: [código de dos caracteres]
c) Identificador completo de la versión: [versión del componente]
d) Componentes hardware y software, y breve descripción: [terminal, sistema
   operativo y aplicación]. El componente atiende el cobro en terminales
   desatendidos e invoca de forma indefectible, en cada operación, la API pública
   del sistema informático de facturación Factuarea para obtener la factura, su
   registro de facturación y su código QR, que muestra o imprime tal como los recibe.
e) Solo puede funcionar como VERI*FACTU: [sí / no]. El componente no genera
   registros de facturación.
f) Permite su uso por varios obligados tributarios: [sí / no]
g) Tipos de firma de los registros no VERI*FACTU: no aplica. El componente no
   genera ni firma registros de facturación.
h) Nombre o razón social del productor: [nombre o razón social]
i) NIF del productor: [NIF]
j) Dirección postal completa del productor: [dirección]
k) [Declaración literal de cumplimiento que recoge el artículo 15.1.k) de la
   Orden HAC/1177/2024.]
l) [Localidad y país], [día] de [mes] de [año]

ANEXO. Integración con el sistema informático de facturación Factuarea

1. El componente invoca la API pública de Factuarea (https://api.factuarea.com/v1)
   mediante POST /v1/invoices en cada operación. Versión del sistema informático
   de Factuarea: [versión de su declaración responsable vigente]. Versión de la
   API: [valor de Factuarea-Version].
2. El componente no genera, numera, encadena, firma ni remite registros de
   facturación: lo hace en exclusiva el sistema informático de Factuarea.
3. El componente no entrega ninguna factura sin el registro de facturación que
   devuelve la API, y no altera ni el registro ni el código QR recibidos.
4. Sin conexión con la API, el componente no emite facturas.
5. Ante un fallo o una respuesta dudosa, el componente repite la misma petición con
   el mismo identificador externo hasta recibir una respuesta definitiva.

Llista de comprovació abans de sortir a producció

• El component crida l'API en cada operació i no té numeració local.
• Envia un external_id estable per venda i el desa abans de la primera crida.
• Tracta verifactu.status: "failed" com una venda pendent i repeteix la crida.
• Imprimeix qr_png_base64 i huella tal com arriben, amb el rètol i la llegenda, a la mida i amb el marge exigits.
• No emet sense connexió.
• Tracta 409, 422, 429 i 5xx com es descriu a Errors que el terminal ha de tractar.
• El seu productor ha signat la seva pròpia declaració responsable, que indica que crida l'API de Factuarea i en quina versió.
• Has provat tot el flux amb una clau fact_test_ (consulta Mode de prova i sandbox).