Documentación de SIFEN: qué debe leer un desarrollador antes de integrar

La respuesta corta es esta: un desarrollador que va a integrar SIFEN no debería empezar por un endpoint ni por un ejemplo de XML. Primero tiene que identificar la modalidad de facturación, leer el Manual Técnico vigente, entender los documentos que la empresa realmente emite y revisar XML, XSD, certificados, transmisión y guía de pruebas en ese orden.

La DNIT concentra la documentación para desarrollo de software en la sección técnica de e-Kuatia. Allí aparecen el Manual Técnico, recomendaciones para servicios asíncronos, estructuras XML, XSD, checksums, notas técnicas y la guía de pruebas. El objetivo de este artículo no es reemplazar esos documentos: es ayudarte a leerlos sin perder dos semanas navegando un PDF de cientos de páginas sin saber qué parte aplica.

¿Por qué la documentación de SIFEN cuesta leer?

Porque mezcla capas diferentes que en un proyecto común suelen estar separadas:

• Reglas tributarias y tipos de documentos.
• Estructura de datos y XML.
• Firma electrónica y certificados.
• Transporte y servicios web.
• Validaciones técnicas y de negocio.
• Estados, eventos y consultas.
• Representación gráfica y código QR.

Si el equipo lee solo el XML, puede producir un documento bien formado que igual es rechazado por una regla de negocio. Si lee solo un ejemplo, puede copiar una estructura de otra versión. Si implementa primero la transmisión, puede descubrir tarde que el ERP no tiene los datos obligatorios.

La documentación no es una lista de instrucciones lineales. Es el mapa de un sistema con varias responsabilidades. El trabajo consiste en armar el recorrido que aplica a tu empresa.

¿Qué hay en el portal oficial?

La sección técnica de e-Kuatia separa materiales con usos distintos:

Documento	Para qué sirve	Cuándo leerlo
Manual Técnico	Reglas generales, conceptos, documentos, campos y procesos	Al definir el alcance
Recomendaciones de servicio asíncrono	Consideraciones para intercambios no inmediatos	Al diseñar estados y reintentos
Estructura XML	Archivos de ejemplo o estructura electrónica	Al modelar la generación
XSD	Esquema para validar estructura y tipos	Antes de transmitir
Checksum MD5	Identificación de versiones publicadas	Al fijar una versión de trabajo
Notas técnicas	Correcciones o ajustes al manual	Antes de cerrar una implementación
Guía de pruebas	Escenarios mínimos de validación	Durante QA y habilitación

El portal muestra versiones y notas con el mismo identificador de manual. Eso no es una formalidad: una nota técnica puede corregir una interpretación que parecía válida cuando se leyó una versión anterior.

Paso 1 — Definir el alcance antes de abrir el editor

Antes de escribir código, respondé estas preguntas:

1. ¿La empresa utilizará e-Kuatia’i o integrará software con e-Kuatia?
2. ¿Es voluntaria, designada o ya habilitada como facturador electrónico?
3. ¿Qué tipo de documentos emite hoy?
4. ¿Cuántos establecimientos y puntos de expedición tiene?
5. ¿Qué datos están en el ERP y cuáles están solo en sistemas externos?
6. ¿Necesita transmisión sincrónica, asincrónica o ambas?
7. ¿Quién administrará certificados, rechazos y eventos?

La DNIT diferencia e-Kuatia’i y la vía de desarrollo de software. Si la empresa entra en el flujo de e-Kuatia’i, la lectura técnica y la responsabilidad de integración pueden ser distintas. No tiene sentido diseñar una capa completa para un caso que la plataforma oficial ya resuelve.

Paso 2 — Leer el Manual Técnico por capas

No hace falta memorizar cada página. Buscá primero las secciones que responden estas cinco preguntas:

¿Qué es un Documento Electrónico?

Necesitás entender la terminología: DE, DTE, KuDE, CDC, eventos, emisor y receptor. Sin ese vocabulario, el equipo termina usando “factura”, “XML” y “PDF” para referirse a cosas distintas.

¿Qué documentos aplica emitir?

Una factura electrónica no tiene los mismos campos ni relaciones que una nota de crédito, una nota de débito, una autofactura o una nota de remisión. El alcance debe salir de la operación real, no de una lista genérica.

¿Qué datos forman parte del documento?

Revisá emisor, receptor, operación, ítems, impuestos, totales, timbrado, establecimiento, punto de expedición y referencias. Comparalos con el modelo del ERP y anotá los campos que faltan.

¿Qué resultado puede devolver el sistema?

Leé cómo se informan aprobación, rechazo, validaciones, eventos y consultas. Un sistema que solo modela “éxito/error” va a quedarse corto.

¿Qué debe conservarse?

La integración necesita guardar suficiente información para reconstruir qué documento se generó, cuándo se transmitió, con qué certificado y qué respuesta se recibió.

Paso 3 — Entender XML y XSD sin confundirlos

El XML es la representación estructurada que se transmite. El XSD es un esquema que ayuda a verificar si la estructura respeta tipos, campos, longitudes y relaciones esperadas.

Una validación contra XSD puede detectar que falta un campo obligatorio o que un valor tiene un formato incorrecto. No puede decirte por sí sola si el RUC corresponde al receptor esperado, si una regla de negocio se cumple o si el certificado es válido. Por eso hay que separar:

Validación	Ejemplo	Dónde se revisa
Estructural	Etiqueta ausente o tipo incorrecto	XML/XSD local
Firma	Documento firmado con certificado válido	Capa de firma y SIFEN
Certificado	Vigencia o registro permitido	Configuración y servicio
Negocio	Totales o combinación no permitida	Reglas del SIFEN
Operativa	Documento duplicado o evento fuera de secuencia	Sistema y respuesta

La secuencia importa. Validar localmente reduce rechazos previsibles, pero no elimina la respuesta del servicio nacional.

Paso 4 — Revisar firma, certificados y seguridad

La firma electrónica necesita un certificado y una configuración protegida. El desarrollador debe entender:

• Qué certificado corresponde al ambiente.
• Cómo se carga y protege la clave.
• Cómo se verifica la vigencia y revocación.
• Qué identidad usa el proceso de transmisión.
• Cómo se rota o reemplaza un certificado.
• Qué personas pueden operar esa configuración.
• Qué queda registrado cuando una firma falla.

No guardes claves en el repositorio, no las compartas en tickets y no las mezcles con credenciales de base de datos del ERP. Un error de seguridad en esta capa puede detener la emisión de toda una empresa.

Paso 5 — Estudiar transmisión y estados

La guía de pruebas oficial de la DNIT propone probar comunicación, autenticación mutua, transmisión sincrónica y asincrónica, validación de XML, firma, eventos, consultas y KuDE.

Convertí esa secuencia en estados internos. Por ejemplo:

borrador → validado localmente → firmado → transmitido
        → resultado pendiente → aprobado o rechazado
        → KuDE y consulta disponibles

No uses un estado único llamado “facturado”. Administración necesita saber si el documento fue rechazado, si quedó pendiente o si fue aprobado pero todavía no se entregó al receptor.

Paso 6 — Leer la guía de pruebas como checklist de producto

La guía no es solo para el área técnica. También te permite comprobar que el sistema tiene un flujo operativo completo. Incluí pruebas de:

1. Acceso al ambiente de test.
2. Certificado válido y certificado inválido.
3. Documento correcto.
4. Documento con error de estructura.
5. Documento con error de negocio.
6. Transmisión sincrónica.
7. Transmisión asincrónica.
8. Consulta por CDC.
9. Consulta por QR.
10. Registro y consulta de eventos.
11. Generación del KuDE.
12. Caída de red y reintento controlado.

La guía oficial aclara que los documentos del ambiente de pruebas no tienen valor jurídico. El objetivo es demostrar que el sistema puede completar la cadena antes de operar en producción.

¿Cómo documentar la integración internamente?

Además de leer la DNIT, el equipo debe crear documentación propia. Una ficha mínima por documento debería registrar:

• Fuente de cada dato en el ERP.
• Campos transformados y reglas aplicadas.
• XML generado y versión del XSD.
• Método de firma y certificado usado por ambiente.
• Servicio de transmisión y tipo de respuesta.
• Estados internos y acciones permitidas.
• Reglas de reintento.
• Eventos posteriores.
• Retención y acceso a XML, respuestas y KuDE.

Esto evita que la integración dependa de una sola persona que “sabe cómo funciona”. También permite revisar el impacto cuando cambia el Manual Técnico.

¿Qué errores cometen los equipos?

Programar desde un ejemplo viejo

Un XML de un tutorial puede estar construido para otra versión. Tomalo como referencia de forma, no como contrato vigente.

Probar solo el caso feliz

Una factura aprobada no demuestra que funcionan rechazos, certificados, eventos, consultas y reintentos.

Dejar el modelo de datos para después

Si el ERP no tiene dirección, impuesto o referencia necesaria, ningún endpoint lo arregla. El gap aparece antes de la integración.

Separar desarrollo de operación

Si el área administrativa no ve estados y errores, el equipo técnico termina resolviendo facturas por mensajes manuales.

No registrar versiones

Guardá qué Manual Técnico, XSD y notas se usaron. “Según la documentación” no alcanza cuando hay varias versiones en circulación.

Un orden de trabajo razonable

Etapa	Resultado
Alcance	Documentos, modalidad y responsables definidos
Lectura	Mapa del Manual, XML, XSD y notas aplicables
Modelo	Campos y reglas conectados al ERP
Prototipo	Generación y validación local
Integración	Firma, transmisión y estados
Pruebas	Casos correctos, rechazos y eventos
Producción	Certificados, monitoreo y soporte

La secuencia reduce el riesgo porque cada etapa responde una pregunta antes de abrir la siguiente.

En Softium Labs

En software a medida, no tratamos la documentación de SIFEN como un trámite que se lee una vez. La convertimos en decisiones de arquitectura: qué queda en el ERP, qué queda en la capa de facturación, qué estados ve administración y cómo se prueba cada camino.

Si querés conocer el flujo completo, podés leer cómo conectar un ERP con SIFEN o empezar por qué es el CDC. Si ya tenés un sistema y la documentación te está frenando, contactanos para revisar el alcance real antes de construir.