Cómo Integrar Facturación Electrónica en tu ERP o SaaS: Guía para ISVs en Colombia
Integrar facturación electrónica en un ERP o SaaS requiere definir la arquitectura de integración, elegir el PT correcto y gestionar los estados del documento.
La decisión más impactante en la integración de facturación electrónica en un ERP o SaaS colombiano no es el código que se escribe — es la arquitectura que se elige antes de escribir la primera línea. Una integración acoplada al proveedor tecnológico bloquea la migración futura entre PTs; una integración desacoplada simplifica el cambio pero exige más diseño inicial. Ese tradeoff suele tomarse implícitamente, sin discusión, y aparece como deuda técnica varios meses después.
Esta guía explica los patrones de arquitectura más usados para integrar facturación electrónica en un ERP o SaaS colombiano, qué responsabilidades quedan en el sistema del ISV y qué se delega al PT, cómo modelar los estados del documento en la base de datos del ERP, y los puntos de extensibilidad que conviene preparar desde el inicio para anticipar cambios normativos y migraciones futuras.
Patrón de integración: acoplado o con capa de abstracción
Integración acoplada al PT
El código del ERP llama directamente a los endpoints del PT con su modelo de datos específico. Es la opción más rápida en time-to-market: si la documentación del PT es buena, la integración puede salir a producción en pocas semanas. La contraparte es que cambiar de PT más adelante implica reescribir esa capa: cada llamada, cada mapeo de campos, cada manejo de errores específico.
Capa de abstracción del PT
El ERP define su propio modelo de documento (Invoice, CreditNote, etc.) y un adapter por cada PT soportado que traduce entre el modelo interno y el modelo del PT. Permite cambiar de PT sin tocar el código de negocio del ERP — basta con cambiar el adapter. El costo es más código inicial y mayor complejidad para casos específicos del PT que no encajan en la abstracción.
Cuándo elegir cada patrón
Si el ERP solo opera en Colombia con un proveedor estable y no se prevé expansión multi-país, integración acoplada es razonable. Si el ERP/SaaS planea cubrir varios países LATAM o quiere libertad para cambiar de PT según condiciones comerciales, la capa de abstracción se justifica desde el inicio. Migrar de acoplada a abstracción después funciona pero es trabajo el doble: hay que diseñar la abstracción y refactorizar el código existente.
Estados del documento en el ERP
Estados durante la emisión
El ciclo mínimo de estados del lado del ERP es: BORRADOR (factura armada en el sistema pero sin transmitir), EN_TRANSMISION (transmitida al PT, esperando respuesta), APROBADO_DIAN (la DIAN devolvió ApplicationResponse positiva), RECHAZADO (la DIAN devolvió rechazo, requiere acción), CONTINGENCIA (emitida en modo contingencia, pendiente de retransmisión), RETRANSMITIDO (la contingencia se retransmitió y la DIAN la confirmó). Cada transición debe ser atómica y auditada.
Estados durante el ciclo de vida posterior
Después de la aprobación, el documento puede pasar por: NOTIFICADO_AL_CLIENTE (la factura se envió al adquiriente con su ApplicationResponse), ACEPTADO o RECHAZADO_POR_CLIENTE (cuando aplica la aceptación para RADIAN), PAGADO (cuando se registra el pago), ANULADO (cuando una nota crédito posterior la anuló). Estos estados son necesarios para gestión contable y de cuentas por cobrar.
Modelado de datos en el ERP
Tablas mínimas necesarias
El esquema mínimo recomendado: tabla documents con metadatos generales y estado actual; tabla document_lines con el detalle de líneas; tabla document_taxes con impuestos discriminados; tabla document_events con el log de transiciones de estado y respuestas DIAN (incluida la ApplicationResponse completa en JSONB); tabla retry_queue para retransmisiones pendientes. La separación entre documents y document_events permite reconstruir el ciclo completo del documento para auditorías.
Relaciones y normalización
Las relaciones entre documentos (factura original → nota crédito asociada → nota crédito que anula a la anterior) deben modelarse explícitamente con foreign keys o referencias por CUFE/CUDE. Esto es lo que permite reportes contables coherentes y auditorías DIAN sin gymnástica de queries. Almacenar el XML original transmitido en blob storage referenciado desde la fila del documento facilita el diagnóstico tardío de rechazos.
Arquitectura event-driven con webhooks
Recepción y procesamiento asíncrono
El patrón recomendado es no procesar la lógica de negocio síncronamente en el endpoint receptor del webhook. El endpoint valida la firma HMAC, persiste el evento crudo en una cola interna (RabbitMQ, SQS, Kafka), y responde 200. Otro worker consume de la cola y aplica las transiciones de estado correspondientes en el ERP. Así, picos de eventos no saturan el endpoint del PT y los reintentos del PT no se acumulan.
Reconciliación periódica como red de seguridad
Adicional a los webhooks, conviene un job programático (cron) que cada cierto tiempo consulte al PT por el estado de los documentos pendientes y reconcilie las diferencias con el ERP local. Esto cubre el caso en que un webhook se perdió o llegue corrupto. La reconciliación no reemplaza a los webhooks — los complementa como red de seguridad.
Manejo de errores y reintento
Errores transitorios vs permanentes
Distinguir errores transitorios (timeout, rate limit, 5xx) de errores permanentes (contenido inválido, NIT mal, CUFE incorrecto) es la condición para automatizar el reintento. Transitorios: reintento con backoff exponencial. Permanentes: marcar el documento como pendiente de revisión humana y alertar al equipo operativo. Mezclar ambos en el mismo flujo genera duplicados y ruido innecesario.
Cola de retransmisión para contingencia
Los documentos emitidos en modo contingencia deben retransmitirse cuando la DIAN vuelve. La cola dedicada a retransmisión debe ser FIFO, persistente, y debe tener mecanismo de pausa-reanuda para los casos en que la DIAN se cae nuevamente durante la retransmisión. Cada retransmisión exitosa actualiza el estado del documento en el ERP y elimina la entrada de la cola.
La documentación pública de Alanube incluye un set de patrones recomendados para ERPs e ISVs con clasificación automática de errores (transitorios, permanentes, contingencia), lo cual reduce el código del lado cliente a reaccionar a callbacks tipados en lugar de construir el clasificador desde cero.
Preguntas frecuentes
¿Cuál es la diferencia entre emitir una factura desde el ERP y emitirla desde un portal del PT? La emisión vía portal del PT (cargar manualmente la factura en una interfaz web del proveedor) sirve para volúmenes pequeños o casos puntuales pero no escala y desincroniza la contabilidad del ERP. La emisión desde el ERP via API garantiza que cada operación contable dispare automáticamente la factura electrónica correspondiente, manteniendo coherencia entre contabilidad y reportes a DIAN. La mayoría de ERPs colombianos para empresas medianas y grandes operan vía API; el portal se mantiene como mecanismo de contingencia o para casos excepcionales.
¿Cómo puedo modelar correctamente la relación entre factura, nota crédito y devolución parcial? La nota crédito siempre referencia una factura específica por su CUFE. Una devolución parcial se modela como nota crédito que ajusta solo las líneas o cantidades devueltas, no como anulación total. En el ERP, conviene tener una columna o flag en la nota crédito que indique si es total o parcial, y mantener la trazabilidad bidireccional: desde la factura se pueden ver todas las notas asociadas, y desde la nota se ve la factura origen. Cuando una factura tiene múltiples notas parciales, los reportes contables deben sumar todas para conocer el monto neto vigente.
¿Qué diferencia hay entre integrar el PT vía HTTP API directo o vía SDK oficial? Los SDKs oficiales del PT abstraen la construcción de payloads, la autenticación, el manejo de errores tipados y la serialización. Aceleran el desarrollo inicial significativamente. La contraparte es que el SDK introduce una dependencia versionada que hay que mantener actualizada cuando el PT lanza cambios, y limita las personalizaciones que el cliente puede hacer sobre el flujo. La integración HTTP directa es más flexible pero requiere construir la capa cliente desde cero. Para SaaS jóvenes, SDK suele ser la opción más pragmática; para ERPs maduros con stack técnico específico o restricciones de dependencias, la integración HTTP directa puede ser preferible.
¿Es posible cambiar de PT sin perder historía de facturas previamente emitidas? Sí. La historia de facturas aprobadas queda en el repositorio público de la DIAN, no en el PT — cualquier consulta por CUFE devuelve la factura sin importar qué PT la transmitió originalmente. En el ERP, las facturas históricas mantienen su CUFE y su contenido sin cambios. Lo que sí se afecta es el rango de numeración autorizado: al cambiar de PT, el rango se redefine para no solaparse con el anterior. También se afectan los webhooks pendientes — conviene completar el ciclo de todos los documentos en transmisión antes de cortar al PT anterior.
Artículos Relacionados
Errores de rechazo de la DGII en e-CF: cómo diagnosticarlos y corregirlos desde un agente de IA
Los rechazos de la DGII en e-CF tienen causas precisas y acciones correctivas definidas. Esta guía explica el ciclo de vida del documento, los códigos de error más frecuentes y cómo un agente de IA puede diagnosticar y corregir rechazos de forma autónoma.
Cómo conectar un agente de IA a la DGII en República Dominicana: guía paso a paso con el MCP de Alanube
Guía completa para conectar un agente de IA a la DGII de República Dominicana usando el único servidor MCP de infraestructura fiscal disponible actualmente: configuración del cliente, primer e-CF en lenguaje natural y emisión programática con TypeScript.
Las 30 herramientas del MCP de infraestructura fiscal de República Dominicana: referencia completa
Referencia consolidada en español de las 30 herramientas del único servidor MCP de infraestructura fiscal conectado a la DGII en República Dominicana: organización por capas, casos de uso y cuándo usar el orquestador vs. emisión directa.