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ú 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. El certificado debe ser del titular de la empresa: el serialNumber de su sujeto (NIT o cédula, sin dígito de verificación) debe ser el NIT de la empresa registrada. Si no coincide, si el certificado no trae serialNumber o si la empresa no tiene NIT ni cédula, el portal lo rechaza con 422 holder_mismatch y no lo guarda; el certificado de un representante legal, que trae su cédula, solo se acepta si la empresa está registrada con esa 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. La solicitud espera a la DIAN y responde 201 con el documento en accepted y su número, o 200 con rejected y sus reglas. Si la DIAN tarda más que la espera responde 202 con el documento en proceso: consúltalo con GET. 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.

Cuota mensual en habilitación

Cada empresa tiene un tope de documentos nuevos al mes con claves sk_test_ (mes calendario en hora de Colombia; el valor vigente está en la guía de límites por empresa). El set de habilitación no cuenta. El documento que pasa el tope responde 429 test_quota_exceeded, sin Retry-After: el cupo vuelve el día 1 del mes siguiente, y repetir la misma Idempotency-Key de un documento ya emitido devuelve el original sin gastar cupo. Si tu integración legítimamente necesita más, pídele a foliios que lo ajuste para tu empresa. La cuota no aplica a live ni al sandbox.

Después de habilitarte: activar producción

Aprobar el set no activa producción. Para configurar el ambiente de producción en el portal (crear una clave sk_live_, guardar el software, registrar o sincronizar resoluciones) la cuenta debe estar activada: tener una compra de documentos vigente, o un acuerdo con foliios. Si no, el portal responde 402 activation_required con el enlace de compra (cuando hay checkout abierto) y el contacto; no se cambia nada. Comprar una bolsa activa la cuenta al instante. La habilitación y el sandbox no lo necesitan.

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.

El correo al comprador en habilitación

En habilitación, por defecto ningún correo llega al comprador. Un documento de sk_test_ no tiene validez fiscal, así que foliios arma el mismo correo que en producción (remitente, responder a, destinatarios, asunto, texto y HTML, con el ZIP del documento) y lo guarda en el buzón de habilitación de la empresa en lugar de enviarlo. Vale para la entrega automática al validarse el documento, para la entrega en contingencia y para los reenvíos por la API, el portal y el MCP.

Lo que ve tu integración no cambia de forma:

La entrega queda sent y llega el webhook document.delivered, como en producción.
Cada intento de delivery.attempts trae destination: inbox cuando el correo se guardó en un buzón (habilitación y sandbox) y email cuando se envió al comprador (producción, y los correos reales de habilitación que se explican abajo). El webhook trae el mismo campo en data.delivery.destination. Es null en un intento que no envió nada.
El message_id de un intento con destination: inbox es el identificador del mensaje en el buzón (msg_…).
Los topes de reenvío (10 por minuto por empresa y 5 por documento en 24 horas) cuentan también lo que se guarda en el buzón.

Dónde leer el buzón:

En el portal: Configuración → Habilitación → Buzón de habilitación. Muestra cada correo con su asunto, sus destinatarios, el cuerpo y los archivos del ZIP (XML y PDF). Lo lee cualquier persona de la cuenta con acceso a la empresa.
Con un agente (MCP): la herramienta list_test_inbox, con una clave sk_test_ de la empresa.

Cada mensaje vence con su documento: a más tardar 7 días después de la creación del documento, sin importar cuándo se hizo el reenvío. Un reenvío hecho el día 6 se puede leer durante un día. El ZIP del mensaje es el paquete archivado del documento.

Correos reales en habilitación

Si necesitas ver llegar el correo a un buzón real antes de pasar a producción, pídele a foliios que habilite para tu empresa un tope diario de correos reales en habilitación. Solo foliios lo fija o lo cambia: no hay un ajuste en la API, en el portal ni en el MCP. Va de 1 a 200 correos por día; sin él, que es lo normal, ningún correo de habilitación se envía.

Con un tope de N:

Los primeros N correos de cada día se envían de verdad a los destinatarios del documento. El día es el calendario de Colombia: el tope empieza de nuevo a las 00:00.
El asunto de esos correos lleva [PRUEBA] antes del asunto normal, y el cuerpo dice que es un documento de habilitación sin efecto fiscal.
Cuenta cada correo enviado, sin importar cuántos destinatarios tenga, y cuentan todos: la entrega automática, la de contingencia y los reenvíos por la API, el portal y el MCP.
Los correos que siguen en el día se guardan en el buzón de habilitación, como siempre. No es un error: la entrega queda sent, llega document.delivered y ningún aviso de fallo.
Para saber a dónde fue cada uno, mira destination en el intento: email es un correo enviado, inbox uno guardado. Lo guardado conserva el asunto sin [PRUEBA] .

Un cambio del tope rige en menos de un minuto. Los topes de reenvío de arriba no cambian.

Sin un tope, para comprobar que un comprador real recibe el correo usa producción: el correo de un documento sk_live_ sí se envía.

Cuánto se conservan los documentos de habilitación

Un documento emitido con una clave sk_test_ no tiene validez fiscal, así que foliios lo conserva 7 días desde que se creó (los de producción se conservan diez años). Pasado ese plazo:

Descargar su XML, su PDF o su AttachedDocument, reintentarlo, reenviarlo o corregirlo responde 410 con el código document_expired: emite uno nuevo.
Más tarde, cuando el documento ya se borró del todo, la misma consulta responde 404.
El progreso de tu set de habilitación no se pierde: la página Habilitación sigue mostrando los intentos y su resultado aunque sus documentos hayan vencido.

El plazo cuenta desde la creación del documento y no se renueva. Si necesitas conservar un documento de prueba, descárgalo antes de que venza.

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.