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

# Contaduría CHIP

> Reportes financieros y presupuestales de las entidades públicas colombianas, tal como cada una los reporta a la Contaduría General de la Nación en el CHIP: saldos, ejecución presupuestal y más, por entidad, periodo y formulario.

Toda entidad pública colombiana (ministerios, departamentos, municipios, empresas
públicas, hospitales, universidades) reporta su contabilidad y su presupuesto a la
Contaduría General de la Nación en el CHIP, el Consolidador de Hacienda e
Información Pública. Cada reporte es un formulario de un periodo: las cuentas del
balance con su saldo inicial, movimientos y saldo final; los ingresos y gastos del
presupuesto como se programaron y como se ejecutaron; tesorería, deuda, regalías y
más.

Estos endpoints devuelven esos reportes como datos: las entidades que reportan, qué
reportó cada una, y cualquier formulario con todo su árbol de cuentas y valores.

También devuelven los estados financieros que cada entidad presenta una vez al año,
con sus notas: el documento, su texto completo y una búsqueda en el texto de todos.

## Buscar entidades

`POST /co/contaduria-chip/entities-search/v1` [Dataset](https://docs.usecroma.com/es/datasets.md)

Lista las entidades que reportan al CHIP. Combine los filtros.

| Campo | Tipo | Notas |
| - | - | - |
| `query` | string | Opcional. Palabras del nombre de la entidad. No distingue mayúsculas ni tildes. |
| `entity_code` | string | Opcional. Un código CHIP, p. ej. `210105001`: esa entidad. |
| `tax_id` | string | Opcional. NIT sin dígito de verificación, p. ej. `890905211`. |
| `department` | string | Opcional. Departamento, p. ej. `ANTIOQUIA`. |
| `municipality` | string | Opcional. Municipio, p. ej. `MEDELLIN`. |
| `status` | enum | Opcional. `active` o `inactive`. |
| `page` | integer | Opcional. Página, empieza en 1. Por defecto `1`. |
| `per_page` | integer | Opcional. Resultados por página, 1-100. Por defecto `20`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/entities-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "medellin", "department": "ANTIOQUIA" }'
```

Devuelve `as_of`, `query`, `total`, `page`, `per_page`, `total_pages`, `count` y `entities[]`: `entity_code`, `name`, `tax_id`, `tax_id_check_digit`, `address`, `phone`, `department`, `municipality`, `status`, `sector` y `nature`.

## Índice de reportes

`POST /co/contaduria-chip/report-index/v1` [Live](https://docs.usecroma.com/es/live-lookups.md)

Lista lo que reportó una entidad, un paso a la vez: categorías, luego periodos, luego formularios.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obligatorio.** El código CHIP de la entidad, p. ej. `210105001`. |
| `category_code` | string | Opcional. Un código de categoría de `categories[]`, p. ej. `K70`: también devuelve `periods[]`. |
| `period` | string | Opcional, con `category_code`. Un periodo de `periods[]`, p. ej. `2026-07/2026-09`: también devuelve `forms[]`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/report-index/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_code": "210105001", "category_code": "K70" }'
```

Devuelve `found`, `entity`, `categories[]` (`category_code`, `name`, `retired`), `category_code`, `periods[]` (`period`, `label`, `start_date`, `end_date`), `period`, `forms[]` (`form_code`, `name`) y `checked_at`.

## Reporte

`POST /co/contaduria-chip/report/v1` [Live](https://docs.usecroma.com/es/live-lookups.md)

Devuelve un formulario reportado con sus filas.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obligatorio.** El código CHIP de la entidad, p. ej. `210105001`. |
| `category_code` | string | **Obligatorio.** El código de la categoría, p. ej. `K70`. |
| `period` | string | **Obligatorio.** Primer y último mes del periodo, `YYYY-MM/YYYY-MM`, p. ej. `2026-07/2026-09`. |
| `form_code` | string | **Obligatorio.** El código del formulario, p. ej. `168`. |
| `level` | integer,null | Opcional. Profundidad del árbol a devolver: `1` son solo las cuentas de primer nivel. Omítalo para todos los niveles. Por defecto `null`. |
| `page` | integer | Opcional. Página de filas, empieza en 1. Por defecto `1`. |
| `per_page` | integer | Opcional. Filas por página, 1-500. Por defecto `100`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/report/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "entity_code": "210105001",
        "category_code": "K70",
        "period": "2026-07/2026-09",
        "form_code": "168",
        "level": 2
      }'
```

Devuelve `found`, `entity`, `category`, `form`, `period`, `scope`, `submission_number`, `received_at`, `columns[]`, `rows[]` con su paginación (`total`, `page`, `per_page`, `total_pages`, `count`), `document_url`, `checked_at` y `served_from` (ver abajo). `found` es `false`, nunca un error, cuando la entidad no reportó ese formulario en ese periodo.

> [!NOTE]
>
> Esta lectura puede tardar más que una solicitud típica. Es un
> [trabajo asíncrono](https://docs.usecroma.com/es/async-jobs.md). Por defecto la solicitud espera en línea y
> devuelve `{ data }`, o puedes hacer polling o usar un `callback_url`. Un reporte
> leído hace poco responde de inmediato: `served_from` dice cuál, y
> `checked_at` cuándo se consultó la fuente por última vez.

## Buscar estados financieros

`POST /co/contaduria-chip/statements-search/v1` [Dataset](https://docs.usecroma.com/es/datasets.md)

Busca en el texto completo de los estados financieros y sus notas. Combine las palabras con los filtros.

| Campo | Tipo | Notas |
| - | - | - |
| `query` | string | Opcional. Palabras o una pregunta, buscadas en el texto de cada documento, p. ej. `litigios y demandas provisión`. Sin él, se listan los estados financieros que cumplen los filtros. |
| `entity_code` | string | Opcional. Un código CHIP, p. ej. `210105001`: solo los estados financieros de esa entidad. |
| `year` | integer,null | Opcional. Año fiscal, p. ej. `2025`. Por defecto `null`. |
| `department` | string | Opcional. Departamento de la entidad, p. ej. `ANTIOQUIA`. |
| `municipality` | string | Opcional. Municipio de la entidad, p. ej. `MEDELLIN`. |
| `page` | integer | Opcional. Página de resultados, empieza en 1. Por defecto `1`. |
| `per_page` | integer | Opcional. Resultados por página, 1-50. Por defecto `10`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/statements-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "litigios y demandas provisión",
        "entity_code": "210105001",
        "year": 2025
      }'
```

Devuelve `as_of`, los filtros como se leyeron, `total`, `total_is_exact`, `page`, `per_page`, `total_pages`, `count` y `results[]`: cada estado financiero (`statement_id`, `entity_code`, `entity_name`, `tax_id`, `department`, `municipality`, `sector`, `category_code`, `category_name`, `year`, `start_date`, `end_date`, `scope`, `submission_number`, `document_name`, `document_url`, `document_bytes`, `pages`, `text_length`, `checked_at`) con `matches[]`: hasta tres pasajes, cada uno con su `page_number`, `text`, `start` y `end`.

## Estados financieros

`POST /co/contaduria-chip/statement/v1` [Dataset](https://docs.usecroma.com/es/datasets.md)

Devuelve los estados financieros de una entidad en un año y el texto del documento.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obligatorio.** El código CHIP de la entidad, p. ej. `210105001`. |
| `year` | integer | **Obligatorio.** Año fiscal, p. ej. `2025`. |
| `page_number` | integer,null | Opcional. Una página del documento para devolverla completa, p. ej. `12`. Por defecto `null`. |
| `offset` | integer | Opcional. Primer carácter del rango. Pase el `next_offset` anterior para seguir leyendo. Por defecto `0`. |
| `limit` | integer | Opcional. Máximo de caracteres a devolver, 1000-1000000. Por defecto `200000`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/statement/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_code": "210105001", "year": 2025, "page_number": 12 }'
```

Devuelve `as_of`, `found`, `entity_code`, `year` y `statement`: los campos de un resultado de búsqueda más `text_url`, `page_number` y `content` (`text`, `offset`, `total_length`, `has_more`, `next_offset`, `from_page`, `to_page`). `found` es `false`, nunca un error, cuando no hay estados financieros de esa entidad para ese año.

## Cómo se usan los tres

Empiece por la búsqueda de entidades para obtener un código CHIP. Pregunte al índice de reportes qué reportó esa entidad: sus categorías, luego los periodos de una categoría, luego los formularios de un periodo. Pase los cuatro valores (`entity_code`, `category_code`, `period`, `form_code`) al endpoint del reporte.

### `columns[]` y `rows[]`

Cada formulario tiene sus propias columnas, así que el reporte las describe en vez de fijarlas:

| Campo | Notas |
| - | - |
| `columns[].key` | La clave de esa columna en `values` de cada fila. |
| `columns[].name` | El nombre de la columna, como lo imprime el formulario (`SALDO FINAL`). |
| `columns[].unit` | `pesos`, `thousands_of_pesos` o `unit` en una columna de valores; `null` en una de texto. Los periodos contables antiguos vienen en miles: lea siempre la unidad. |
| `columns[].type` | `amount` (números) o `text` (el texto del formulario). |
| `rows[].code` | El código de la fila en el árbol del formulario, con puntos (`1.1.05.01`). |
| `rows[].name` | La cuenta o el concepto. |
| `rows[].level` | Profundidad en el árbol: `1` arriba, uno más por cada punto. |
| `rows[].parent_code` | El código del nivel superior, `null` arriba. |
| `rows[].values` | Las celdas por clave de columna. |

Una fila padre ya suma a sus hijas: sume filas de un mismo nivel, nunca de varios.

`submission_number` y `received_at` dicen qué envío muestra el reporte. Una entidad que corrige un periodo hace un envío nuevo, así que una lectura posterior del mismo periodo puede traer otro número.

`document_url` es la copia de Croma del reporte tal como lo exporta la fuente, un libro de Excel con todas las filas de todos los niveles.

> [card] [Referencia completa](https://docs.usecroma.com/es/api-reference/overview.md)
>
> Esquemas, todos los campos de respuesta y un playground interactivo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.