Cómo integrar VeriFactu en ERP, ecommerce y software propio sin crear una deuda técnica fiscal

VeriFactu introduce requisitos que afectan a los sistemas informáticos de facturación en España, pero la respuesta técnica no debería ser añadir llamadas aisladas a cada aplicación que emite una factura. Esa estrategia funciona en una demostración y se vuelve frágil cuando aparecen varios canales, rectificaciones, fallos de red, importaciones, cambios de versión y necesidades de auditoría. La alternativa es tratar la adaptación como un problema de arquitectura: definir una frontera entre el sistema de negocio y la capa fiscal, utilizar un contrato de datos común, validar antes de producir efectos, registrar estados y conservar evidencia suficiente para reconstruir qué ocurrió. Este enfoque no sustituye el análisis normativo que corresponda a cada empresa; organiza la implementación técnica para que las obligaciones puedan aplicarse de forma controlada. Kairoseth Fiscal sigue este patrón para conectar WooCommerce, PrestaShop, ERP, CRM, Excel y software propio sin exigir que todos ellos conozcan los detalles del transporte fiscal.

1. Empieza por el modelo de datos, no por el endpoint

El primer trabajo consiste en describir qué representa una operación de facturación dentro de la empresa. Hay que identificar emisor, receptor cuando corresponda, serie, número, fecha, conceptos, bases, impuestos, totales, moneda, referencias y relación con operaciones previas cuando exista una rectificación. Pero también hay que capturar contexto operativo: qué sistema creó el registro, qué evento lo convirtió en facturable y qué identificador permitirá encontrarlo meses después. Un contrato canónico evita que cada conector invente nombres y comportamientos. El adaptador de WooCommerce puede traducir un pedido pagado al contrato; el de un ERP puede partir de una factura contabilizada; una importación puede leer una fila validada. Todos entregan una estructura equivalente al núcleo. Este modelo debe versionarse. Cuando cambie una regla o aparezca un nuevo campo, la plataforma podrá evolucionar de manera explícita en vez de romper silenciosamente conectores antiguos. La estabilidad del contrato interno es una de las mejores defensas contra la deuda técnica fiscal.

2. Define exactamente cuándo nace la operación fiscal

En ecommerce, el evento técnicamente más fácil de capturar no siempre es el correcto. Crear un pedido, autorizar un pago, capturarlo, marcarlo como completado o emitir una factura son momentos diferentes. La integración debe partir del proceso real de la empresa y no de un hook elegido por comodidad. También necesita una política para cancelaciones, devoluciones parciales y cambios realizados después de la emisión. En ERP sucede algo parecido: guardar un borrador no equivale necesariamente a contabilizar o emitir. La regla debe documentarse por conector y probarse con escenarios. Una tabla de transición ayuda a especificar qué estados pueden generar una operación, cuáles se ignoran y cuáles producen una rectificación o una revisión humana. Esta precisión reduce dos riesgos opuestos: enviar demasiado pronto información que aún puede cambiar o no enviar una operación porque el evento esperado nunca ocurrió. El diseño correcto convierte el flujo comercial en decisiones fiscales explícitas y observables.

3. Valida antes de ejecutar y explica los errores

La validación debe ocurrir lo más cerca posible de la frontera fiscal. El conector puede comprobar requisitos básicos del origen, pero el núcleo necesita aplicar las reglas comunes para evitar diferencias entre canales. Un error útil identifica el campo, el motivo y la acción posible; un error genérico obliga a revisar logs y aumenta el tiempo de resolución. Conviene separar fallos de datos, configuración, autenticación, conectividad y respuesta externa. Los primeros suelen requerir corrección humana o en el sistema de origen; los temporales pueden admitir reintentos; los definitivos deben detener la automatización. Esta taxonomía también mejora las métricas: la empresa puede saber si sus problemas provienen de datos incompletos, de un conector concreto o de disponibilidad externa. La validación previa debe ser determinista y repetible para que un mismo payload produzca el mismo diagnóstico mientras las reglas no cambien. Si el núcleo transforma datos, esa transformación debe quedar documentada; nunca debería completar silenciosamente información fiscal que no conoce.

4. Diseña reintentos idempotentes desde el primer día

Los fallos parciales son inevitables. Una petición puede salir del servidor y perderse la respuesta; el proceso puede reiniciarse; un trabajador puede pulsar de nuevo; una cola puede entregar el mismo mensaje más de una vez. Sin idempotencia, cada uno de estos casos puede crear duplicados o dejar al equipo sin saber qué estado es real. La solución empieza con una clave estable derivada de la identidad de la operación en origen y con un registro interno de procesamiento. Antes de ejecutar un efecto, el núcleo consulta si esa operación ya fue aceptada, rechazada definitivamente o está pendiente. Si el estado es incierto, no debe asumir éxito ni repetir a ciegas: debe entrar en reconciliación. Los reintentos necesitan límites, espera progresiva cuando tenga sentido y una cola de intervención para aquello que no se resuelve automáticamente. Esta disciplina es más importante que la velocidad. Una plataforma fiscal que procesa miles de operaciones rápidamente pero no puede demostrar qué hizo con una operación repetida es operativamente más débil que una que prioriza consistencia.

5. Conserva evidencia útil sin convertir los logs en un vertedero

Trazabilidad no significa guardar indiscriminadamente cada byte para siempre. La evidencia debe responder preguntas concretas: qué operación se procesó, desde qué sistema, con qué versión del conector y del núcleo, cuándo cambió de estado, cuál fue el resultado y qué referencia permite relacionarla con el origen. Los datos sensibles deben limitarse según necesidad y política de retención. También es útil distinguir evidencia operativa de logs de diagnóstico. La primera forma parte del historial que permite auditar y reconciliar; los segundos sirven para investigar incidencias y pueden tener ciclos de vida diferentes. Los identificadores de correlación permiten seguir una operación entre componentes sin copiar información completa en cada mensaje. Cuando existe una corrección, la relación con la operación anterior debe quedar explícita. Una interfaz de operaciones debería permitir buscar por referencia de pedido, factura o identificador interno y reconstruir la secuencia. Esta capacidad reduce drásticamente el coste de soporte y evita depender del conocimiento de la persona que implementó el conector.

6. Reconciliar es comprobar el sistema completo, no solo el transporte

Una comprobación de salud que diga que un endpoint responde no demuestra que todas las facturas estén correctamente procesadas. La reconciliación parte de conjuntos: qué operaciones debían existir según el origen durante un periodo y cuáles conoce la capa fiscal. Las diferencias se clasifican como pendientes legítimos, errores, operaciones ignoradas por regla, duplicados potenciales o estados que requieren consulta. Este proceso puede ejecutarse periódicamente y también bajo demanda después de una incidencia. Para ecommerce, conviene comparar pedidos que alcanzaron el evento fiscal con registros procesados; para ERP, facturas emitidas de las series incluidas; para importaciones, filas aceptadas frente a resultados. El objetivo no es forzar igualdad ciega, sino explicar cada diferencia. Una buena reconciliación produce una lista accionable y evidencia de cierre. También permite medir cobertura y detectar regresiones después de actualizar un plugin o una regla. Cuando esta capacidad existe desde el diseño, recuperar una caída deja de ser una investigación artesanal y se convierte en un procedimiento repetible.

7. Despliega por fases y mantén una salida segura

El despliegue debe reducir simultáneamente riesgo técnico y riesgo operativo. Primero se documenta el flujo actual y se construye el conector sin cambiar el comportamiento de producción. Después se ejecutan casos sintéticos y muestras controladas, incluyendo datos incorrectos y fallos deliberados. La siguiente fase activa un piloto limitado por organización, serie, canal o volumen. Durante el piloto se comparan resultados con el sistema de origen y se mide cuánto trabajo manual genera. Solo con esa evidencia se amplía cobertura. Cada fase necesita criterios de salida y rollback. Detener el transporte no debería destruir datos ni impedir registrar operaciones comerciales; una cola controlada puede conservar trabajo pendiente mientras se resuelve el incidente. Tras recuperar el servicio, la reconciliación determina qué debe reintentarse. Para empresas de Barcelona, Cataluña y el resto de España este enfoque permite adaptar procesos existentes sin duplicar páginas o arquitecturas por geografía. En organizaciones europeas, la implementación española debe permanecer como un módulo jurisdiccional claramente delimitado dentro de una plataforma más amplia.