Descargar los XML de sus facturas recibidas y enviadas de la DIAN

El servicio consulta el catálogo de la DIAN y devuelve los documentos electrónicos de un rango de fechas, con toda su información estructurada y, si se solicita, el XML original firmado de cada documento.

Se resuelve en dos etapas, que la API encadena automáticamente:

1. Listado. Obtiene del catálogo los CUFE de todos los documentos del rango, con su emisor, folio, fecha, estado y valor.
2. Consulta. Por cada CUFE pregunta a la DIAN y devuelve el XML original del documento.

Para consumir la API necesita tener a mano lo siguiente:

Es el punto que más dudas genera, así que conviene entenderlo bien. La DIAN envía por correo un enlace de autorización con esta forma:

https://catalogo-vpfe.dian.gov.co/User/AuthToken?pk=10910094|53031455&rk=901234567&token=6b84e2c2-9530-4e02-8bc0-647da438d804

Ese enlace completo es lo que se envía en el campo url de cada petición.

Tres reglas que debe respetar

Hay dos formas, según el endpoint que use.

A · API Key para volumen

X-Api-Key: <api_key>

Es la que usan los dos endpoints del flujo principal. Una sola clave sirve para todas las empresas que usted maneje: el certificado de cada una viaja dentro de la petición, así que no hay nada que registrar previamente.

Como el certificado va en el cuerpo, use siempre HTTPS y consuma la API desde su servidor, nunca desde el navegador.

La clave es suya y personal: identifica a su organización y es la que atribuye el consumo que se le factura (ver Consumo). No la comparta con terceros.

B · Token de empresa

Authorization: Bearer <token_de_empresa>

Alternativa para los endpoints de extracción completa. El servicio firma con el certificado que la empresa ya tiene configurado, de modo que usted no lo envía — pero requiere dar de alta cada empresa con su certificado, lo que no resulta práctico cuando son muchas.

El campo tipo determina qué documentos se extraen:

Para obtener ambos debe hacer dos extracciones separadas, una por cada valor. El resto de los parámetros es idéntico.

{
  "url":        "https://catalogo-vpfe.dian.gov.co/User/AuthToken?...",
  "tipo":       "Received",        // Received compras · Sent ventas
  "fechaDesde": "2026-08-01",
  "fechaHasta": "2026-08-31",
  "limite":     10                  // opcional: acota cuántos se descargan
}

{
  "success":   true,
  "total":     161,
  "ok":        155,               // facturas con XML interpretado
  "no_aplica": 6,                 // acuses RADIAN u otros: NO son errores
  "errores":   0,
  "parcial":   false,
  "conteo": {
    "pedidos": 161, "entregados": 161, "de_cache": 0,
    "reintentos": 1, "bloqueos": 1, "sin_xml": 0, "fallidos": 0
  },
  "data": [{
    "TipoDocumento":      "Invoice",
    "Numero de Factura":  "AFE8052025",
    "CUFE":              "09acc105d8dd1e61...",
    "NIT del Emisor":    "860013771",
    "Sub Total":         553800,
    "Impuestos Cabecera": 105222,
    "Total a Pagar":     659022,
    "TaxBreakdown": [{ "code": "01", "name": "IVA", "percent": 19,
                       "taxable_amount": 553800, "amount": 105222 }],
    "LineItems": [{
      "Nombre del Producto": "Domo Circular resq Negro - CJ x 50 un",
      "Referencia": "D15251099", "Cantidad": 5,
      "Precio Unitario": 83000, "Total": 415000,
      "taxes": [{ "code": "01", "percent": 19, "amount": 78850 }]
    }],
    "Estado extracción": "ok"
  }]
}

{
  "success": true,
  "total":   6,
  "data": [{
    "cufe":          "1ac814c2df59984f...",
    "tipoDoc":       "01",
    "folio":         "DPOS73771",
    "fechaEmision":  "26-07-2026",
    "nitEmisor":     "901772356",
    "nombreEmisor":  "GRUPO RC S.A.S.",
    "estado":        "Aprobado",
    "EstadoRadian":  "No Aplica",
    "valor":         "$ 246.850",
    "valorNumerico": 246850
  }]
}

{
  "certificate": "<contenido del .p12 en base64>",
  "password":    "<contraseña del certificado>",
  "ambiente":    1,                 // 1 producción · 2 habilitación
  "cufes":       [ "1669c097...", "18a20b3d..." ]
}

{
  "success": true, "total": 2, "ok": 2,
  "data": [{
    "cufe":      "1669c097...",
    "success":   true,
    "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
  }]
}

Alternativas

Estas tres usan token de empresa, lo que exige que cada empresa esté registrada en el servicio con su certificado. Sirven cuando se opera una sola empresa, no cuando son muchas.

{
  "tipo":       "Received",
  "fechaDesde": "2026-07-01",
  "fechaHasta": "2026-07-31",
  "url":        "https://catalogo-vpfe.dian.gov.co/User/AuthToken?..."
}

{
  "success":   true,
  "jobId":     "19e1f865-8d68-4b93-8f1a-b162eb27ca08",
  "statusUrl": "https://.../api/extractor/company/jobs/19e1f865-..."
}

{
  "status":    "running",      // running · done · error
  "stage":     "enriching",
  "total":     6,
  "processed": 5,
  "log":       [ "..." ],
  "data":      [ /* documentos, al terminar */ ]
}

El campo xmlBase64 contiene el documento UBL 2.1 firmado, tal como lo tiene la DIAN. No es un extracto ni una conversión: es el archivo original, con validez legal, que usted procesa y conserva.

Qué trae

• La firma digital XAdES del emisor y la validación de la DIAN.
• Las extensiones DIAN (sts:DianExtensions) con el CUFE, la resolución de numeración y el rango autorizado.
• Emisor y adquiriente completos, con identificación, régimen y ubicación.
• Totales, desglose de impuestos, retenciones y el detalle de todos los renglones.
• Notas, medios de pago, descuentos y cargos.

Cómo obtenerlo

Decodifique el base64 y guarde el resultado como archivo .xml:

# PHP
file_put_contents("$cufe.xml", base64_decode($doc['xmlBase64']));

# Python
open(f"{cufe}.xml", "wb").write(base64.b64decode(doc["xmlBase64"]))

El contenido decodificado empieza siempre por <?xml version="1.0"...><Invoice ...> (o CreditNote / DebitNote según el tipo de documento).

Una llamada por empresa y período, sin certificado, sin trabajos asíncronos y sin consultas de avance.

1. Obtener un enlace AuthToken nuevo de la DIAN para esa empresa.
2. POST /api/xml-sin-certificado con el rango de fechas → devuelve cada documento con su XML ya interpretado.
3. Revisar conteo: si fallidos no es cero, reintentar ese período.
4. Guardar lo recibido y causarlo en su sistema.
5. Repetir con tipo: "Sent" si también necesita las ventas.

# todo en una llamada, sin certificado
curl -X POST https://<url-base>/api/xml-sin-certificado \
  -H "X-Api-Key: <api_key>" -H "Content-Type: application/json" \
  -d '{"tipo":"Received","fechaDesde":"2026-08-01","fechaHasta":"2026-08-31","url":"<authtoken>"}'

La vía anterior, con certificado

Sigue vigente y sin cambios. Son dos llamadas, y la segunda exige el .p12 de la empresa. Tiene sentido cuando ya dispone de los CUFEs por otro medio, o cuando necesita un caudal que no dependa del ritmo del portal de la DIAN.

# 1 · listar
curl -X POST https://<url-base>/api/cufes \
  -H "X-Api-Key: <api_key>" -H "Content-Type: application/json" \
  -d '{"tipo":"Received","fechaDesde":"2026-07-01","fechaHasta":"2026-07-31","url":"<authtoken>"}'

# 2 · traer los XML (en lotes)
curl -X POST https://<url-base>/api/ubl2.1/xml/by-cufes \
  -H "X-Api-Key: <api_key>" -H "Content-Type: application/json" \
  -d '{"certificate":"<p12_base64>","password":"<clave>","ambiente":1,"cufes":["..."]}'

Cuando son muchas empresas

El esquema escala sin configuración adicional, y esa es su principal ventaja:

• Una sola API Key para toda la operación, sin importar cuántas empresas maneje.
• Por la vía sin certificado no hay certificados que gestionar, que es lo que más pesa cuando son muchas empresas: ni pedirlos, ni custodiarlos, ni renovarlos al vencer.
• Si usa la vía con certificado, los .p12 se quedan de su lado: no hay que cargarlos ni registrarlos en el servicio, viajan en cada petición.
• Lo único imprescindible por empresa es su enlace AuthToken.

El límite real es el tiempo, no la cantidad

El servicio consulta la DIAN una vez por cada documento, de forma secuencial. Un lote de 500 CUFEs son 500 consultas encadenadas, y puede tardar más de lo que el servidor web permite mantener abierta una petición.

La vía sin certificado va al ritmo del portal

/api/xml-sin-certificado no consulta el servicio web de la DIAN sino su portal, y ese portal limita por dirección IP. Medido sobre 300 documentos:

Ir más deprisa no entrega más documentos: las peticiones rechazadas también gastan cupo. El servicio mantiene el paso de una por segundo y reintenta lo que la DIAN frene, así que no hay nada que ajustar del lado del cliente.

Tiempos de referencia

Recomendaciones

• Extraiga por períodos mensuales y por empresa. Es más fácil de reintentar que un rango de un año.
• Programe el proceso en tareas de fondo o nocturnas, nunca dentro de una petición de usuario.
• No vuelva a pedir lo que ya tiene. Guarde por CUFE y consulte solo lo nuevo.
• Compare ok contra total en cada respuesta y reintente solo los CUFEs que fallaron.
• Procese los lotes en serie, no en paralelo, para no saturar el servicio ni la DIAN.

Al recibir un xmlBase64, decodifíquelo y persístalo. Una convención simple:

almacenamiento/xml/<NIT>/<AAAA-MM>/<CUFE>.xml

Guarde también el CUFE en su base de datos como identificador único del documento: le sirve para no volver a descargarlo y para cualquier consulta posterior.

Errores por documento

Una extracción puede terminar correctamente y aun así tener documentos individuales con error. Revise siempre los contadores del resultado:

• Procesados — cuántos se intentaron.
• OK — cuántos se obtuvieron completos.
• No coincide — el adquiriente del documento no corresponde a su NIT.
• Error — la DIAN no devolvió el documento. Reintente esos CUFE por separado.

El servicio se factura por lo que se usa, y usted puede consultarlo cuando quiera con su misma API Key. La idea es que vea exactamente la misma cifra que vemos nosotros, sin tener que pedirla.

{
  "success": true,
  "cliente": "Su Empresa S.A.S.",
  "periodo": { "desde": "2026-08-01", "hasta": "2026-08-31" },
  "consumo": { "consultas": 50, "documentos": 400 },
  "importe": {
    "cuota_mensual":       300000,   // fija, se suma al consumo
    "precio_consulta":     280,
    "subtotal_consultas":  14000,
    "tramo_documento":     "1 – 500",
    "precio_documento":    150,
    "subtotal_documentos": 60000,
    "consumido":           74000,
    "total":               374000,
    "moneda":              "COP"
  },
  "detalle": [
    { "endpoint": "cufes", "unidad": "consulta",
      "total": 50, "llamadas": 50 },
    { "endpoint": "xml/by-cufes", "unidad": "documento",
      "total": 400, "llamadas": 4 }
  ]
}

El precio del documento depende del volumen del mes

El tramo_documento lo define el total del mes y se aplica a todos los documentos, incluidos los primeros — no es un cálculo por escalones. Por eso, mientras el mes no cierre, el importe es una estimación: si el consumo sigue creciendo y cambia de tramo, el precio unitario baja y el total puede resultar menor que el que vio a mitad de mes.

Antes de dar por terminada la integración, verifique que su sistema:

• Solicita un enlace AuthToken nuevo por empresa en cada extracción, sin reutilizar el anterior.
• Usa /api/cufes y /api/ubl2.1/xml/by-cufes como flujo principal.
• Divide los CUFEs en lotes de 100 a 150, ajustados a la medición de su servidor.
• Procesa los lotes en serie, no en paralelo.
• Almacena los XML por su cuenta, indexados por CUFE, y no vuelve a pedir lo ya descargado.
• Compara ok contra total y reintenta solo los CUFEs fallidos.
• Extrae compras y ventas por separado (Received y Sent).
• Corre en un proceso de fondo o tarea programada, no dentro de una petición de usuario.
• Guarda las credenciales y los certificados fuera del código, y los consume solo desde el servidor.
• Reintenta con espera progresiva cuando la DIAN no responde.
• Confirmó con su proveedor que los tiempos de espera del servidor están en 600 segundos.
• Revisa /api/mi-consumo periódicamente y vigila el conteo de consultas y documentos.