DIAN

Resolves records published by DIAN (Dirección de Impuestos y Aduanas Nacionales): the electronic-invoice registry, and the compilation of tax doctrine (oficios, conceptos) with the norms and rulings compiled alongside it.

Electronic document

POST /co/dian/electronic-document/v1

Field	Type	Notes
`cufe`	string	Required. The document’s CUFE/CUDE or UUID (30-100 chars).
`document_number`	string	Required. NIT of the emisor or receptor (4-15 digits, no verification digit).

curl https://api.croma.run/co/dian/electronic-document/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cufe": "0123456789abcdef...0123456789abcdef", "document_number": "900123456" }'

The response returns the document’s parties, totals, current legitimate holder, validations, and events:

Field	Notes
`found`	`true` when the CUFE and NIT resolve to a document; `false` on a mismatch or not-found.
`document_type`	Document class label, e.g. “Factura electrónica”.
`issuer` / `recipient`	`{ nit, name }` of the emisor and receptor.
`total` / `taxes`	Document total and tax lines, in COP.
`legitimate_holder`	Current legitimate holder (tenedor legítimo) in the registry.
`validations` / `events`	Document validations and the electronic-invoice event history.

This lookup can take longer than a typical request. It’s an async job. By default the request waits inline and returns { data }, or you can poll / use a callback_url.

Doctrine search

POST /co/dian/doctrina-search/v1 Full-text search over DIAN’s published doctrine and the legal compilation kept with it: oficios, conceptos, decretos, resoluciones, leyes, and high-court rulings.

Field	Type	Notes
`query`	string	Required. Search terms (2-300 characters).
`document_type`	string	Optional. Filter by type, e.g. `Oficios`, `Conceptos`, `Decretos`.
`year`	string	Optional. Filter by year of issue (`yyyy`).
`page`	number	Optional. 1-based page (default 1).
`per_page`	number	Optional. Results per page, 1-100 (default 20).

curl https://api.croma.run/co/dian/doctrina-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "dividendos", "document_type": "Conceptos" }'

Field	Notes
`query`, `document_type`, `year`	The terms and filters applied.
`page`, `per_page`	The page returned and its size.
`total`	Matches after filters.
`count`	Results on this page.
`capped`	`true` when the source returned more matches than are retrievable; narrow the query.
`results`	Matching documents, each with `document_id`, `title`, `document_type`, `number`, `year`, `issuer`, `summary`, `excerpt`, and `url`.

Pass a result’s document_id to the lookup below to read the full text. The id is the document’s own identifier and does not always match its visible label, so always take it from a search result rather than composing it.

Doctrine document

POST /co/dian/doctrina/v1

Field	Type	Notes
`document_id`	string	Required. The `document_id` from a search result, e.g. `oficio_dian_18075_2023`.
`offset`	number	Optional. First character to return (default 0).
`limit`	number	Optional. Characters to return, 1000 to 1000000 (default 200000).

curl https://api.croma.run/co/dian/doctrina/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document_id": "oficio_dian_18075_2023" }'

Field	Notes
`found`	`false` when no document carries that id; `content` is then `null`.
`document_id`	The id queried.
`title`	Official title, e.g. “Concepto 18075 de 2023”.
`content`	The requested range: `text`, `offset`, `total_length`, `has_more`, `next_offset`.
`url`	Public URL of the document.

Most oficios and conceptos fit in a single response. Compiled norms run to millions of characters, so the body comes back in ranges: read content.total_length for the full size, and while content.has_more is true request the next range with offset set to content.next_offset.

Full reference

Full schema and an interactive playground.

Get Started

Countries

Electronic document

Doctrine search

Doctrine document

Full reference

​Electronic document

​Doctrine search

​Doctrine document

Full reference

Electronic document

Doctrine search

Doctrine document