🧾 DIAN Downloader Colombia (XML, PDF, Eventos RADIAN, Nómina, Contingencia & Equivalentes)

Script en Python para la consulta y descarga masiva automatizada de TODO TIPO de comprobantes electrónicos directamente desde el portal de la DIAN Colombia (catalogo-vpfe.dian.gov.co / gratis-vpfe.dian.gov.co) de forma gratuita, sin resolver CAPTCHAs y sin navegadores visuales (Selenium/Puppeteer).

---

📋 Documentos y Códigos Oficiales Soportados

El sistema soporta la totalidad de códigos de documento verificados en la plataforma de la DIAN:

1. 🛒 Facturas Electrónicas de Venta (Tipos 01, 02 Exportación, 09 AIU y 11 Mandato).
2. ⚡ Facturas y Documentos de Contingencia (Tipos 03 Contingencia, 04 Contingencia DIAN, 07 y 08 Contingencia Documento Equivalente).
3. 📝 Documentos Soporte en Adquisiciones (Compras a no obligados a facturar - Tipo 05).
4. ✏️ Notas de Ajuste al Documento Soporte (Tipo 95).
5. 🔖 Notas Crédito y Débito Electrónicas (Tipos 91 Nota Crédito y 92 Nota Débito).
6. 👥 Nómina Electrónica Individual y Notas de Ajuste (Tipos 102 Nómina Individual y 103 Nota de Ajuste de Nómina).
7. 🎟️ Documentos Equivalentes Electrónicos (Tipos 20 POS, 25 Cine, 27 Espectáculos, 32 Juegos Localizados, 35 Transporte Terrestre, 40 Peajes, 45 Extractos, 50 Transporte Aéreo, 55 Bolsa, 60 Servicios Públicos).
8. ⚖️ Notas de Ajuste para Documentos Equivalentes (Tipos 93 Débito y 94 Crédito).
9. 📬 Application Response y Eventos RADIAN (Tipo 96 - Acuses de recibo, recibo de bienes/servicios, aceptaciones y títulos valores).

---

📬 CATALOGO COMPLETO DE CÓDIGOS DE EVENTOS DIAN Y RADIAN (ApplicationResponse / Tipo 96)

Listado exhaustivo de la totalidad de códigos de eventos (Serie 030 a 059) según la normatividad vigente de la DIAN (Resolución 000085 de 2022, Anexo Técnico 1.8/1.9 y Anexo RADIAN):

1. 📑 Eventos Fiscales Obligatorios (Requisito Costos y Gastos - Art. 616-1 del E.T.)

Código de Evento	Nombre Oficial del Evento	Relevancia y Efecto Fiscal
030	Acuse de Recibo de la Factura Electrónica	Confirma la recepción del documento XML de la factura electrónica por el comprador.
031	Reclamo / Rechazo de la Factura Electrónica	Rechazo formal e inconformidad declarada por el comprador antes de la aceptación.
032	Recibo del Bien y/o Prestación del Servicio	Confirma la recepción a satisfacción de los bienes o prestación de servicios.
033	Aceptación Expresa	Aceptación formal, expresa e irrevocable de la factura a crédito por el comprador.
034	Aceptación Tácita	Transcurridos 3 días hábiles sin reclamo, la DIAN genera la aceptación tácita.

2. 🏛️ Eventos del Registro RADIAN (Serie 035 al 059 - Títulos Valores, Factoring y Circulación)

Código de Evento	Nombre Oficial del Evento	Relevancia y Efecto Fiscal
035	Inscripción de la Factura en el RADIAN	Convierte y registra la factura electrónica como Título Valor negociable.
036	Endoso en Propiedad	Transfiere la propiedad y titularidad de la factura a un tercero/factor.
037	Endoso en Procuración	Otorga facultad a un tercero para gestionar el cobro del título sin transferir propiedad.
038	Endoso en Garantía	Entrega la factura como garantía o colateral de una obligación.
039	Cancelación de Endoso	Deja sin efecto un endoso previamente registrado (propiedad, procuración o garantía).
040	Aval	Garantía total o parcial del pago del título valor respaldada por un avalista.
041	Mandato	Concede autorización a un mandatario para negociar o administrar el título.
042	Terminación del Mandato	Revocatoria o conclusión formal de la autorización concedida al mandatario.
043	Limitación a la Circulación	Embargos, medidas cautelares o restricciones judiciales sobre la factura.
044	Terminación de la Limitación a la Circulación	Levantamiento formal de la medida cautelar o embargo sobre la factura.
045	Solicitud de Disponibilidad para Negociación	Petición para habilitar la factura en sistemas de negociación o factoring.
046	Oferta de Transferencia de Derechos Económicos	Propuesta formal para ceder o vender los derechos de cobro del título.
047	Informe para el Pago / Notificación de Pago	Notificación enviada por el deudor o factor informando el estado o fecha de pago.
048	Pago de la Factura Electrónica	Registro del pago total o parcial de la factura electrónica.
049	Protesto	Registro oficial de incumplimiento o no pago del título valor a su vencimiento.
050	Transferencia de Derechos Económicos	Cesión o venta de los derechos económicos derivados de la factura.
051	Notificación de Pago al Tenedor Legítimo	Confirmación formal del pago realizado al tenedor legítimo registrado en RADIAN.
052	Solicitud de Anulación de Evento	Solicitud de reversión o anulación de un evento registrado por error en RADIAN.
053	Respuesta a Solicitud de Anulación de Evento	Aceptación o rechazo de la solicitud de anulación de evento en RADIAN.
054	Pago de Factura por Adquiriente / Deudor	Registro del pago efectuado por el comprador directamente al facturador/tenedor.
055	Pago al Tenedor Legítimo	Confirmación de desembolso o pago directo al tenedor del título en RADIAN.
056	Cobro Judicial / Liquidación de Título Valor	Registro de inicio de proceso ejecutivo o cobro judicial del título.
057	Cesión de Derechos de Crédito	Cesión o traspaso formal del derecho de crédito derivado de la operación.
058	Notificación de Acuerdo de Pago	Registro de acuerdo o reestructuración de pagos entre las partes.
059	Cancelación de Limitación a la Circulación	Registro de levantamiento definitivo de restricciones sobre el título en RADIAN.

3. ⚙️ Códigos de Estado de Validación DIAN (ApplicationResponse Técnico)

Código de Estado	Descripción Técnica	Significado
00 / 02	Procesado y Validado	Documento recibido, validado y aprobado exitosamente por la DIAN.
66	Aprobado con Notificación	Documento aprobado por la DIAN con advertencias u observaciones no impeditivas.
88 / 99	Rechazado	Documento rechazado por inconsistencias en la estructura UBL o reglas de negocio DIAN.

---

🛠️ Requisitos

• Python 3.8 o superior.
• Dependencias necesarias:

pip install requests beautifulsoup4   # el facturador v2 usa facturador_electronico_DIAN/requirements.txt

---

🚀 Modo de Uso (dian_downloader.py)

Ejecuta el script principal en tu terminal:

python3 dian_downloader.py

Pasos:

1. Ingresa la URL de AuthToken: Copia el enlace de acceso enviado al correo del representante legal por la DIAN (https://catalogo-vpfe.dian.gov.co/User/AuthToken?pk=...).
2. Ingresa el rango de fechas (DD/MM/YYYY): Presiona ENTER para usar el mes actual por defecto o ingresa tus fechas.
3. Selecciona la categoría deseada:
   • [1] 🚀 DESCARGAR TODO (Descarga absolutamente todos los documentos disponibles: compras, ventas, contingencia, soporte, nómina, notas C/D, eventos RADIAN y equivalentes).
   • [2] 🛒 Solo compras / recibidos (Facturas, notas y eventos)
   • [3] 💰 Solo ventas / emitidos (Facturas y notas)
   • [4] ⚡ Solo facturas de contingencia (Tipos 03, 04, 07 y 08)
   • [5] 📝 Solo documentos soporte y notas de ajuste (Tipos 05 y 95)
   • [6] 👥 Solo nómina electrónica y notas de ajuste (Tipos 102 y 103)
   • [7] 🎟️ Solo documentos equivalentes (POS, peajes, servicios públicos, etc.)
   • [8] 🔖 Solo notas crédito y débito (Tipos 91 y 92)

---

🧪 Script Secundario: Descarga de Ejemplos (descargar_ejemplos.py)

Para descargar únicamente 1 ejemplar de muestra (XML + PDF) por cada tipo de documento encontrado desde 2025 en una carpeta independiente:

DIAN_AUTH_URL="https://catalogo-vpfe.dian.gov.co/User/AuthToken?pk=...&rk=...&token=..." python3 descargar_ejemplos.py

Los ejemplares se guardarán en la carpeta ejemplos_dian/ con un índice consolidado resumen_ejemplos.json.

---

🌐 Facturador DIAN v2: portal web + API interna (facturador_electronico_DIAN/)

Emite facturas de venta por la Solución Gratuita de la DIAN. El formulario web replica las 11 secciones del portal (/ioFacturo/Documents/FacturaElectronica) y la misma lógica queda disponible como API REST.

cd facturador_electronico_DIAN
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python server.py          # http://localhost:8085  ·  API: /api/v1  ·  docs: /docs
.venv/bin/python -m pytest tests    # pruebas (sin red)

Arquitectura (app/):

• domain/: modelo canónico (FacturaEntrada) y motor de totales que replica el JS del portal con Decimal.
• dian/form_mapper.py: único módulo que conoce los campos del formulario DIAN; reproduce exactamente el POST capturado.
• dian/: sesión (AuthToken → SSO), consultas, registro de maestros y flujo de emisión.
• services/: maestros con código propio (CLI000001, PRD000001), emisión idempotente y conciliación del CUFE.
• catalogos/data/: catálogos DIAN versionados. Se regeneran con python -m app.catalogos.sync --auth-url "..."; --check avisa si la DIAN cambió los campos del formulario.

Emitir por API:

curl -X POST http://localhost:8085/api/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: pedido-123" \
  -d '{"cliente_id": "CLI000001", "items": [{"producto_id": "PRD000001", "cantidad": "2"}]}'

Variables de entorno: PORT (8085), FACTURADOR_API_KEY (exige header X-API-Key), FACTURADOR_DATA_DIR (base SQLite), CUFE_ESPERA_INTENTOS / CUFE_ESPERA_SEGUNDOS.

---

🧾 Facturador Gratuito DIAN - POC de Registro y Emisión (dian_facturador_gratis.py)

Script para interactuar con la Solución Gratuita de Facturación Electrónica (gratis-vpfe.dian.gov.co):

python3 dian_facturador_gratis.py

Capacidades:

• Verificación de Habilitación: Consulta el estado de la cuenta, rangos de numeración autorizados y vigencia del certificado digital gratuito de la DIAN.
• Catálogos: Prueba de concepto para crear/asociar clientes adquirentes y productos/servicios.
• Emisión: Estructuración y envío del payload de Factura Electrónica de Venta (Tipo 01) con firma delegada en la nube de la DIAN.
• Modo Demostración / Offline: Permite inspeccionar la estructura técnica de validación UBL 2.1 sin necesidad de un token activo.

---

📁 Estructura de Archivos y Reporte Consolidado

Los archivos .xml firmados, sus representaciones gráficas .pdf y los acuses de recibo se organizan por categoría y subcarpetas mensuales. Además, se genera un archivo resumen_descargas.csv consolidado compatible con Excel que incluye montos y estados:

descargas_dian/
├── resumen_descargas.csv  <-- Incluye Subtotal, IVA, Total, Estado DIAN y Rutas
├── compras/
│   └── 2026-09/
│       ├── COMPRAS_900123456_FEV1001.xml
│       └── COMPRAS_900123456_FEV1001.pdf
├── ventas/
├── contingencia/
├── notas_credito/
├── notas_debito/
├── soporte/
├── soporte_notas_ajuste/
├── nomina/
├── equivalentes/
└── eventos_radian/

Campos del Reporte CSV:

• Categoria, TipoDocumento, Numero, EmisorNIT, EmisorNombre, ReceptorNIT, ReceptorNombre, Fecha, Subtotal, IVA, Total, EstadoDIAN, CUFE_CUNE, EstadoDescarga, RutaXML, RutaPDF.