Three changes to POST /co/dian/electronic-document/v1, the lookup of an electronic invoice by CUFE and NIT, prompted by a team that reconciles hundreds of invoices a day. Nothing changes for anyone already using it: the new fields sit next to the existing ones and the default behavior is the same.
Every event, with its fields#
Until now an event arrived as a single line of text, and pulling the code out of it was the client's job. Now every row of the history carries its columns separately:
{
"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"
}| Field | What it carries |
|---|---|
code | The event's code in the registry: 030 acknowledgement of receipt, 032 receipt of the goods or service, 033 express acceptance, 036 RADIAN registration, 037 endorsement, among others |
name | The event's name as the registry publishes it |
date | The event's date |
issuer and recipient | Who issued the event and who it is addressed to, with nit and name. They do not always match the invoice's parties: an endorsement is issued by the holder, not the issuer |
cude | The event's key in the registry |
description | The whole row as one string, exactly as before, for anyone already parsing it |
With code, a rule like "the invoice has a 032 and no 033" is a comparison, not a regular expression.
Reading the registry again#
A lookup is reused for 24 hours per cufe, document_number and include_pdf, and the response says so with the X-Cache: HIT header. That is right for most cases and wrong right after filing an event: the invoice had changed in the registry and the lookup kept answering with the previous result until the window ran out.
When you know the registry changed, send 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
}'The response comes back with X-Cache: MISS, is charged as a new request and replaces the stored one, so the next lookup without the parameter already returns what this one found. cache defaults to true, and nothing changes for anyone who does not send it.
Totals as DIAN publishes them#
total and every value in taxes come in whole pesos because that is how the registry publishes them. An invoice for $2,083,576.95 appears in the registry as $2,083,577, and that is what we return: we do not round, and there are no centavos to keep from that source. The exact amount is on the official PDF representation, available with include_pdf: true. The documentation now says so on the fields themselves, so a reconciliation to the cent knows from the start where to look.
The full guide is at DIAN.