Tres cambios en POST /co/dian/electronic-document/v1, la consulta de una factura electrónica por CUFE y NIT, a partir de lo que nos pidió un equipo que concilia cientos de facturas al día. Nada cambia para quien ya la usa: los campos nuevos se suman a los que había y el comportamiento por defecto es el mismo.
Cada evento, con sus campos#
Hasta ahora un evento llegaba como una sola línea de texto, y sacar el código de ahí era trabajo del cliente. Ahora cada fila del historial trae sus columnas por separado:
{
"code": "032",
"name": "Recibo del bien o prestación del servicio",
"date": "2026-02-05",
"issuer": { "nit": "900123456", "name": "ACME SAS" },
"recipient": { "nit": "800654321", "name": "BANCO XYZ" },
"cude": "6fc8dbca25dffe01f9da...",
"description": "032 · Recibo del bien o prestación del servicio · 2026-02-05 · 900123456 · ACME SAS · 800654321 · BANCO XYZ · Ver detalle"
}| Campo | Qué trae |
|---|---|
code | El código del evento en el registro: 030 acuse de recibo, 032 recibo del bien o servicio, 033 aceptación expresa, 036 inscripción en el RADIAN, 037 endoso, entre otros |
name | El nombre del evento tal como lo publica el registro |
date | La fecha del evento |
issuer y recipient | Quién emitió el evento y a quién va dirigido, con nit y name. No siempre coinciden con las partes de la factura: un endoso lo emite el tenedor, no el emisor |
cude | La clave del evento en el registro |
description | La fila completa en un solo texto, igual que antes, para quien ya la interpreta |
Con code una regla como "la factura tiene 032 y no tiene 033" es una comparación, no una expresión regular.
Volver a leer el registro#
Una consulta se reutiliza durante 24 horas por cufe, document_number e include_pdf, y la respuesta lo dice con el encabezado X-Cache: HIT. Es lo correcto para la mayoría de los casos, y es un problema justo después de radicar un evento: la factura cambió en el registro y la consulta seguía devolviendo la respuesta anterior hasta que vencía la ventana.
Cuando sabes que el registro cambió, envía cache: false:
curl https://api.croma.run/co/dian/electronic-document/v1 \
-H "Authorization: Bearer $CROMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cufe": "0123456789abcdef0123456789abcdef0123456789abcdef",
"document_number": "900123456",
"cache": false
}'La respuesta llega con X-Cache: MISS, se cobra como una consulta nueva y reemplaza a la guardada, así que la siguiente consulta sin el parámetro ya devuelve lo que esta encontró. Por defecto cache es true y nada cambia para quien no lo envía.
Los totales, tal como los publica la DIAN#
total y cada valor de taxes vienen en pesos enteros porque así los publica el registro. Una factura de $2.083.576,95 aparece en el registro como $2.083.577, y eso es lo que devolvemos: no redondeamos nosotros, y no hay centavos que conservar en esa fuente. El monto exacto está en la representación PDF oficial, que se obtiene con include_pdf: true. La documentación ahora lo dice en los propios campos, para que una conciliación al centavo sepa desde el principio dónde buscarlo.
La guía completa está en DIAN.