Cumplimiento del componente del integrador

Cuando un cajero, un punto de venta o un ERP emite facturas a través de la API de Factuarea, en cada venta intervienen dos piezas de software: Factuarea, que genera, numera, encadena y remite el registro de facturación, y tu componente, que lo pide e imprime o muestra la factura y su QR. Cada una tiene su propia declaración responsable.

Esta página es la lectura que hace Factuarea de la FAQ de desarrolladores de la AEAT de 4 de diciembre de 2025 (sección 5) y de la Orden HAC/1177/2024, escrita para ayudarte a preparar tu integración. Es orientativa: el productor del componente es quien firma, y responde de, su declaración. No sustituye al asesoramiento legal.

Cuándo aplica

Tu software es un componente cuando, en cada operación, llama a la API de Factuarea para obtener la factura y su registro de facturación y no genera, numera, encadena, firma ni remite registros de facturación propios. El flujo del cobro desatendido es el caso típico.

Si tu software sí genera sus propios registros, es en sí mismo un sistema de facturación con obligaciones propias y esta página no aplica.

Quién hace qué

Lo que debe hacer tu componente

1. No entregar nunca una factura sin su registro. Una operación está facturada cuando la API ha respondido con la factura y verifactu.status: "registered". Si la respuesta es failed, todavía no: trata la venta como pendiente y repite la llamada con el mismo external_id (consulta cuando verifactu.status es failed).
2. No alterar el registro ni el QR que recibiste. Imprime qr_png_base64 y huella tal como llegan. No los recalcules ni cambies importes, número o fecha después de la respuesta. Si una cifra es errónea, la forma de corregirla es una factura rectificativa o una anulación, nunca una edición en el terminal.
3. Mantener la conexión indefectible. Llama a la API en cada operación, sin numeración local y sin un plan B que emita sin respuesta. Sin conexión el terminal no emite: Factuarea no tiene modo sin conexión (consulta sin conexión no hay factura).
4. Tratar los errores y los reintentos. Reenvía la misma petición, con el mismo external_id, hasta recibir una respuesta definitiva. Trata 409 resource_locked como «vuelve a intentarlo en unos segundos», 409 idempotency_key_reused como un fallo en tus identificadores y un 422 como algo que hay que corregir antes de repetir. Guarda el request_id de cada fallo para soporte. Consulta Errores que el terminal debe tratar.
5. Mostrar o imprimir el QR como exige la especificación. Entre 30 × 30 mm y 40 × 40 mm, nivel de corrección de errores M, al menos 2 mm de margen en blanco, el rótulo QR tributario: encima y la legend de la respuesta debajo, con una letra no menor que la del resto de los datos, al principio del documento. Consulta Mostrar el QR. El PDF de ticket (GET /v1/invoices/{invoice}/pdf?format=ticket_80) ya lo maqueta.
6. Declarar lo que es. El productor de tu componente emite una declaración responsable que indica, entre su contenido, que llama a la API de Factuarea y en qué versión.

Tu propia declaración responsable

La declaración sigue el contenido del artículo 15 de la Orden, en este orden. La última columna indica qué aplica a un componente:

Añade un anexo que diga cómo se integra el componente con Factuarea: qué API llama, en qué versión, y que no genera, numera, encadena, firma ni remite nada. La versión de Factuarea está en su propia declaración, que lees con GET /v1/verifactu/declaracion-responsable (system_name, system_id, version); fija la versión de la API con la cabecera Factuarea-Version (consulta Versionado).

El modelo siguiente es orientativo: completa los campos entre corchetes bajo tu responsabilidad y usa el texto literal de la Orden para el apartado k). Está en castellano, el idioma de la declaración que emite la propia Factuarea y que lee la administración tributaria española.

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.

Lista de comprobación antes de salir a producción

• El componente llama a la API en cada operación y no tiene numeración local.
• Envía un external_id estable por venta y lo guarda antes de la primera llamada.
• Trata verifactu.status: "failed" como una venta pendiente y repite la llamada.
• Imprime qr_png_base64 y huella tal como llegan, con el rótulo y la leyenda, al tamaño y con el margen exigidos.
• No emite sin conexión.
• Trata 409, 422, 429 y 5xx como se describe en Errores que el terminal debe tratar.
• Su productor ha firmado su propia declaración responsable, que indica que llama a la API de Factuarea y en qué versión.
• Probaste todo el flujo con una clave fact_test_ (consulta Modo de prueba y sandbox).