Três mudanças em POST /co/dian/electronic-document/v1, a consulta de uma fatura eletrônica por CUFE e NIT, a partir do que nos pediu uma equipe que concilia centenas de faturas por dia. Nada muda para quem já a usa: os campos novos se somam aos que existiam e o comportamento padrão é o mesmo.
Cada evento, com seus campos#
Até agora um evento chegava como uma única linha de texto, e extrair o código dali era trabalho do cliente. Agora cada linha do histórico traz suas colunas separadas:
{
"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 | O que traz |
|---|---|
code | O código do evento no registro: 030 confirmação de recebimento, 032 recebimento do bem ou serviço, 033 aceitação expressa, 036 inscrição no RADIAN, 037 endosso, entre outros |
name | O nome do evento como o registro o publica |
date | A data do evento |
issuer e recipient | Quem emitiu o evento e a quem ele se dirige, com nit e name. Nem sempre coincidem com as partes da fatura: um endosso é emitido pelo portador, não pelo emissor |
cude | A chave do evento no registro |
description | A linha inteira em um só texto, igual a antes, para quem já a interpreta |
Com code, uma regra como "a fatura tem 032 e não tem 033" é uma comparação, não uma expressão regular.
Ler o registro de novo#
Uma consulta é reutilizada por 24 horas por cufe, document_number e include_pdf, e a resposta avisa com o cabeçalho X-Cache: HIT. É o certo na maioria dos casos, e é um problema logo depois de registrar um evento: a fatura mudou no registro e a consulta continuava devolvendo a resposta anterior até a janela acabar.
Quando você sabe que o registro mudou, envie 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
}'A resposta vem com X-Cache: MISS, é cobrada como uma consulta nova e substitui a armazenada, então a próxima consulta sem o parâmetro já devolve o que esta encontrou. Por padrão cache é true, e nada muda para quem não o envia.
Os totais, como a DIAN os publica#
total e cada valor de taxes vêm em pesos inteiros porque é assim que o registro os publica. Uma fatura de $2.083.576,95 aparece no registro como $2.083.577, e é isso que devolvemos: não arredondamos, e não há centavos a preservar nessa fonte. O valor exato está na representação PDF oficial, obtida com include_pdf: true. A documentação agora diz isso nos próprios campos, para que uma conciliação ao centavo saiba desde o início onde procurar.
O guia completo está em DIAN.