Cómo integrar un ERP con VeriFactu por API sin duplicar la lógica fiscal dentro del sistema

El error más habitual al adaptar un ERP a un requisito fiscal nuevo es intentar convertir el propio ERP en la implementación completa de la norma. Eso parece directo al principio, pero multiplica dependencias: el sistema origen termina acoplado a XML, certificados, transporte, reglas de validación, estados remotos y evolución normativa. Kairoseth Fiscal adopta otro límite: ERP, CRM o software propio conserva los hechos que ya gobierna, mientras Puente VeriFactu centraliza el contrato fiscal, la validación, la idempotencia, la reconciliación y el transporte soportado. La API v1 acepta tanto InvoiceIntent canónico como payload mapeado, dispone de webhook firmado y forma parte de una matriz capability-first donde API es la primera opción, pero no la única. El resultado permite adaptar sistemas modernos y legacy sin mantener un motor fiscal diferente por proveedor.

1. Define la frontera: el ERP conoce el negocio y el bridge conoce el contrato fiscal

El sistema origen suele ser la autoridad sobre número y serie de factura, fecha de expedición, cliente, productos o servicios, descuentos, moneda e impuestos calculados. Esos datos deben salir de una fuente estable y trazable. El bridge no debería inventarlos cuando faltan, y el ERP no debería asumir responsabilidades que pertenecen a la capa fiscal. Puente VeriFactu mantiene fuera del origen decisiones como tenant, certificado, entorno AEAT, permisos, clasificación fiscal sensible, hash, encadenamiento y transporte. Esta división reduce el riesgo de que una actualización normativa obligue a modificar decenas de instalaciones ERP.

La arquitectura también evita que cada integración se convierta en un proyecto completamente distinto. API, webhook, archivo, Local Agent o conector nativo terminan produciendo el mismo InvoiceIntent y pasando por el mismo preflight. El adaptador cambia porque cambia la capacidad de entrada, pero el core fiscal no. Esta regla es importante para una empresa con varios sistemas: un ecommerce puede entrar por conector, una filial por ERP REST y una aplicación antigua por base de datos read-only, pero todos comparten semántica, estado, idempotencia y presentación.

2. Decide si enviar InvoiceIntent canónico o conservar el JSON del ERP

La API admite un modo canónico para equipos que quieren construir InvoiceIntent v1 directamente. Es útil cuando el software es propio, el modelo está bien documentado y el equipo de desarrollo puede controlar la transformación con tests. Los importes viajan como strings decimales exactos para evitar errores de float y el contrato mantiene una identidad de origen estable. El cliente no elige mediante payload organizationId, installationId o sourceSystem: esos valores salen de la credencial autenticada y cualquier intento de enviarlos como autoridad se sobrescribe.

El segundo modo es mapeado. El ERP puede seguir enviando campos con su vocabulario histórico y el request referencia un profileId. MappingProfile traduce rutas permitidas al contrato canónico, puede aportar configuración fija y se mantiene versionado server-side. Esta opción suele reducir cambios en software de terceros porque no obliga a reconstruir todas las estructuras internas. La elección no debe basarse solo en comodidad: un mapping mantenido por servidor facilita gobernanza, pero un sistema propio con fuerte tipado puede preferir el contrato canónico para detectar errores antes incluso de llamar a la API.

3. Usa preflight como contrato de calidad antes de cualquier efecto fiscal

POST /v1/preflight existe precisamente para separar validación de emisión. Una integración nueva debería empezar con muestras reales anonimizadas, probar número y fecha, destinatario, bases, cuotas, moneda y configuración y corregir todo lo que falle sin crear registros fiscales. El modo mapeado usa el mismo perfil que se empleará al emitir, lo que permite validar no solo el payload bruto, sino la transformación completa. Un preflight que falla debe ser visible y accionable; ocultarlo con defaults automáticos solo traslada el problema a una fase más costosa.

Este gate también permite establecer una estrategia de rollout. Primero se valida manualmente una operación, después se repite con varios tipos de factura y rectificación relevantes, luego se comprueban errores previstos y solo entonces se automatiza. El equipo del ERP puede construir alertas a partir del error estructurado sin conocer detalles internos del transporte AEAT. La separación entre datos comerciales y mapping ayuda a asignar responsabilidades: un NIF ausente se corrige en origen; una clasificación server-side incompleta se corrige en configuración; un timeout se trata como incidencia de transporte.

4. Diseña la Idempotency-Key antes de automatizar el primer envío

POST /v1/fiscal-records exige Idempotency-Key porque una integración empresarial debe asumir que las peticiones se repetirán. El ERP puede reenviar tras un timeout, un worker puede reiniciarse y una cola puede entregar el mismo evento más de una vez. La clave debe derivar de una identidad estable de la operación y permanecer igual durante todos los reintentos de esa misma intención. La API reserva idempotencia por organización, instalación y clave; la misma clave con el mismo contenido devuelve el mismo recurso y un contenido distinto provoca conflicto en lugar de reutilizar silenciosamente una identidad equivocada.

Además existe idempotencia fiscal por identidad de factura/origen. Esa defensa por capas permite recuperarse incluso si una reserva HTTP queda pendiente tras una caída. Para el integrador la regla operativa es simple: una operación nueva conserva su clave; cuando el servidor devuelve recordId, ese recordId se persiste. A partir de ahí un error de red o sincronización no debe crear una nueva identidad. El sistema consulta el recurso existente, registra correlationId y aplica la política de retry únicamente sobre consulta o reconciliación cuando corresponde.

5. Separa creación, estado y errores para poder reconciliar de verdad

GET /v1/fiscal-records/{recordId} devuelve estado normalizado sin secretos y respeta el tenant autenticado. Si un recurso pertenece a otra organización, la API responde como no encontrado para no filtrar su existencia. Esta consulta debe convertirse en una parte normal del ciclo de vida, no en una herramienta solo para soporte. Un ERP que guarda recordId puede refrescar estado después de una interrupción, reconstruir una pantalla de seguimiento o reanudar una cola sin repetir el proceso de creación.

Los errores siguen un formato estable con code, message, retryable, correlationId y detalles sanitizados. retryable permite decidir si un worker debe volver a intentar o si la operación necesita corrección humana. correlationId conecta la observabilidad del cliente con la del runtime sin exponer XML/SOAP ni secretos. Para reporting, el ERP puede conservar sourceInvoiceId, recordId, estado y último código de error. Ese conjunto es suficiente para operar la integración sin convertir la base de datos cliente en una copia de la capa fiscal interna.

6. Usa webhook cuando el origen puede emitir eventos pero no necesita una integración REST completa

POST /v1/webhooks/{profileId} permite una ruta low-code para CRM, SaaS o automatizadores que pueden lanzar HTTP al producirse una factura. El cuerpo se firma con HMAC-SHA256 sobre timestamp y raw body, con una ventana anti-replay y una identidad de evento estable. profileId y secreto se resuelven en servidor y el evento no puede decidir por sí mismo tenant, certificado o entorno. La seguridad no depende de ocultar una URL, sino de autenticar el evento y limitar qué mapping puede ejecutar cada instalación.

El webhook entra al mismo pipeline que la API: mapping, preflight, idempotencia, creación y consulta de estado. Por tanto, usar webhook no significa renunciar al control. Un evento duplicado debe conservar la misma identidad; uno fuera de ventana se rechaza; un payload incompleto se bloquea. En integraciones con herramientas low-code conviene además limitar cuidadosamente qué campos pueden editar usuarios no técnicos, porque facilidad de configuración no equivale a autoridad fiscal. La clasificación sensible continúa en servidor incluso cuando el evento se construye con un formulario visual.

7. Para ERP legacy, elige el adapter mínimo que pueda extraer datos sin invadir el sistema

No todos los ERP pueden hacer POST ni exponen REST. La matriz universal contempla lectura read-only mediante Local Agent para PostgreSQL, MySQL/MariaDB y SQL Server. El agente usa query o vista configurable, checkpoint durable y conexiones HTTPS salientes; por defecto no escribe en la base del ERP. Para sistemas que exportan ficheros existe watch-folder y SFTP read-only/no destructivo. Estos adapters resuelven transporte, descubrimiento y checkpoint, pero siguen pasando por MappingProfile y no incorporan reglas AEAT propias.

CSV/XLSX cubre el caso más simple: la empresa exporta un archivo, el sistema inspecciona estructura, propone mapping, ejecuta preflight, exige confirmación explícita y crea un batch durable. Una fila ya emitida no vuelve a emitirse, y una caída conserva la misma clave idempotente. El flujo manual universal queda como último fallback para microempresas o sistemas sin interfaz técnica razonable. La ventaja de esta matriz es que una limitación del ERP cambia el adapter elegido, no obliga a cambiar el motor fiscal o a migrar de software de gestión.

8. Mantén secretos server-side y separa TEST de AEAT producción

La integración puede desarrollarse sin colocar certificados o claves fiscales en el ERP. Las credenciales del conector se usan server-to-server y el contexto autenticado determina organización, instalación y origen. El cliente no selecciona el certificado mediante JSON y no debería recibir passphrase, XML AEAT crudo ni permisos de administración fiscal. Este modelo limita el impacto de una brecha en el sistema origen y simplifica la rotación de credenciales. También permite que un partner implemente el adapter con un contrato documentado sin obtener acceso innecesario a material sensible.

El despliegue recomendado pasa por diagnóstico, mapping, preflight, pruebas de idempotencia, escenarios de error y TEST antes de considerar producción. La AEAT publica un portal específico de Sistemas Informáticos de Facturación y VERI*FACTU con información técnica y normativa, y el marco base procede del Real Decreto 1007/2023 y su normativa de desarrollo. Como las fechas y especificaciones pueden cambiar, el gate de producción debe revisar las fuentes vigentes en el momento del go-live. Una release técnica o un contrato comercial no sustituye esa revisión ni constituye certificación oficial.

9. Checklist de implantación: qué debe estar resuelto antes de automatizar

Antes de activar un worker automático hay que poder responder con precisión a varias preguntas: qué evento significa factura expedida, cuál es su identidad estable, de dónde salen número y fecha, cómo se representan destinatario e impuestos, qué ocurre con rectificativas, qué moneda utiliza el origen, qué campos son obligatorios y qué ruta de fallback existe. Después se documenta el MappingProfile, se crean credenciales por instalación y se prueba que preflight detecta tanto casos válidos como errores intencionados. Una prueba que solo demuestra el happy path deja sin cubrir precisamente los fallos que suelen generar duplicados.

El segundo bloque de pruebas debe forzar reintentos: misma Idempotency-Key y mismo contenido, conflicto con contenido distinto, timeout después de creación, lookup por recordId, error retryable y error de validación no retryable. También conviene verificar observabilidad y soporte: correlationId disponible, estados comprensibles, secretos fuera de logs y runbook de recuperación. Solo cuando el sistema puede explicar qué ocurrió ante una interrupción merece la pena automatizar volumen. La velocidad de integración importa, pero en una operación fiscal la capacidad de reconstruir identidad y estado importa más.