> ## 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 un documento electrónico colombiano por CUFE y NIT, y consulta la doctrina tributaria publicada por la DIAN.
Resuelve registros publicados por la DIAN (Dirección de Impuestos y Aduanas
Nacionales): el registro de facturación electrónica y la compilación de doctrina
tributaria (oficios, conceptos) junto con las normas y providencias compiladas
con ella.
## Documento electrónico
`POST /co/dian/electronic-document/v1`
| Campo | Tipo | Notas |
| ----------------- | ------ | -------------------------------------------------------------------------------------- |
| `cufe` | string | **Requerido.** CUFE/CUDE o UUID del documento (30 a 100 caracteres). |
| `document_number` | string | **Requerido.** NIT del emisor o receptor (4 a 15 dígitos, sin dígito de verificación). |
```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" }'
```
La respuesta devuelve las partes del documento, los totales, el tenedor legítimo
actual, las validaciones y los eventos:
| Campo | Notas |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `found` | `true` cuando el CUFE y el NIT corresponden a un documento; `false` si no coinciden o no se encuentra. |
| `document_type` | Tipo de documento, por ejemplo "Factura electrónica". |
| `issuer` / `recipient` | `{ nit, name }` del emisor y del receptor. |
| `total` / `taxes` | Total del documento y líneas de impuestos, en COP. |
| `legitimate_holder` | Tenedor legítimo actual en el registro. |
| `validations` / `events` | Validaciones del documento e historial de eventos de la factura electrónica. |
Esta consulta puede tardar más que una petición típica. Es un
[trabajo asíncrono](/es/async-jobs). Por defecto la petición espera en línea y
devuelve `{ data }`, o puedes hacer polling o usar un `callback_url`.
## Búsqueda de doctrina
`POST /co/dian/doctrina-search/v1`
Búsqueda de texto completo sobre la doctrina publicada por la DIAN y la
compilación jurídica que la acompaña: oficios, conceptos, decretos,
resoluciones, leyes y providencias de las altas cortes.
| Campo | Tipo | Notas |
| --------------- | ------ | --------------------------------------------------------------------- |
| `query` | string | **Requerido.** Términos de búsqueda (2 a 300 caracteres). |
| `document_type` | string | Opcional. Filtra por tipo, p. ej. `Oficios`, `Conceptos`, `Decretos`. |
| `year` | string | Opcional. Filtra por año de expedición (`yyyy`). |
| `page` | number | Opcional. Página, base 1 (por defecto 1). |
| `per_page` | number | Opcional. Resultados por página, 1 a 100 (por defecto 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` | Los términos y filtros aplicados. |
| `page`, `per_page` | La página devuelta y su tamaño. |
| `total` | Coincidencias después de aplicar los filtros. |
| `count` | Resultados en esta página. |
| `capped` | `true` cuando la fuente devolvió más coincidencias de las recuperables; refine la consulta. |
| `results` | Documentos encontrados, cada uno con `document_id`, `title`, `document_type`, `number`, `year`, `issuer`, `summary`, `excerpt` y `url`. |
Pase el `document_id` de un resultado a la consulta siguiente para leer el texto
completo. El id es el identificador propio del documento y no siempre coincide
con su etiqueta visible, así que tómelo siempre de un resultado de búsqueda en
lugar de componerlo.
## Documento de doctrina
`POST /co/dian/doctrina/v1`
| Campo | Tipo | Notas |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| `document_id` | string | **Requerido.** El `document_id` de un resultado de búsqueda, p. ej. `oficio_dian_18075_2023`. |
| `offset` | number | Opcional. Primer carácter a devolver (por defecto 0). |
| `limit` | number | Opcional. Caracteres a devolver, 1000 a 1000000 (por defecto 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` cuando ningún documento corresponde a ese id; `content` queda en `null`. |
| `document_id` | El id consultado. |
| `title` | Título oficial, por ejemplo "Concepto 18075 de 2023". |
| `content` | El rango solicitado: `text`, `offset`, `total_length`, `has_more`, `next_offset`. |
| `url` | URL pública del documento. |
La mayoría de oficios y conceptos caben en una sola respuesta. Las normas
compiladas alcanzan millones de caracteres, así que el cuerpo se devuelve por
rangos: consulte `content.total_length` para conocer el tamaño total y, mientras
`content.has_more` sea `true`, solicite el siguiente rango con `offset` igual a
`content.next_offset`.
Esquema completo y un playground interactivo.