Buscar entidades
POST /co/contaduria-chip/entities-search/v1 Dataset
Lista las entidades que reportan al CHIP. Combine los filtros.
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
Lista lo que reportó una entidad, un paso a la vez: categorías, luego periodos, luego formularios.
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
Devuelve un formulario reportado con sus filas.
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.
Esta lectura puede tardar más que una solicitud típica. Es un
trabajo asíncrono. 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
Busca en el texto completo de los estados financieros y sus notas. Combine las palabras con los filtros.
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
Devuelve los estados financieros de una entidad en un año y el texto del documento.
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:
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.
Referencia completa
Esquemas, todos los campos de respuesta y un playground interactivo.