Una llamada devuelve todas las facturas que le emitieron a una empresa en un rango de fechas, con emisor, totales e impuestos discriminados. Esta guía la deja funcionando en cinco minutos.
Hasta ahora, bajar el XML original exigía el certificado digital de cada empresa. Desde septiembre de 2026 hay una vía que no lo pide. La anterior sigue funcionando: puede usar la que le convenga, o las dos.
Recorre el rango de fechas y devuelve, por cada documento, lo que declara el catálogo y lo que dice su XML firmado. Solo con el enlace AuthToken.
La vía que ya conoce. Devuelve el XML firmado en base64 a partir de una lista de CUFEs, usando el certificado .p12 de la empresa.
Es la credencial que autoriza la consulta del catálogo de una empresa.
La DIAN lo envía por correo al representante legal, desde el portal de factura electrónica. Llega con esta forma:
https://catalogo-vpfe.dian.gov.co/User/AuthToken?pk=········%7C········&rk=NIT&token=········-····-····-····-············Se pega completo y sin modificar, incluidos los caracteres raros. Recortarlo o reescribir alguna parte lo invalida.
Estos son los datos para integrar el servicio desde su sistema. La clave se la entregamos por separado, por un canal seguro: no viaja en esta página ni en el archivo que descarga.
https://api.tra-di.site
se la entregamos por separado
Un ejemplo directo, sin Postman. Sustituya SU_CLAVE por la clave que le entregamos y PEGUE_AQUI_SU_ENLACE_AuthToken por el enlace que le envió la DIAN:
curl -X POST https://api.tra-di.site/api/cufes \
-H "X-Api-Key: SU_CLAVE" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"tipo": "Received",
"fechaDesde": "2026-08-24",
"fechaHasta": "2026-08-31",
"url": "PEGUE_AQUI_SU_ENLACE_AuthToken"
}'Cinco pasos, una sola vez.
En Postman, Import y seleccione el archivo APIDIAN-Extractor-Piloto-Pleia.postman_collection.json. Aparecerá una colección con cuatro peticiones, ordenadas de la más usada a la menos.
La dirección del servicio ya viene configurada. La clave de acceso se la entregamos aparte.
JSON · 18 KB · formato Postman v2.1
Abra la colección, pestaña Variables, y pegue el enlace AuthToken en url_token. Guarde con Save.
En esa misma pestaña pegue también su api_key. Son los dos únicos valores que hay que configurar, y quedan guardados para todas las consultas.
En la pestaña Variables ajuste desde y hasta en formato AAAA-MM-DD. En el Body de cada petición elija "tipo": Received para compras, Sent para ventas.
Las peticiones vienen preparadas para traer el rango completo. Si solo quiere comprobar que el enlace funciona antes de una consulta larga, añada "limite": 10 al cuerpo: responde en unos quince segundos. Recuerde la coma al agregarlo.
Menú View → Show Postman Console. Ahí se imprime el primer documento completo con todos sus campos, que es lo que sirve para evaluar si cubren el requerimiento.
Pulse Send y espere. La consulta abre una sesión contra el portal de la DIAN, recorre el catálogo y descarga cada XML, así que el tiempo depende de cuántos documentos haya: unos 44 por minuto.
No la cancele aunque parezca detenida. Si Postman corta la conexión no sabrá si falló el servicio o el cliente. Para rangos largos conviene poner el tiempo de espera de Postman en 0: Settings → General → Request timeout.
Un ejemplo real, con los datos del receptor sustituidos.
{
"success": true,
"total": 140,
"message": "Se obtuvieron 140 CUFE(s)",
"data": [
{
"cufe": "fca85322a318d4412db7f2c2ec67ce68c117f3f9c85212…",
"tipoDoc": "01",
"partitionKey": "co|29|fca",
"fechaEmision": "29-06-2026",
"fechaRecepcion": "29-06-2026",
"grupo": "101E",
"folio": "101E9248",
"descripcion": "Factura electrónica",
"nitEmisor": "891200701",
"nombreEmisor": "DISPROPAN SAS",
"nitReceptor": "901234567",
"nombreReceptor": "SU EMPRESA S.A.S.",
"estado": "Aprobado con notificación",
"EstadoRadian": "Factura Electrónica",
"valor": "$ 387.848",
"valorNumerico": 387848,
"impuestos": {
"iva": 53494,
"ica": 0,
"ipc": 0,
"iva5": 0,
"iva19": 0
}
}
]
}| Campo | Qué contiene |
|---|---|
| cufe | Identificador único del documento ante la DIAN. Es la llave para pedir el XML por la vía con certificado. |
| tipoDoc | Código DIAN del tipo de documento. 01 factura, 91 nota crédito, 92 nota débito, 20 documento equivalente POS, 03 contingencia. |
| descripcion | El mismo tipo, ya en texto legible. |
| fechaEmision fechaRecepcion | Cuándo se emitió y cuándo la DIAN lo recibió, en formato DD-MM-AAAA. |
| grupo · folio | Prefijo de la numeración y número del documento. |
| nitEmisor nombreEmisor | Quién le facturó. Es el dato central para conciliar cuentas por pagar. |
| nitReceptor nombreReceptor | La empresa que recibe, tal como la escribió el emisor. |
| estado | Situación ante la DIAN: Aprobado o Aprobado con notificación. |
| EstadoRadian | Estado en el registro de facturas como título valor: Factura Electrónica, Título Valor, Disponibilizada, Endosada, Pagada, No Aplica. |
| valor | Total formateado en pesos, para mostrar. |
| valorNumerico | El mismo total como número, listo para sumar sin procesar. |
| impuestos | Desglose en iva, ica, ipc, iva5 e iva19, cada uno como número. |
| partitionKey | Referencia interna del catálogo de la DIAN. |
tipo del cuerpo decide qué se consulta: Received son las compras —lo que le facturaron— y Sent las ventas. La colección viene en Received.
Esos campos salen del listado del catálogo. Cuando además se descarga el XML, cada documento llega con el detalle que el listado no tiene:
| Campo | Qué contiene |
|---|---|
| LineItems | Una entrada por línea de la factura: nombre del producto, referencia, unidad de medida, cantidad, precio unitario, total e impuestos de esa línea. |
| TaxBreakdown | Los impuestos del documento agrupados por tarifa, cada uno con su código, nombre, porcentaje, base gravable e importe. Aquí aparecen mezclados el 19 %, el 5 % y el 0 % cuando la factura los combina. |
| Sub Total Total a Pagar Retenciones | Los totales tal como los declara el XML firmado, no como texto del listado. |
| Metodo de Pago Codigo Medio de Pago | Si es de contado o a crédito, y por qué medio. |
| Fecha de Vencimiento | Cuándo vence, cuando el documento la declara. |
| Estado extracción Detalle extracción | Qué pasó con ese documento en concreto: ok, no_aplica si no era una factura, o error con su motivo. |
Una sola petición. Lo único que hay que saber es cuánto tarda y hasta dónde llega de una vez.
Se le indica el rango de fechas y si quiere compras o ventas. El servicio abre la sesión con su enlace AuthToken, recorre el catálogo y descarga el XML de cada documento, todo dentro de la misma llamada.
| Concepto | Valor |
|---|---|
| Ritmo | unos 44 documentos por minuto |
| Un mes típico (160 documentos) | unos 4 minutos |
| Máximo por llamada | 400 documentos |
| Repetir un rango ya extraído | inmediato |
| Certificado digital | no hace falta |
El ritmo no es una limitación nuestra: el portal de la DIAN restringe por dirección IP y rechaza las peticiones que van más rápido. Pedir más deprisa no entrega más documentos, solo produce rechazos. El servicio se encarga de mantener el paso y de reintentar lo que la DIAN frene, así que usted no tiene que hacer nada al respecto.
Sigue disponible y sin cambios. Devuelve el XML firmado de cada CUFE en base64, y requiere el certificado digital de la empresa, que viaja en la petición. Tiene sentido cuando ya dispone de los CUFEs por otro medio, o cuando necesita un caudal que no dependa del ritmo del portal.
| Concepto | Valor |
|---|---|
| Máximo por llamada | 500 CUFEs |
| Recomendado | 100 a 150 CUFEs |
| Tiempo por documento | 1 a 2 segundos |
| Tamaño por documento | unos 25 KB en base64 |
| Un lote de 150 | unos 4 MB, entre 3 y 6 minutos |
Sí se pueden emitir, pero no salen de esta conexión: hacen falta un certificado digital y credenciales propias.
La diferencia no es de permisos ni de plan, es de naturaleza. Lo que usa hoy solo lee. Un evento RADIAN escribe en la DIAN a nombre de quien recibe la factura: es un documento XML firmado digitalmente que queda registrado y produce efectos legales.
Listar y descargar documentos.
X-Api-KeyAcusar, aceptar o reclamar una factura.
| Evento | Cuándo se usa |
|---|---|
| Acuse de recibo de la Factura Electrónica de Venta | Se confirma que la factura llegó |
| Recibo del bien y/o prestación del servicio | Se confirma que lo facturado se recibió |
| Aceptación expresa | Se acepta la factura de forma explícita |
| Reclamo de la Factura Electrónica de Venta | Se rechaza, con su motivo |
El listado que ya usa alimenta este flujo: le entrega los CUFEs, y el evento se envía por CUFE. No hace falta resolver captcha ni construir el AttachedDocument.
Activo desde el 1 de septiembre de 2026. Importes en pesos colombianos, antes de IVA.
Cuota de disponibilidad del servicio. Se cobra completa desde el mes en que arranca, consuma o no.
Cada documento que se le entrega, por cualquiera de las dos vías. La consulta en sí no se cobra, ni tampoco revisar este consumo.
| Documentos en el mes | Precio por documento | Ejemplo: coste del mes |
|---|---|---|
| 1 – 500 | $150 | 500 docs → $75.000 |
| 501 – 2.000 | $110 | 840 docs → $92.400 |
| 2.001 – 5.000 | $80 | 3.000 docs → $240.000 |
| 5.001 – 15.000 | $55 | 10.000 docs → $550.000 |
| 15.001 – 40.000 | $38 | — |
| 40.001 – 100.000 | $30 | — |
| 100.001 – 250.000 | $27 | — |
| más de 250.000 | $25 | — |
Un mes de 840 documentos sale en $200.000 de cuota + $92.400 de consumo = $292.400 antes de IVA.
Cuánto lleva en el periodo, en cualquier momento y sin esperar a la factura.
La petición 3 · Consultar mi consumo de la colección responde con el detalle del periodo. También se puede llamar directamente:
curl -sS "https://api.tra-di.site/api/mi-consumo" \
-H "X-Api-Key: SU_CLAVE"| Campo | Qué contiene |
|---|---|
| periodo | El rango que se consultó. Revíselo siempre antes de dar una cifra por buena. |
| consumo.documentos | Documentos facturables del periodo. |
| importe.tramo_documento | El tramo de precio en el que cayó el volumen. |
| importe.precio_documento | Precio unitario de ese tramo. |
| importe.total | Total antes de IVA. |
| detalle | Por endpoint: cuántos documentos y en cuántas llamadas. |
desde y hasta en formato AAAA-MM-DD — las dos o ninguna: si envía solo una, la otra se rellena con el mes actual y sumaría dos periodos sin avisar.
Consultar el consumo no se cobra, y solo ve el suyo: la empresa se identifica por la clave, no por un parámetro.
"Sin CUFEs en el rango indicado"Puede ser que no haya documentos en ese rango, pero también que la sesión contra el portal de la DIAN no alcanzara a establecerse. Antes de concluir que no hay documentos, repita la consulta; si a la segunda tampoco devuelve nada, verifique el rango y el tipo Received o Sent. Estamos trabajando en que ambos casos se distingan solos.
Es normal, y el tiempo depende de la vía. Solo el listado: una semana responde en menos de un minuto, un mes puede tardar dos. Listado y XML: unos 44 documentos por minuto, así que un mes de 160 documentos son unos 4 minutos. El portal de la DIAN limita por dirección IP y rechaza lo que va más rápido, de modo que el servicio mantiene el paso a propósito. No la cancele: si Postman corta, no sabrá si falló el servicio o el cliente.
401 No autorizadoLa clave de acceso no llegó o no coincide. Compruebe que la variable api_key de la colección conserva el valor con el que se la entregamos y que no quedó vacía al importar.
422 con una lista de camposFalta algún dato del cuerpo o tiene mal formato. Lo más habitual son las fechas: deben ir como AAAA-MM-DD. El mensaje indica exactamente qué campo falló.
422 con rangos_sugeridosNo es un error suyo: el rango tiene más de 400 documentos y no cabe en una sola llamada. No se descargó nada y no se gastó cupo del portal. La respuesta trae los tramos de fechas en que conviene partirlo, ya calculados con los documentos que hay en cada día; copie uno en desde y hasta y repita.
no_aplicaTampoco es un error. El listado de compras incluye acuses RADIAN, que no son facturas y no tienen nada que extraer. Se le entregan igual, contados aparte como «sin factura», para que el total cuadre con lo que muestra el portal de la DIAN.
502 o un mensaje sobre el portal de la DIANEl enlace AuthToken caducó o el portal rechazó la sesión. Pida un enlace nuevo desde el portal de factura electrónica y actualice la variable url_token.
valorNumerico e impuestosLa consulta se resolvió por una vía alterna que no entrega el desglose. Repita la consulta: la vía habitual sí los incluye. Si se repite, avísenos.
Esta guía cubre lo justo para la prueba. La referencia técnica completa del servicio vive aparte.
Trece secciones con todo lo que esta guía deja fuera a propósito.
Escríbanos y lo revisamos con usted. Si prefiere, le acompañamos en la primera consulta.