Proceso de habilitación DIAN
Qué es y por qué es obligatoria
La habilitación es el proceso mediante el cual la DIAN certifica que el software de una empresa genera documentos electrónicos correctos (XML UBL bien formado, firma XAdES válida, cálculos correctos, CUFE/CUDE correctos, etc.).
Como esta plataforma opera en modo software propio, cada empresa (tenant) debe habilitarse individualmente con su propio NIT y certificado. Hasta no superar la habilitación, una empresa no puede emitir documentos con validez fiscal en producción.
Cómo funciona el test set
La DIAN asigna a cada empresa un set de pruebas identificado por un testSetId. La API
envía a ese set un conjunto mínimo de documentos:
| # | Tipo | Ejemplo |
|---|---|---|
| 1 | Factura de venta | SETP990000001 |
| 2 | Factura de venta | SETP990000002 |
| 3 | Nota crédito | referencia a la factura 1 |
| 4 | Nota débito | referencia a la factura 2 |
Los documentos del set se envían con el método SendTestSetAsync, que es asíncrono:
devuelve un ZipKey y luego se consulta el estado con GetStatusZip (polling).
:::info Criterio de aprobación Para aprobar el set basta con que la DIAN acepte el mínimo de documentos exigido. En la práctica, la DIAN puede aprobar el set aun cuando algunos envíos agoten el timeout de polling local, siempre que los documentos hayan sido contabilizados como válidos de su lado. :::
Estados del proceso
| Estado | Significado |
|---|---|
pendiente | Aún no se ha ejecutado el envío del set. |
en_proceso | Documentos enviados; esperando el resultado de la DIAN. |
aprobada | La DIAN aprobó el set; el tenant puede pasar a producción. |
rechazada | Uno o más documentos fueron rechazados; revisar los errores. |
Se consultan con GET /tenants/:nit/habilitacion/status.
Qué hacer si hay rechazos
- Revisar el campo
errores[]de cada documento rechazado (ver Errores DIAN frecuentes). - Corregir la causa (datos del tenant, configuración DIAN, certificado, etc.).
- Volver a ejecutar
POST /tenants/:nit/habilitacion/run.
:::tip "Aprobado con notificación" Si la DIAN reporta "Aprobado con notificación", el documento fue aceptado con advertencias informativas — no es un rechazo. Ver Emitir documentos. :::
SendTestSetAsync vs SendBillSync
Esta es una distinción central del sistema:
SendTestSetAsync | SendBillSync | |
|---|---|---|
| Uso | Solo proceso de habilitación | Emisión general (facturas, NC, ND) |
Requiere testSetId | Sí | No |
| Respuesta | Asíncrona (ZipKey + polling con GetStatusZip) | Síncrona (resultado en la misma llamada) |
| Catálogo DIAN | No aparece en el catálogo general | Aparece en el catálogo general |
| Ambientes | Solo habilitación | Habilitación y producción (cambia la URL) |
:::warning No mezclar los métodos
Un documento enviado con SendTestSetAsync aparece bajo el set de pruebas pero no en el
catálogo general, y viceversa. Toda emisión fuera del proceso formal de habilitación debe
usar SendBillSync.
:::
Siguiente paso
Una vez aprobada la habilitación y activada la producción, continúa con Emitir documentos electrónicos →.