Habilitación ante la DIAN

Esta guía lleva a una empresa nueva desde el alta hasta su primera factura en el ambiente de habilitación (test), el que emite contra el servicio de habilitación de la DIAN. Son siete pasos, en este orden. Todo se hace desde el portal y desde el sitio de habilitación de la DIAN; aquí no hay comandos.

Antes de empezar, ten a mano:

El correo registrado en el RUT de la empresa (la DIAN envía ahí el acceso a su sitio de habilitación).
El certificado de firma de la empresa, en un archivo .p12 vigente, y su contraseña. No la escribas en correos ni en tickets.
Un rol de propietario o administrador en el portal: configurar la empresa, subir el certificado y correr el set son acciones de esos dos roles (los desarrolladores pueden crear claves de habilitación, pero no ejecutar los pasos 2 a 5).

Si quieres verlo antes, ensáyalo en el Sandbox (Sandbox → Ensayar el set de habilitación): el mismo set, con los mismos pasos, estados y mensajes que verás en la página Habilitación, pero contra la DIAN simulada de foliios. El ensayo no habilita a la empresa.

Qué cambia con el bloqueo: en habilitación una empresa no emite documentos nuevos hasta que la DIAN apruebe su set de habilitación con el software vigente. Antes de eso, cada emisión responde 409 habilitation_required (ver El error 409). Las claves sk_sandbox_ y sk_live_ no pasan por esta regla.

Los siete pasos

1. Crea la cuenta y la empresa

Regístrate en el portal con tu correo. Te llega un enlace de acceso que vence en 15 minutos; si venció, pide otro. Después crea la empresa con los datos del emisor (identificación, régimen, responsabilidades, dirección, establecimientos y correo de recepción). Los datos de la empresa son los mismos en habilitación y en producción.

2. Registra el software en la DIAN y guárdalo en el portal

Entra al sitio de habilitación de la DIAN (el catálogo de participantes de habilitación, catalogo-vpfe-hab.dian.gov.co). La DIAN envía un acceso de un solo uso al correo del RUT.
En el menú de registro y habilitación, elige documentos electrónicos, factura electrónica, y el modo de operación Software Propio. Los nombres exactos del menú son los que describe el marco normativo y pueden cambiar; si no coinciden con lo que ves, guíate por lo que muestre la DIAN.
Escribe el nombre del software y un PIN (un código numérico que defines tú). Guárdalo en un lugar seguro: el portal lo cifra y no vuelve a mostrarlo.
La DIAN te entrega dos datos:

Dato	Para qué sirve
`SoftwareID`	Identifica el software ante la DIAN.
`TestSetId`	Identifica el set de habilitación que enviarás. Cambia si registras otro software.

En el portal, en Empresa, abre el software de habilitación y escribe el SoftwareID, el NIT del proveedor (el de la empresa si el software es propio, sin dígito de verificación), el PIN y el TestSetId.

Importante: si más adelante cambias el software de habilitación (otro TestSetId, o el mismo TestSetId con otro SoftwareID), la habilitación anterior deja de valer y hay que aprobar el set otra vez. Guardar el mismo software de nuevo no la afecta.

3. Registra la resolución de habilitación

El set numera sus facturas con una resolución electrónica automática vigente hoy en habilitación. Esa resolución la define la DIAN en el catálogo de participantes de la empresa (autorización, prefijo, rango desde y hasta, fechas y clave técnica). Cópiala de ahí tal como aparece: no es una constante y no hay una consulta automática que la traiga en habilitación.

Regístrala en el portal, en Resoluciones, con el ambiente de habilitación. Verifica que su fecha de vigencia incluya el día en que vas a correr el set.

4. Sube el certificado

En Certificado, sube el .p12 de la empresa para habilitación e indica su contraseña. El portal lo abre, comprueba que sea legible y vigente y guarda solo sus datos públicos; nunca permite descargarlo de nuevo. Si el portal avisa que el NIT del certificado no coincide con el de la empresa, revísalo: es una advertencia, no un rechazo (el certificado de un representante legal trae su cédula).

Sube el archivo tal como te lo entregó la entidad de certificación: el portal también lee los .p12 empaquetados con el cifrado antiguo RC2 (el que usan algunas entidades y las exportaciones de Windows), sin convertirlos antes.

Renovar el certificado más adelante no invalida la habilitación.

5. Corre el set de habilitación

En Habilitación, cuando los tres requisitos (software con TestSetId, certificado vigente y resolución vigente) aparezcan completos, escribe cuántas facturas, notas crédito y notas débito enviar y pulsa Iniciar set de habilitación. Las cantidades están en el catálogo de habilitación de la DIAN: en el software asociado, el ícono del ojo abre el detalle del set, que muestra el TestSetId, el Total de documentos requeridos y el Total de documentos aceptados requeridos. Sin ese dato, deja las que vienen: 8 facturas, 1 nota crédito y 1 nota débito. El portal acepta hasta 30 facturas y hasta 10 notas de cada tipo.

El portal arma esos documentos, los firma con tu certificado, los envía a la DIAN con tu TestSetId y consulta el resultado de cada uno. Deja la página abierta: el asistente avanza solo y, si la DIAN no responde, puedes pausar y reanudar sin perder lo hecho.

Cuando todos los documentos quedan Aceptado, el intento queda Aprobado y la empresa queda habilitada para emitir en el ambiente de habilitación. Confirma además en el sitio de la DIAN que el software figura habilitado: el set debe pasar de En proceso a aceptado. Si la DIAN lo deja en proceso con un intento aprobado en el portal, inicia otro con las cantidades del Total de documentos requeridos.

6. Crea una clave `sk_test_`

En Claves de API, crea una clave de habilitación (empieza por sk_test_). Se muestra completa una sola vez: guárdala en tu gestor de secretos. Crearla no exige haber aprobado el set, pero hasta entonces sus emisiones nuevas responden 409 habilitation_required.

7. Emite tu primera factura

Emite una factura con la clave sk_test_, desde tu integración o desde Documentos → Nueva. Responde 202 con el documento en pending y su número; la DIAN lo valida en segundos y verás accepted o rejected con sus reglas. La referencia de la API está en la referencia de la API v1.

Qué significan los estados

Cada documento del set pasa por estos estados:

Estado (API)	Lo que ves	Qué significa
`planned`	Por enviar	Todavía no se envió a la DIAN.
`sent`	En validación	La DIAN lo recibió y aún no responde.
`accepted`	Aceptado	La DIAN lo validó.
`rejected`	Rechazado	La DIAN lo rechazó; el mensaje trae sus reglas.
`refused`	No recibido	La DIAN rechazó el envío en las validaciones iniciales del ZIP.
`timed_out`	Sin respuesta de la DIAN	La DIAN no dio un resultado dentro del tope (ver abajo).
`set_accepted`	Set ya aceptado por la DIAN	La DIAN no validó el documento porque el set de ese TestSetId ya está aceptado (código 2, «se encuentra Aceptado»).

Y el intento completo: En curso, Aprobado (todos aceptados, o la DIAN responde que el set ya está aceptado: entonces no se envía nada más) o Falló (basta un documento rechazado, no recibido o sin respuesta).

`timed_out`: la DIAN no respondió a tiempo

A veces la DIAN deja un documento en “en proceso” o “no encontrado” sin resolverlo nunca. Para que el intento no quede colgado, cada documento enviado tiene un tope, contado desde su envío:

Último código de la DIAN	Tope
`66` o `90` (“no encontrado”)	10 minutos
Cualquier otro en proceso (por ejemplo `98`) o sin código	1 hora

Al cumplirse el tope, el documento pasa a timed_out y el intento queda Falló, con un mensaje que nombra el documento, el código y los minutos, y te pide iniciar un intento nuevo. Los umbrales son una decisión de foliios, no una cifra de la DIAN. Dos precisiones:

Si la DIAN responde de verdad (aceptado o rechazado), esa respuesta manda, aunque llegue pasado el tope.
El tope se aplica aunque no tengas el portal abierto: un proceso periódico (cada 5 minutos) revisa los intentos pendientes.

Un intento que se detuvo en Por enviar porque la DIAN no estaba disponible no vence solo: ábrelo y pulsa Reanudar.

El error 409 `habilitation_required`

Lo recibes al emitir un documento nuevo con una clave sk_test_ cuando la empresa no aprobó el set con su software vigente. Llega como application/problem+json, con estado 409 y el código habilitation_required. Además del mensaje en español, trae tres campos propios en la raíz:

Campo	Contenido
`company_id`	La empresa a la que le falta aprobar el set.
`environment`	Siempre `test`.
`habilitation_url`	La ruta del asistente en el portal: `/habilitacion`.

El MCP devuelve el mismo código, mensaje y campos en la raíz de error.

Lo importante: el 409 no consume nada. No se gasta un número de la numeración ni queda atada tu Idempotency-Key. Cuando apruebes el set, repite la misma solicitud con la misma clave y se admite con el primer número libre. En un lote, el rechazo es de todo el lote (no se guarda nada) y, si el lote ya estaba creado, sus documentos fallan con ese código y se reintentan después de aprobar.

Lo que no se bloquea: reintentar o reenviar un documento ya creado, validar sin transmitir, declarar o cerrar una contingencia, crear claves sk_test_ y las lecturas.

Qué consume números del rango

Acción	¿Consume números?
Cada intento del set	Sí. Las facturas toman números de la resolución de habilitación; las notas usan los prefijos `NC` y `ND` con un número propio de cada intento (`NC1001`, `NC1002`… en el primero; `NC2001`… en el segundo).
Un intento detenido y reanudado	No gasta de más: sigue con los mismos números y nunca reenvía un documento que ya tiene respuesta de envío.
Un `409 habilitation_required`	No.
Emitir facturas en el ambiente de habilitación después de aprobar el set	Sí, como toda emisión: cada factura toma un número.

Por eso, antes de reintentar, corrige la causa: un intento nuevo toma otros 8 números del rango (uno por factura: más si el intento pide más facturas) y, si el rango de tu resolución es corto, puedes agotarlo. Revisa el consumo de la resolución en Resoluciones.

Cómo reintentar

Lee los mensajes del intento fallido: indican qué documento falló y por qué (reglas de la DIAN o el aviso de tiempo agotado).
Corrige lo que indiquen: software, certificado o resolución. Si fue timed_out, no hay nada que corregir; espera unos minutos y reintenta.
Pulsa Iniciar un intento nuevo. El anterior queda en el historial sin cambios.

La habilitación es del software vigente: un intento aprobado con un software anterior no la devuelve.

Datos que la DIAN no ha confirmado

Estos tres datos salen del anexo técnico, de fuentes secundarias o de la configuración por defecto de foliios; no están confirmados por la DIAN con una corrida real en habilitación. Si alguno no coincide con lo que ves en el catálogo de participantes, manda lo que diga la DIAN:

Rango y resolución de ejemplo. El prefijo SETP, el rango 990000000 a 995000000 y la autorización 18760000001 son los de ejemplo de foliios (y vienen de fuentes secundarias). No confirmado por la DIAN: usa siempre la resolución que la DIAN asignó a tu empresa.
Composición del set. El micrositio de la DIAN habla de 8 facturas, 1 nota crédito y 1 nota débito, y es lo que el portal propone por defecto. El tablero de un TestSetId real (visto el 2026-11-03) pedía otra cosa: 50 documentos requeridos (30 facturas, 10 notas débito y 10 notas crédito) y 1 documento aceptado requerido (1 factura). Cuál de los dos totales decide la aprobación: no confirmado por la DIAN. Por eso las cantidades se escriben en cada intento.
Atributos de conexión del certificado. La regla ZC06 de la DIAN pide que el certificado de transmisión tenga los atributos de conexión. foliios no valida este requisito al subirlo. No confirmado por la DIAN: un certificado emitido solo para firma podría no traerlos, y la DIAN lo rechazaría al transmitir.