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

> Relatórios financeiros e orçamentários das entidades públicas colombianas, como cada uma os reporta à Contaduría General de la Nación pelo CHIP: saldos, execução orçamentária e mais, por entidade, período e formulário.

Toda entidade pública colombiana (ministérios, departamentos, municípios, empresas
públicas, hospitais, universidades) reporta sua contabilidade e seu orçamento à
Contaduría General de la Nación pelo CHIP, o Consolidador de Hacienda e
Información Pública. Cada relatório é um formulário de um período: as contas do
balanço com saldo inicial, movimentos e saldo final; as receitas e despesas do
orçamento como programadas e como executadas; tesouraria, dívida, royalties e
mais.

Estes endpoints retornam esses relatórios como dados: as entidades que reportam, o
que cada uma reportou, e qualquer formulário com toda a sua árvore de contas e valores.

Também retornam as demonstrações financeiras que cada entidade apresenta uma vez por
ano, com suas notas: o documento, seu texto completo e uma busca no texto de todas.

## Buscar entidades

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

Lista as entidades que reportam ao CHIP. Combine os filtros.

| Campo | Tipo | Notas |
| - | - | - |
| `query` | string | Opcional. Palavras do nome da entidade. Não diferencia maiúsculas nem acentos. |
| `entity_code` | string | Opcional. Um código CHIP, p. ex. `210105001`: essa entidade. |
| `tax_id` | string | Opcional. NIT sem dígito verificador, p. ex. `890905211`. |
| `department` | string | Opcional. Departamento, p. ex. `ANTIOQUIA`. |
| `municipality` | string | Opcional. Município, p. ex. `MEDELLIN`. |
| `status` | enum | Opcional. `active` ou `inactive`. |
| `page` | integer | Opcional. Página, começa em 1. Por padrão `1`. |
| `per_page` | integer | Opcional. Resultados por página, 1-100. Por padrão `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" }'
```

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

## Índice de relatórios

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

Lista o que uma entidade reportou, um passo por vez: categorias, depois períodos, depois formulários.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obrigatório.** O código CHIP da entidade, p. ex. `210105001`. |
| `category_code` | string | Opcional. Um código de categoria de `categories[]`, p. ex. `K70`: também retorna `periods[]`. |
| `period` | string | Opcional, com `category_code`. Um período de `periods[]`, p. ex. `2026-07/2026-09`: também retorna `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" }'
```

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

## Relatório

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

Retorna um formulário reportado com suas linhas.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obrigatório.** O código CHIP da entidade, p. ex. `210105001`. |
| `category_code` | string | **Obrigatório.** O código da categoria, p. ex. `K70`. |
| `period` | string | **Obrigatório.** Primeiro e último mês do período, `YYYY-MM/YYYY-MM`, p. ex. `2026-07/2026-09`. |
| `form_code` | string | **Obrigatório.** O código do formulário, p. ex. `168`. |
| `level` | integer,null | Opcional. Profundidade da árvore a retornar: `1` são apenas as contas de primeiro nível. Omita para todos os níveis. Por padrão `null`. |
| `page` | integer | Opcional. Página de linhas, começa em 1. Por padrão `1`. |
| `per_page` | integer | Opcional. Linhas por página, 1-500. Padrão `100`. Por padrão `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
      }'
```

Retorna `found`, `entity`, `category`, `form`, `period`, `scope`, `submission_number`, `received_at`, `columns[]`, `rows[]` com sua paginação (`total`, `page`, `per_page`, `total_pages`, `count`), `document_url`, `checked_at` e `served_from` (ver abaixo). `found` é `false`, nunca um erro, quando a entidade não reportou esse formulário nesse período.

> [!NOTE]
>
> Esta leitura pode demorar mais que uma solicitação típica. É um
> [trabalho assíncrono](https://docs.usecroma.com/pt/async-jobs.md). Por padrão a solicitação aguarda de forma
> síncrona e retorna `{ data }`, ou você pode fazer polling ou usar um `callback_url`. Um
> relatório lido há pouco responde de imediato: `served_from` diz qual, e
> `checked_at` quando a fonte foi consultada pela última vez.

## Buscar demonstrações financeiras

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

Busca no texto completo das demonstrações financeiras e suas notas. Combine as palavras com os filtros.

| Campo | Tipo | Notas |
| - | - | - |
| `query` | string | Opcional. Palavras ou uma pergunta, buscadas no texto de cada documento, p. ex. `litigios y demandas provisión`. Sem ele, são listadas as demonstrações que atendem aos filtros. |
| `entity_code` | string | Opcional. Um código CHIP, p. ex. `210105001`: apenas as demonstrações dessa entidade. |
| `year` | integer,null | Opcional. Ano fiscal, p. ex. `2025`. Por padrão `null`. |
| `department` | string | Opcional. Departamento da entidade, p. ex. `ANTIOQUIA`. |
| `municipality` | string | Opcional. Município da entidade, p. ex. `MEDELLIN`. |
| `page` | integer | Opcional. Página de resultados, começa em 1. Por padrão `1`. |
| `per_page` | integer | Opcional. Resultados por página, 1-50. Padrão `10`. Por padrão `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
      }'
```

Retorna `as_of`, os filtros como foram lidos, `total`, `total_is_exact`, `page`, `per_page`, `total_pages`, `count` e `results[]`: cada demonstração (`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`) com `matches[]`: até três trechos, cada um com `page_number`, `text`, `start` e `end`.

## Demonstrações financeiras

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

Retorna as demonstrações de uma entidade em um ano e o texto do documento.

| Campo | Tipo | Notas |
| - | - | - |
| `entity_code` | string | **Obrigatório.** O código CHIP da entidade, p. ex. `210105001`. |
| `year` | integer | **Obrigatório.** Ano fiscal, p. ex. `2025`. |
| `page_number` | integer,null | Opcional. Uma página do documento para retorná-la inteira, p. ex. `12`. Por padrão `null`. |
| `offset` | integer | Opcional. Primeiro caractere do intervalo. Passe o `next_offset` anterior para continuar lendo. Por padrão `0`. |
| `limit` | integer | Opcional. Máximo de caracteres a retornar, 1000-1000000. Padrão `200000`. Por padrão `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 }'
```

Retorna `as_of`, `found`, `entity_code`, `year` e `statement`: os campos de um resultado de busca mais `text_url`, `page_number` e `content` (`text`, `offset`, `total_length`, `has_more`, `next_offset`, `from_page`, `to_page`). `found` é `false`, nunca um erro, quando não há demonstrações dessa entidade para esse ano.

## Como os três se encaixam

Comece pela busca de entidades para obter um código CHIP. Pergunte ao índice de relatórios o que essa entidade reportou: suas categorias, depois os períodos de uma categoria, depois os formulários de um período. Passe os quatro valores (`entity_code`, `category_code`, `period`, `form_code`) ao endpoint do relatório.

### `columns[]` e `rows[]`

Cada formulário tem suas próprias colunas, então o relatório as descreve em vez de fixá-las:

| Campo | Notas |
| - | - |
| `columns[].key` | A chave dessa coluna em `values` de cada linha. |
| `columns[].name` | O nome da coluna, como o formulário imprime (`SALDO FINAL`). |
| `columns[].unit` | `pesos`, `thousands_of_pesos` ou `unit` em uma coluna de valores; `null` em uma de texto. Os períodos contábeis antigos vêm em milhares: leia sempre a unidade. |
| `columns[].type` | `amount` (números) ou `text` (o texto do formulário). |
| `rows[].code` | O código da linha na árvore do formulário, com pontos (`1.1.05.01`). |
| `rows[].name` | A conta ou o conceito. |
| `rows[].level` | Profundidade na árvore: `1` no topo, mais um a cada ponto. |
| `rows[].parent_code` | O código do nível acima, `null` no topo. |
| `rows[].values` | As células por chave de coluna. |

Uma linha pai já soma suas filhas: some linhas de um mesmo nível, nunca de vários.

`submission_number` e `received_at` dizem qual envio o relatório mostra. Uma entidade que corrige um período faz um novo envio, então uma leitura posterior do mesmo período pode trazer outro número.

`document_url` é a cópia da Croma do relatório como a fonte o exporta, uma planilha Excel com todas as linhas de todos os níveis.

> [card] [Referência completa](https://docs.usecroma.com/pt/api-reference/overview.md)
>
> Esquemas, todos os campos de resposta e um playground interativo.


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