API de SIFEN: cómo conectar un ERP con facturación electrónica

La respuesta corta es esta: integrar un ERP con SIFEN significa construir una capa de facturación que transforma datos comerciales en Documentos Electrónicos, los firma, los transmite, procesa la respuesta y devuelve un estado confiable al negocio. No es una llamada HTTP aislada ni un botón que “manda la factura”. Es un flujo con XML, certificados, validaciones, reintentos, consultas, eventos y trazabilidad.

La DNIT indica que los contribuyentes pueden desarrollar o adquirir un sistema conforme al Manual Técnico. También publica documentación técnica y una guía de pruebas. La arquitectura debe partir de esas fuentes, no de un ejemplo copiado de otro proyecto.

¿Qué significa “API de SIFEN”?

En conversaciones de software se dice “API de SIFEN” para referirse a los servicios web y mecanismos técnicos que permiten comunicarse con el Sistema Integrado de Facturación Electrónica Nacional. La DNIT documenta servicios para autenticación, transmisión, validación, consulta y registro de eventos, entre otras funciones del ciclo de facturación.

La palabra API puede llevar a una expectativa equivocada: que existe un único endpoint al que se envía una factura y devuelve “aprobado”. La guía oficial describe una secuencia más amplia, con ambiente de prueba, autenticación mutua, documentos sincrónicos y asincrónicos, validaciones y consultas. La integración es un sistema de estados, no una función suelta.

¿Qué arquitectura conviene usar?

Un diseño inicial puede separar cuatro piezas:

Pieza	Responsabilidad	No debería hacer
ERP	Venta, cliente, producto, precio, impuesto y estado comercial	Conocer cada detalle del transporte de SIFEN
Capa de facturación	XML, reglas, firma, transmisión, reintentos y respuestas	Inventar datos comerciales que el ERP no tiene
SIFEN	Recibir y validar documentos, devolver resultados y conservar DTE	Corregir datos incompletos del negocio
Panel/operación	Mostrar aprobados, rechazos, eventos y pendientes	Ocultar errores para que “parezca automático”

El ERP sigue siendo la fuente de verdad para la operación comercial. La capa de facturación se convierte en la fuente de verdad técnica del intercambio: sabe qué XML se generó, con qué certificado se firmó, cuándo se transmitió y qué respuesta recibió.

Un flujo conceptual sería:

Venta en ERP
   ↓
Validación de datos obligatorios
   ↓
Construcción del DE/XML
   ↓
Firma y control de identificadores
   ↓
Transmisión a servicios SIFEN
   ↓
Respuesta: aprobado / rechazado / pendiente
   ↓
Persistencia, KuDE, CDC y actualización del ERP

La tecnología puede cambiar. La separación de responsabilidades es lo que evita que un rechazo tributario rompa la pantalla de ventas o que una caída de red genere una operación duplicada.

¿Qué datos tiene que aportar el ERP?

Antes de programar, hay que mapear los datos que ya existen y los que faltan. Entre los grupos habituales están:

• Identificación del emisor y configuración tributaria.
• Establecimiento y punto de expedición.
• Timbrado y numeración.
• Receptor, RUC, documento y dirección cuando corresponda.
• Tipo de operación y moneda.
• Productos o servicios, unidad, cantidad, precio e impuestos.
• Totales, descuentos y condiciones comerciales.
• Referencias a documentos anteriores cuando se emite una nota.
• Correo o canal para entregar el documento.

No todos los documentos usan exactamente los mismos campos ni las mismas reglas. La estructura XML y los XSD publicados por la DNIT deben guiar el modelo técnico. El ERP puede tener una tabla de productos que no contiene todos los datos necesarios para el documento tributario; ese gap hay que detectarlo antes del primer desarrollo.

¿Cómo se firma y transmite?

La firma electrónica no es una imagen pegada al PDF. Forma parte del documento electrónico y se valida con certificados y condiciones técnicas que la DNIT contempla en sus ambientes y manuales.

Una capa de facturación debería:

1. Validar los datos de negocio antes de construir el XML.
2. Generar el documento según el tipo correspondiente.
3. Aplicar la firma con el certificado configurado.
4. Validar estructura y firma antes de transmitir.
5. Autenticarse frente al ambiente elegido.
6. Enviar el documento usando el servicio definido en la documentación vigente.
7. Guardar la solicitud, el momento y el resultado.
8. Devolver al ERP un estado comprensible.

Los certificados y secretos no deberían quedar en el código ni en la base comercial sin protección. La integración también necesita permisos internos: no todas las personas que ven una venta deberían poder reemplazar certificados, repetir una transmisión o registrar un evento.

¿Qué diferencia hay entre transmisión sincrónica y asincrónica?

En una transmisión sincrónica, el sistema espera una respuesta dentro del intercambio. En una asincrónica, la recepción y el resultado pueden estar separados: el documento se envía, se obtiene una respuesta inicial y luego se consulta o procesa el resultado posterior según el servicio y la documentación.

La guía oficial de pruebas incluye pruebas de ambos tipos. El diseño tiene que asumir que el usuario puede preguntar “¿está aprobada?” antes de que el resultado definitivo esté disponible.

Un modelo de estados puede incluir:

Estado interno	Qué significa
Borrador	La operación todavía puede cambiar
Pendiente de transmisión	Datos listos, todavía no enviados
Recibida	El sistema remoto aceptó la recepción inicial
Aprobada	Hay resultado de aprobación y registro persistido
Rechazada	SIFEN devolvió un error que requiere corrección
Reintento controlado	El sistema está reintentando según una regla definida
Con evento	El DTE tiene una acción o evento posterior registrado

Los nombres pueden variar, pero la operación necesita distinguir lo que pasó. “Enviado” no es sinónimo de “aprobado”.

¿Cómo se manejan los rechazos?

Un rechazo tiene que volver a la causa de origen. Si falta un dato del receptor, administración debe corregir ese dato. Si el XML no cumple la estructura, el equipo técnico debe revisar la generación. Si el certificado está vencido o revocado, el error pertenece a la configuración y seguridad.

Un buen flujo registra:

• Código o referencia del error según la respuesta recibida.
• Mensaje original sin sobrescribirlo con una traducción vaga.
• Documento y versión del XML enviados.
• Fecha y hora de transmisión.
• Ambiente utilizado.
• Usuario o proceso que inició la operación.
• Corrección aplicada y nuevo intento.

Reintentar automáticamente solo tiene sentido cuando el error es transitorio y la identidad del documento está controlada. Reintentar cualquier rechazo puede generar más ruido y dificultar la conciliación.

¿Qué hay que probar antes de producción?

La guía de pruebas de la DNIT contempla una cadena completa: ingreso, comunicación, autenticación mutua, transmisión de documentos, validación de XML, certificado y firma, resultados de aprobación o rechazo, eventos, consultas por CDC o QR y generación de KuDE.

Un checklist mínimo debería cubrir:

1. Certificado válido y certificado rechazado.
2. Documento correcto y documento con errores conocidos.
3. Transmisión sincrónica y asincrónica.
4. Reintento después de una caída de red.
5. Consulta por CDC y QR.
6. Registro de un evento permitido.
7. Generación del KuDE a partir del DTE aprobado.
8. Recuperación de una operación desde el ERP.
9. Permisos para corregir, reenviar y consultar.
10. Monitoreo de errores y vencimiento de certificados.

El ambiente de pruebas no tiene valor jurídico. Sirve para validar el sistema antes de operar en producción; no es una forma de emitir comprobantes reales sin habilitación.

¿Cómo se conecta el CDC con el ERP?

Cuando SIFEN aprueba el documento, el ERP debería recibir y guardar el CDC, el estado del DTE, la referencia del XML y el vínculo al KuDE. El artículo qué es el CDC de una factura electrónica explica por qué debe tratarse como texto de 44 dígitos y no como un número de cálculo.

La búsqueda interna debería permitir encontrar la operación por número de factura, cliente, fecha, estado y CDC. Así administración no depende de abrir archivos uno por uno ni de copiar un identificador desde un correo.

¿Qué no conviene hacer?

• Integrar directamente la pantalla de ventas con todos los servicios técnicos.
• Guardar únicamente el PDF y descartar XML y respuestas.
• Poner certificados en variables escritas dentro del repositorio.
• Marcar la venta como finalizada antes de conocer el resultado.
• Automatizar el portal público como reemplazo de los servicios documentados.
• Copiar endpoints de una versión antigua sin revisar notas técnicas.
• Diseñar la integración sin contemplar eventos, consultas y rechazos.

En Softium Labs

En software a medida, analizamos primero el ERP y los documentos que la empresa necesita emitir. Después separamos la lógica comercial de la capa SIFEN, definimos estados, permisos, auditoría y pruebas. Si el caso se resuelve con una herramienta más simple, también lo decimos.

Una conexión propia vale la pena cuando reduce carga manual, duplicación y errores. No vale la pena si solo agrega otra pantalla para hacer lo mismo que el ERP ya hacía.

Si querés revisar tu arquitectura o preparar una integración con trazabilidad, contactanos. Te ayudamos a identificar el alcance real antes de empezar a programar.