Cómo integrar Verifactu en tu ERP mediante API

Para cumplir Verifactu con un software que ya factura hay dos caminos: implementar el protocolo completo de la AEAT (XML, encadenamiento, certificados, control de flujo — meses de trabajo y mantenimiento perpetuo) o delegarlo en una API intermediaria y reducir el problema auna llamada HTTP en el punto de emisión. Esta guía recorre el segundo camino de principio a fin, con los ejemplos reales de la API de FactuBridge.

La arquitectura en una frase

Tu ERP sigue siendo el dueño de la factura; la API es el módulo que la convierte en un registro Verifactu. En el momento en que hoy «confirmas» la factura, llamas a POST /v1/create con los datos en JSON y recibes en la misma respuesta la huella encadenada, el QR y la URL de cotejo. La remisión a la AEAT, el certificado y los reintentos ocurren al otro lado.

# En tu ERP, donde hoy confirmas la factura:
def confirmar_factura(factura):
    factura.validar()                      # tu lógica actual
    registro = factubridge.create(factura) # ← la línea nueva
    factura.qr = registro.qr
    factura.huella = registro.huella
    factura.marcar_emitida()
    generar_pdf(factura)                   # con el QR incrustado

Paso 1 — El punto de emisión

Localiza el único sitio de tu código donde una factura pasa de borrador a emitida. Ahí va la llamada. La URL base del sandbox essandbox.factubridge.es; la de producción,api.factubridge.es. Su API key te la entregamos al validar la integración:

POST $BASE_URL/create
Authorization: Bearer $API_KEY
Content-Type: application/json

{
  "serie": "A",
  "numero": "2026-0001",
  "fecha_expedicion": "01-10-2026",
  "tipo_factura": "F1",
  "descripcion": "Servicios de consultoría — octubre 2026",
  "nif": "B87654321",
  "nombre": "CLIENTE EJEMPLO SL",
  "lineas": [
    {
      "base_imponible": "1000.00",
      "tipo_impositivo": "21.00",
      "cuota_repercutida": "210.00"
    }
  ],
  "importe_total": "1210.00"
}

{
  "uuid": "9b2e7c1a-4f6d-4c1e-9a3b-2f8e5d7c0a11",
  "estado": "Pendiente",
  "url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?...",
  "qr": "iVBORw0KGgoAAAANSUhEUgAA...",   // PNG en Base64, listo para el PDF
  "huella": "3AD5CA54A0DE383B0C1F79E1B2C4D6E8..."
}

Tres decisiones de diseño que conviene tomar bien desde el principio:

• Emisión única: toda factura debe salir por este circuito. Si tu software deja «imprimir sin confirmar» o editar una factura emitida, eso es lo que hay que cerrar — es además requisito de tu declaración responsable.
• Persistencia: guarda uuid, huella y qr junto a la factura.
• Fallos de red: si la llamada se corta, reintenta sin miedo: un reenvío de la misma factura devuelve 409 con el registro original (huella y QR incluidos), así que el reintento es idempotente.

Paso 2 — El QR en la factura

El campo qr es un PNG en Base64: se incrusta directamente en la plantilla del PDF o del ticket. El reglamento pide que se imprima con un tamaño de 30×30 a 40×40 mm, al comienzo de la factura, acompañado de la leyenda de factura verificable («VERI*FACTU»). Es el único cambio visible para el cliente final.

Paso 3 — El resultado de la AEAT

La respuesta de /v1/create es inmediata, pero el veredicto de la AEAT llega en segundo plano. Dos formas de recogerlo:

• Webhook (recomendado): registras una URL con POST /v1/client-webhooks y recibes el resultado (Correcto, AceptadoConErrores, Incorrecto) firmado con HMAC en cuanto se procesa.
• Consulta: GET /v1/status?serie=A&numero=2026-0001 cuando lo necesites (por ejemplo, en el detalle de la factura en tu interfaz).

«Aceptado con errores» no es un rechazo: la factura está registrada y la AEAT señala un dato mejorable, casi siempre del destinatario. Puedes reducirlos a casi cero activando lavalidación del destinatariocontra el censo antes de emitir.

Paso 4 — Anulaciones y rectificativas

En Verifactu nada se edita ni se borra; se corrige añadiendo registros:

Si tu ERP ya modela abonos y rectificativas, el mapeo es directo; la referencia completa está enanulaciones y subsanaciones.

Paso 5 — Pruebas y paso a producción

Todo el desarrollo se hace contra el entorno de pruebas, un despliegue gemelo conectado a la preproducción oficial de la AEAT: mismas validaciones, respuestas reales de la Agencia, cero trascendencia fiscal. No es un simulador —habla con la AEAT de verdad—, así que lo que funciona aquí funciona en producción. La verificación de extremo a extremo — alta, QR en el PDF, anulación, resultado por webhook — está guionizada en la documentación. Con eso en verde, producción es cambiar la URL base y la API key.

Plan de trabajo realista

La moraleja de los plazos de 2027: el desarrollo no es el cuello de botella — lo son las pruebas y el papeleo. Empezar en otoño de 2026 es llegar cómodo; empezar en diciembre es llegar con el soporte de todos los proveedores saturado.

Preguntas frecuentes