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.
La diferencia entre ellas decide cuánto trámite implica el proyecto, así que conviene tenerla clara antes de empezar.
Devuelve la información de cada documento del catálogo de la DIAN. Una sola llamada para todo el rango.
Devuelve el archivo XML firmado, tal como quedó en la DIAN. Exige el certificado digital .p12 de cada 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.
Cinco pasos, una sola vez.
En Postman, Import y seleccione el archivo APIDIAN-Extractor-Piloto-Pleia.postman_collection.json. Aparecerá una colección con dos peticiones.
La dirección del servicio y la clave de acceso ya vienen configuradas.
JSON · 8 KB · formato Postman v2.1
Abra la colección, pestaña Variables, y pegue el enlace AuthToken en url_token. Guarde con Save.
Es el único valor que hay que tocar, y queda guardado para todas las consultas.
En la petición 1 · Listar documentos, pestaña Body, ajuste fechaDesde y fechaHasta en formato AAAA-MM-DD.
Viene con una semana por defecto: suficiente para revisar los campos y responde en menos de un minuto. Un mes completo tarda entre uno y dos minutos.
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 y recorre el catálogo, así que tarda entre treinta segundos y dos minutos según el rango.
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 en el paso 2. |
| 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.
Fuera del alcance del piloto. Va incluido en la colección para que se vea el servicio completo.
Devuelve el XML firmado de cada CUFE en base64. Requiere el certificado digital de la empresa emisora del catálogo, que viaja en la petición.
| 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 |
"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. Cada consulta abre una sesión de navegador contra el portal de la DIAN y recorre el catálogo. Una semana responde en menos de un minuto; un mes puede tardar dos. No la cancele antes de los tres minutos.
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ó.
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.