> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DIAN

> Validate a Colombian electronic document by CUFE and NIT, and search DIAN's published tax doctrine.

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). |

```bash theme={"dark"}
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.                          |

<Note>
  This lookup can take longer than a typical request. It's an
  [async job](/async-jobs). By default the request waits inline and returns
  `{ data }`, or you can poll / use a `callback_url`.
</Note>

## 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).                    |

```bash theme={"dark"}
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).                    |

```bash theme={"dark"}
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`.

<Card title="Full reference" icon="code" href="/api-reference/overview">
  Full schema and an interactive playground.
</Card>