Buscar entidades
POST /co/contaduria-chip/entities-search/v1 Dataset
Lista as entidades que reportam ao CHIP. Combine os filtros.
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
Lista o que uma entidade reportou, um passo por vez: categorias, depois períodos, depois formulários.
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
Retorna um formulário reportado com suas linhas.
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.
Esta leitura pode demorar mais que uma solicitação típica. É um
trabalho assíncrono. 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
Busca no texto completo das demonstrações financeiras e suas notas. Combine as palavras com os filtros.
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
Retorna as demonstrações de uma entidade em um ano e o texto do documento.
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:
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.
Referência completa
Esquemas, todos os campos de resposta e um playground interativo.