> ## 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
> Valida um documento eletrônico colombiano por CUFE e NIT e consulta a doutrina tributária publicada pela DIAN.
Resolve registros publicados pela DIAN (Dirección de Impuestos y Aduanas
Nacionales): o registro de faturamento eletrônico e a compilação de doutrina
tributária (oficios, conceptos) junto com as normas e providencias compiladas
com ela.
## Documento eletrônico
`POST /co/dian/electronic-document/v1`
| Campo | Tipo | Notas |
| ----------------- | ------ | ------------------------------------------------------------------------------------------- |
| `cufe` | string | **Obrigatório.** CUFE/CUDE ou UUID do documento (30 a 100 caracteres). |
| `document_number` | string | **Obrigatório.** NIT do emissor ou do receptor (4 a 15 dígitos, sem dígito de verificação). |
```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" }'
```
A resposta retorna as partes do documento, os totais, o tenedor legítimo
atual, as validações e os eventos:
| Campo | Notas |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `found` | `true` quando o CUFE e o NIT correspondem a um documento; `false` se não coincidem ou o documento não é encontrado. |
| `document_type` | Tipo de documento, por exemplo "Factura electrónica". |
| `issuer` / `recipient` | `{ nit, name }` do emissor e do receptor. |
| `total` / `taxes` | Total do documento e linhas de impostos, em COP. |
| `legitimate_holder` | Tenedor legítimo atual no registro. |
| `validations` / `events` | Validações do documento e histórico de eventos da fatura eletrônica. |
Esta consulta pode demorar mais do que uma requisição típica. É um
[trabalho assíncrono](/pt/async-jobs). Por padrão a requisição aguarda de forma síncrona e
retorna `{ data }`, ou você pode fazer polling ou usar um `callback_url`.
## Busca de doutrina
`POST /co/dian/doctrina-search/v1`
Busca de texto completo na doutrina publicada pela DIAN e na
compilação jurídica que a acompanha: oficios, conceptos, decretos,
resoluções, leis e providencias das altas cortes.
| Campo | Tipo | Notas |
| --------------- | ------ | --------------------------------------------------------------------- |
| `query` | string | **Obrigatório.** Termos de busca (2 a 300 caracteres). |
| `document_type` | string | Opcional. Filtra por tipo, p. ex. `Oficios`, `Conceptos`, `Decretos`. |
| `year` | string | Opcional. Filtra por ano de expedição (`yyyy`). |
| `page` | number | Opcional. Página, base 1 (por padrão 1). |
| `per_page` | number | Opcional. Resultados por página, 1 a 100 (por padrão 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" }'
```
| Campo | Notas |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `query`, `document_type`, `year` | Os termos e filtros aplicados. |
| `page`, `per_page` | A página retornada e seu tamanho. |
| `total` | Correspondências após aplicar os filtros. |
| `count` | Resultados nesta página. |
| `capped` | `true` quando a fonte retornou mais correspondências do que as recuperáveis; refine a consulta. |
| `results` | Documentos encontrados, cada um com `document_id`, `title`, `document_type`, `number`, `year`, `issuer`, `summary`, `excerpt` e `url`. |
Passe o `document_id` de um resultado para a consulta seguinte para ler o texto
completo. O id é o identificador próprio do documento e nem sempre coincide
com seu rótulo visível, então pegue-o sempre de um resultado de busca em vez
de compô-lo.
## Documento de doutrina
`POST /co/dian/doctrina/v1`
| Campo | Tipo | Notas |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| `document_id` | string | **Obrigatório.** O `document_id` de um resultado de busca, p. ex. `oficio_dian_18075_2023`. |
| `offset` | number | Opcional. Primeiro caractere a retornar (por padrão 0). |
| `limit` | number | Opcional. Caracteres a retornar, 1000 a 1000000 (por padrão 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" }'
```
| Campo | Notas |
| ------------- | ------------------------------------------------------------------------------------ |
| `found` | `false` quando nenhum documento corresponde a esse id; `content` fica em `null`. |
| `document_id` | O id consultado. |
| `title` | Título oficial, por exemplo "Concepto 18075 de 2023". |
| `content` | O intervalo solicitado: `text`, `offset`, `total_length`, `has_more`, `next_offset`. |
| `url` | URL pública do documento. |
A maioria dos oficios e conceptos cabe em uma única resposta. As normas
compiladas chegam a milhões de caracteres, então o corpo é retornado por
intervalos: consulte `content.total_length` para conhecer o tamanho total e,
enquanto `content.has_more` for `true`, solicite o próximo intervalo com
`offset` igual a `content.next_offset`.
Esquema completo e um playground interativo.