guia · v1
Guia da API
Referência completa da API pública. Prefere explorar interativamente? Use o Swagger em api.balancos.ai/v1/docs.
comece aqui
Crie uma chave e faça a primeira chamada
- Crie uma conta gratuita e gere sua chave em Minha conta → Chaves de API. A chave (
bal_live_…) aparece uma única vez — copie e guarde antes de fechar o aviso. - Envie a chave no header, em toda chamada de dados:
Authorization: Bearer bal_live_…. - Faça a primeira chamada:
curl "https://api.balancos.ai/v1/empresas?q=petrobras" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Uma chamada admitida conta pra sua cota — mesmo terminando em erro. Veja o que conta e o que não conta em Limites.
integração
Explore a API no Postman
A collection reúne todas as versões publicadas da API, cada uma em sua pasta, com as rotas e os parâmetros prontos para editar. Hoje, a versão disponível é a v1.
- Clique em Adicionar ao Postman e depois em Fork Collection para criar uma cópia no seu workspace. Se preferir o download, clique em Import no Postman e selecione o arquivo baixado.
- Abra a collection → Variables. Preencha
api_keycom sua chave de Minha conta, sem o prefixoBearer, somente no valor local. Não compartilhe nem exporte sua chave. - Abra a pasta da versão: dentro dela há uma subpasta por fonte — Empresas, CVM e BCB. Cada uma usa a própria variável de chave, já preenchida com um exemplo real:
chave(CNPJ sem pontuação ou slug, na pasta Empresas),chave_cvm(CNPJ ou código CVM) eid_doc(entrega) na CVM,chave_bcb(CodInst, CNPJ ou raiz),codinst(conglomerado) edata_baseno BCB. Troque o valor em Variables pra consultar outra companhia ou instituição. - Em Params, marque os filtros opcionais que quiser usar e clique em Send. As chamadas consomem a cota normal da conta.
O workspace público também oferece o environment Balanços.AI — Produção. Se fizer um fork dele, selecione-o e preencha api_key no valor local do environment, que tem prioridade sobre a variável da collection.
A collection oficial é atualizada automaticamente. No seu fork, use Pull changes para trazer as novidades. O JSON baixado é uma cópia daquele momento: reimporte-o quando quiser atualizar.
Para importar por URL, use https://balancos.ai/api/balancos-ai.postman_collection.json.
autenticação
Uma chave, um header
Toda rota de dados (/v1/*) exige o header Authorization: Bearer bal_live_…. A chave tem o formato bal_live_ seguido de 43 caracteres — gerada com 256 bits de entropia, sem necessidade de rotação por padrão.
- Bearer ausente, malformado, inexistente ou revogado responde
401 chave_invalida, sem custo de cota. - Até 5 chaves ativas por conta; revogar não apaga o histórico de consumo dela.
- A chave em claro só existe na resposta da criação — o site nunca guarda ela em cookie ou
localStorage, e não é possível recuperá-la depois. Perdeu? Revogue e crie outra.
/v1/docs, /v1/openapi.json, /v1/health e /v1 não exigem chave. As rotas de gestão (/conta/*) usam a sessão do site, não a chave — é o que o bloco Chaves de API em Minha conta chama por trás.
empresas
Empresas: as seis rotas unificadas
Base: https://api.balancos.ai/v1. Todo campo monetário vem em reais. Exemplos ilustrativos — os tipos exatos ficam congelados no schema OpenAPI.
GET v1/empresas?q=petrobras
cap. 20 resultadosBusca por razão social, nome fantasia ou CNPJ (inteiro ou raiz).
curl "https://api.balancos.ai/v1/empresas?q=petrobras" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"empresas": [
{
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"cnpj": "33000167000101",
"slug": "petroleo-brasileiro-sa-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
}
],
"total": 1
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "5f0d9b1e-8c2a-4b7f-9e3a-2b6a7c9d1e4f"
}
}GET v1/empresas/{chave}
cap. —Ficha cadastral, setor, contagem de publicações e anos com BP/DRE. {chave} aceita slug ou CNPJ.
curl "https://api.balancos.ai/v1/empresas/petroleo-brasileiro-sa-petrobras" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"empresa": {
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"nome_fantasia": "PETROBRAS",
"cnpj": "33000167000101",
"slug": "petroleo-brasileiro-sa-petrobras",
"setor": "Petróleo e gás",
"porte": "DEMAIS",
"uf": "RJ",
"municipio": "RIO DE JANEIRO",
"cnae_principal": "0600001",
"cnae_descricao": "Extração de petróleo e gás natural",
"natureza_juridica": "Sociedade de Economia Mista",
"situacao_cadastral": "ATIVA",
"capital_social": 205431960490,
"publicacoes_total": 214,
"publicacoes_financeiras": 42,
"ultima_publicacao": "2026-04-11",
"anos_com_balanco": [
2025,
2024,
2023
],
"anos_com_dre": [
2025,
2024,
2023
],
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
}
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "1a2b3c4d-5e6f-4a1b-9c3d-8e2f1a2b3c4d"
}
}GET v1/empresas/{chave}/balancos?ano=
cap. todos os anosBalanços patrimoniais em reais, um item por exercício. ano= é opcional e filtra um único exercício.
curl "https://api.balancos.ai/v1/empresas/petroleo-brasileiro-sa-petrobras/balancos?ano=2025" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"empresa": {
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"slug": "petroleo-brasileiro-sa-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
},
"balancos": [
{
"exercicio": 2025,
"data_referencia": "2025-12-31",
"fonte": "xbrl",
"consolidado": true,
"contexto": "Consolidado",
"valores_em_reais": {
"ativo_total": 1123456789012,
"ativo_circulante": 234567890123,
"ativo_nao_circulante": 888888888889,
"passivo_circulante": 111111111111,
"passivo_nao_circulante": 222222222222,
"passivo_total": 333333333333,
"patrimonio_liquido": 790123455679,
"passivo_e_pl_total": 1123456789012
},
"escala_publicada": "unidade"
}
]
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "2b3c4d5e-6f7a-4b1c-9d3e-8f2a1b2c3d4e"
}
}GET v1/empresas/{chave}/dres?ano=
cap. todos os anosDemonstrações de resultado por exercício, mesmo formato dos balanços.
curl "https://api.balancos.ai/v1/empresas/petroleo-brasileiro-sa-petrobras/dres?ano=2025" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"empresa": {
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"slug": "petroleo-brasileiro-sa-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
},
"dres": [
{
"exercicio": 2025,
"data_referencia": "2025-12-31",
"data_inicio": "2025-01-01",
"fonte": "xbrl",
"periodo_tipo": "anual",
"consolidado": true,
"contexto": "Consolidado",
"valores_em_reais": {
"receita_bruta": 512345678901,
"receita_liquida": 498765432109,
"custo": 210987654321,
"lucro_bruto": 287777777788,
"lucro_operacional": 150000000000,
"lucro_liquido": 98765432109
},
"escala_publicada": "unidade"
}
]
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "3c4d5e6f-7a8b-4c1d-9e3f-8a2b1c2d3e4f"
}
}GET v1/empresas/{chave}/documentos
cap. 100 documentosÍndice de publicações legais, mais recentes primeiro.
curl "https://api.balancos.ai/v1/empresas/petroleo-brasileiro-sa-petrobras/documentos" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"empresa": {
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"slug": "petroleo-brasileiro-sa-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
},
"documentos": [
{
"id": "9f0ec3d2-4a1b-4c3d-8e2f-1a2b3c4d5e6f",
"titulo": "Demonstrações Financeiras Padronizadas — DFP 2025",
"tipo": "dfp",
"publicado_em": "2026-03-28",
"ano_referencia": 2025,
"paginas": 84,
"link": "https://balancos.ai/documentos/9f0ec3d2-4a1b-4c3d-8e2f-1a2b3c4d5e6f?utm_source=api"
}
],
"total": 214
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "4d5e6f7a-8b9c-4d1e-9f3a-8b2c1d2e3f4a"
}
}GET v1/ranking?metrica=&uf=&setor=&limite=&inicio=
cap. 100 por páginametrica ∈ ativo, receita, lucro, crescimento. Para ativo/receita/lucro, o valor vem em valor_em_reais (o campo metrica diz o que ele significa); 'crescimento' tem forma própria (crescimento_ativo_total_pct, ativo_base, ativo_atual, de_ano, para_ano) e é sempre crescimento do ativo total. Pagina por posição: inicio é a posição do primeiro item (padrão 1); a resposta traz total e, havendo mais, proximo_inicio (desde a release 1.3.0).
curl "https://api.balancos.ai/v1/ranking?metrica=ativo&uf=SP&limite=5" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"metrica": "ativo",
"nota": "Valores do último exercício unificado de cada empresa — exercícios podem diferir entre empresas (veja o campo 'exercicio').",
"inicio": 1,
"total": 1842,
"proximo_inicio": 6,
"empresas": [
{
"posicao": 1,
"razao_social": "EMPRESA EXEMPLO LTDA",
"slug": "empresa-exemplo-ltda",
"uf": "SP",
"setor": "Serviços financeiros",
"valor_em_reais": 45678901234,
"exercicio": 2025,
"link": "https://balancos.ai/empresas/empresa-exemplo-ltda?utm_source=api"
}
]
},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "5e6f7a8b-9c0d-4e1f-9a3b-8c2d1e2f3a4b"
}
}companhias abertas
CVM: dez rotas sobre a DFP
Tudo que a CVM publica na DFP (Demonstrações Financeiras Padronizadas) de cada companhia aberta, desde 2010: o índice de entregas com as reapresentações, o balanço e a DRE macro, as oito demonstraçõesconta a conta (BPA, BPP, DRE, DRA, DFC, DMPL e DVA), o relatório do auditor com o texto integral e a composição do capital social. Lido direto do acervo da CVM, sem passar pela unificação entre fontes das rotas de empresas — por isso a chave aqui é a da CVM: {chave} aceita o CNPJ ou ocódigo CVM, e cada entrega é identificada peloid_doc (o número sequencial do documento na CVM).
Regras que valem em todas as rotas: valores em reais (a escala declarada na entrega, em geral R$ mil, já vem aplicada; escala_publicada diz qual era);última versão vence quando há reapresentação (as versões seguem visíveis em /dfps); visao é consolidado ouindividual; familia é a família do plano de contas (comercial, financeira, seguradora oudesconhecida) — num banco, “ativo circulante” não existe e vem nulo. Quando a companhia também existe nas rotas de empresas, empresa traz o slug e o link da página no balancos.ai.
GET v1/cvm/companhias?q=&limite=&cursor=
cap. 100 por páginaCatálogo das companhias abertas com DFP. q filtra por trecho da denominação ou prefixo de CNPJ; proximo_cursor vem nulo na última página.
curl "https://api.balancos.ai/v1/cvm/companhias?q=itausa&limite=50" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhias": [
{
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
}
}
],
"proximo_cursor": null
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}
cap. —Ficha derivada das entregas: denominações, família contábil, exercícios, reapresentações, último parecer e capital social. {chave} = CNPJ ou código CVM.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
},
"denominacoes_anteriores": [
"ITAUSA INVESTIMENTOS ITAU S.A."
],
"familia": "comercial",
"primeiro_exercicio": 2010,
"ultimo_exercicio": 2025,
"n_entregas": 18,
"n_reapresentacoes": 2,
"ultimo_parecer": {
"exercicio": 2025,
"tipo": "Sem Ressalva"
},
"capital_social": {
"exercicio": 2025,
"versao": 1,
"integralizado": {
"ordinarias": 3661534232,
"preferenciais": 6779466836,
"total": 10441001068
},
"tesouraria": {
"ordinarias": 0,
"preferenciais": 1234567,
"total": 1234567
}
}
}
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/dfps?ano=
cap. —Linha do tempo das entregas de DFP: por exercício, cada versão com data de recebimento, tipo do parecer, link na CVM e link do documento no balancos.ai.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/dfps?ano=2024" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
}
},
"exercicios": [
{
"exercicio": 2024,
"data_referencia": "2024-12-31",
"versoes": [
{
"id_doc": "140001",
"versao": 1,
"reapresentacao": false,
"recebida_em": "2025-03-20",
"parecer": "Sem Ressalva",
"link_cvm": "https://www.rad.cvm.gov.br/ENET/frmDownloadDocumento.aspx?NumeroSequencialDocumento=140001",
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api"
},
{
"id_doc": "141000",
"versao": 2,
"reapresentacao": true,
"recebida_em": "2025-06-10",
"parecer": "Sem Ressalva",
"link_cvm": "https://www.rad.cvm.gov.br/ENET/frmDownloadDocumento.aspx?NumeroSequencialDocumento=141000",
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api"
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/balancos?ano=&visao=
cap. —Balanço patrimonial macro em reais, última versão de cada exercício, nas visões consolidado e individual (as duas por padrão). /dres tem o mesmo formato com a DRE.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/balancos?visao=consolidado" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
}
},
"balancos": [
{
"exercicio": 2025,
"data_referencia": "2025-12-31",
"visao": "consolidado",
"versao": 1,
"id_doc": "155399",
"familia": "comercial",
"escala_publicada": "mil",
"eq_ativo_passivo": true,
"valores_em_reais": {
"ativo_total": 121000000000,
"ativo_circulante": 9800000000,
"ativo_nao_circulante": 111200000000,
"passivo_circulante": 3100000000,
"passivo_nao_circulante": 15400000000,
"passivo_total": 18500000000,
"patrimonio_liquido": 102500000000,
"passivo_e_pl_total": 121000000000
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/dres?ano=&visao=
cap. —Demonstração de resultado macro em reais: receita líquida, custo, lucro bruto, operacional e líquido, com o tipo do período.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/dres?ano=2025&visao=consolidado" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
}
},
"dres": [
{
"exercicio": 2025,
"data_referencia": "2025-12-31",
"data_inicio": "2025-01-01",
"periodo_tipo": "anual",
"visao": "consolidado",
"versao": 1,
"id_doc": "155399",
"familia": "comercial",
"escala_publicada": "mil",
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 8100000000,
"custo": 5200000000,
"lucro_bruto": 2900000000,
"lucro_operacional": 16200000000,
"lucro_liquido": 15900000000
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/dfps/{id_doc}
cap. —Uma entrega de DFP pelo ID_DOC da CVM: cabeçalho, visões e demonstrações disponíveis, parecer, capital social e as versões irmãs do mesmo exercício.
curl "https://api.balancos.ai/v1/cvm/dfps/155399" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"entrega": {
"id_doc": "155399",
"exercicio": 2025,
"data_referencia": "2025-12-31",
"versao": 1,
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api",
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAUSA S.A.",
"empresa": {
"razao_social": "Itaúsa S.A.",
"slug": "itausa-sa",
"link": "https://balancos.ai/empresas/itausa-sa?utm_source=api"
}
},
"reapresentacao": false,
"recebida_em": "2026-03-20",
"link_cvm": "https://www.rad.cvm.gov.br/ENET/frmDownloadDocumento.aspx?NumeroSequencialDocumento=155399",
"escala_publicada": "mil",
"moeda": "REAL",
"visoes": [
"consolidado",
"individual"
],
"demonstracoes_disponiveis": {
"consolidado": [
"bpa",
"bpp",
"dre",
"dra",
"dfc",
"dmpl",
"dva"
],
"individual": [
"bpa",
"bpp",
"dre",
"dra",
"dfc",
"dmpl",
"dva"
]
},
"parecer": "Sem Ressalva",
"capital_social": {
"exercicio": 2025,
"versao": 1,
"integralizado": {
"ordinarias": 3661534232,
"preferenciais": 6779466836,
"total": 10441001068
},
"tesouraria": {
"ordinarias": 0,
"preferenciais": 1234567,
"total": 1234567
}
},
"versoes": [
{
"id_doc": "155399",
"versao": 1,
"reapresentacao": false,
"recebida_em": "2026-03-20",
"parecer": "Sem Ressalva",
"link_cvm": "https://www.rad.cvm.gov.br/ENET/frmDownloadDocumento.aspx?NumeroSequencialDocumento=155399",
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api"
}
]
}
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/dfps/{id_doc}/demonstracoes/{demonstracao}?visao=
cap. —Conta a conta de uma demonstração da entrega, em reais (a escala da fonte já aplicada), com o exercício anterior lado a lado. {demonstracao} = bpa, bpp, dre, dra, dfc, dmpl ou dva; sem ela, /demonstracoes devolve todas. visao padrão: consolidado (ou individual quando a entrega não tem).
curl "https://api.balancos.ai/v1/cvm/dfps/155399/demonstracoes/dre" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"entrega": {
"id_doc": "155399",
"exercicio": 2025,
"data_referencia": "2025-12-31",
"versao": 1,
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api"
},
"visao": "consolidado",
"visao_solicitada": null,
"demonstracoes": [
{
"demonstracao": "dre",
"nome": "Demonstração do Resultado",
"metodo": null,
"escala_publicada": "mil",
"moeda": "REAL",
"exercicio_atual": {
"inicio": "2025-01-01",
"fim": "2025-12-31"
},
"exercicio_anterior": {
"inicio": "2024-01-01",
"fim": "2024-12-31"
},
"contas": [
{
"codigo": "3.01",
"descricao": "Receita de Venda de Bens e/ou Serviços",
"nivel": 2,
"padronizada": true,
"coluna": null,
"valor_atual": 8100000000,
"valor_anterior": 7600000000
},
{
"codigo": "3.11",
"descricao": "Lucro/Prejuízo Consolidado do Período",
"nivel": 2,
"padronizada": true,
"coluna": null,
"valor_atual": 15900000000,
"valor_anterior": 14100000000
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/dfps/{id_doc}/parecer
cap. —Relatório do auditor independente (tipo e texto integral) e as declarações dos diretores da mesma entrega.
curl "https://api.balancos.ai/v1/cvm/dfps/155399/parecer" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"entrega": {
"id_doc": "155399",
"exercicio": 2025,
"data_referencia": "2025-12-31",
"versao": 1,
"link_documento": "https://balancos.ai/documentos/0d2e…?utm_source=api"
},
"auditor": {
"tipo": "Sem Ressalva",
"texto": "Examinamos as demonstrações financeiras individuais e consolidadas da Itaúsa S.A. …"
},
"declaracoes": [
{
"tipo": "Declaração dos Diretores sobre as Demonstrações Financeiras",
"texto": "Os diretores declaram que revisaram, discutiram e concordam …"
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/ranking?metrica=&ano=&visao=&familia=&limite=&inicio=
cap. 100 por páginaMaiores companhias abertas no exercício por ativo, patrimonio, receita ou lucro (última versão de cada uma), com filtro opcional de família contábil. Pagina por posição: inicio é a posição do primeiro item (padrão 1); a resposta traz total e, havendo mais, proximo_inicio (desde a release 1.3.0).
curl "https://api.balancos.ai/v1/cvm/ranking?metrica=receita&ano=2024&limite=10" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"metrica": "receita",
"exercicio": 2024,
"visao": "consolidado",
"familia": null,
"inicio": 1,
"total": 436,
"proximo_inicio": 11,
"companhias": [
{
"posicao": 1,
"cnpj": "33000167000101",
"cd_cvm": "9512",
"denominacao": "PETROLEO BRASILEIRO S.A. PETROBRAS",
"valor_em_reais": 490800000000,
"versao": 1,
"id_doc": "155000",
"empresa": {
"razao_social": "Petróleo Brasileiro S.A. Petrobras",
"slug": "petroleo-brasileiro-sa-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-sa-petrobras?utm_source=api"
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/itrs?ano=
cap. —Entregas de ITR (informações trimestrais) por data de referência e versão, no mesmo formato de /dfps. O campo exercicio é o ano da data de referência. Desde a release 1.2.0.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/itrs?ano=2026" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAÚSA S.A.",
"empresa": {
"razao_social": "ITAUSA S.A.",
"slug": "itausa",
"link": "https://balancos.ai/empresas/itausa?utm_source=api"
}
},
"exercicios": [
{
"exercicio": 2026,
"data_referencia": "2026-06-30",
"versoes": [
{
"id_doc": "160371",
"versao": 1,
"reapresentacao": false,
"recebida_em": "2026-08-10",
"parecer": null,
"link_cvm": "http://www.rad.cvm.gov.br/ENETCONSULTA/frmDownloadDocumento.aspx?CodigoInstituicao=1&NumeroSequencialDocumento=160371",
"link_documento": "https://balancos.ai/documentos/df205f2a-2988-37de-a50d-427180a21b5a?utm_source=api"
},
{
"id_doc": "160385",
"versao": 2,
"reapresentacao": true,
"recebida_em": "2026-08-11",
"parecer": "Sem Ressalva",
"link_cvm": "http://www.rad.cvm.gov.br/ENETCONSULTA/frmDownloadDocumento.aspx?CodigoInstituicao=1&NumeroSequencialDocumento=160385",
"link_documento": "https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api"
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-19T16:08:57",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/itrs/{id_doc}/demonstracoes/{demonstracao}?visao=
cap. —Conta a conta de uma entrega de ITR. Na DRE e na DRA, valor_atual e valor_anterior são o resultado acumulado no exercício, e valor_trimestre_atual e valor_trimestre_anterior o trimestre isolado, os dois como publicados; nas demais demonstrações os campos de trimestre vêm nulos. /cvm/itrs/{id_doc} e /cvm/itrs/{id_doc}/parecer têm o formato das rotas /dfps; no ITR o auditor revisa (Relatório da Revisão Especial). O tipo mora no path: ID_DOC de ITR não abre em /dfps.
curl "https://api.balancos.ai/v1/cvm/itrs/160385/demonstracoes/dre" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"entrega": {
"id_doc": "160385",
"exercicio": 2026,
"data_referencia": "2026-06-30",
"versao": 2,
"link_documento": "https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api"
},
"visao": "consolidado",
"visao_solicitada": null,
"demonstracoes": [
{
"demonstracao": "dre",
"nome": "Demonstração do Resultado",
"metodo": null,
"escala_publicada": "mil",
"moeda": "REAL",
"exercicio_atual": {
"inicio": "2026-01-01",
"fim": "2026-06-30"
},
"exercicio_anterior": {
"inicio": "2025-01-01",
"fim": "2025-06-30"
},
"trimestre_atual": {
"inicio": "2026-04-01",
"fim": "2026-06-30"
},
"trimestre_anterior": {
"inicio": "2025-04-01",
"fim": "2025-06-30"
},
"contas": [
{
"codigo": "3.01",
"descricao": "Receita de Venda de Bens e/ou Serviços",
"nivel": 2,
"padronizada": true,
"coluna": null,
"valor_atual": 4250000000,
"valor_anterior": 4024000000,
"valor_trimestre_atual": 2231000000,
"valor_trimestre_anterior": 2121000000
},
{
"codigo": "3.02",
"descricao": "Custo dos Bens e/ou Serviços Vendidos",
"nivel": 2,
"padronizada": true,
"coluna": null,
"valor_atual": -3148000000,
"valor_anterior": -3092000000,
"valor_trimestre_atual": -1683000000,
"valor_trimestre_anterior": -1635000000
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-19T16:08:57",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/trimestres?desde=&ate=&visao=
cap. —Série trimestral, do gold: por data de referência (AAAA-MM-DD, segue o exercício social da companhia), o balanço e os resultados trimestre, acumulado e doze_meses, na última versão de cada entrega. O último trimestre do exercício não é publicado pela companhia: é derivado (DFP menos o acumulado de nove meses, derivado = true). doze_meses = acumulado corrente + DFP anterior − acumulado do mesmo ponto um ano antes; no fechamento é a própria DFP. consistente = false indica que, na fonte, os trimestres isolados daquele exercício não fecham com o acumulado publicado — o dado não é corrigido.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/trimestres?desde=2026-06-30" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAÚSA S.A.",
"empresa": {
"razao_social": "ITAUSA S.A.",
"slug": "itausa",
"link": "https://balancos.ai/empresas/itausa?utm_source=api"
}
},
"visao": "consolidado",
"visao_solicitada": null,
"trimestres": [
{
"data_referencia": "2026-06-30",
"inicio_exercicio": "2026-01-01",
"trimestre_exercicio": 2,
"origem": "itr",
"familia": "comercial",
"link_documento": "https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api",
"balanco_em_reais": {
"ativo_total": 119772000000,
"ativo_circulante": 15055000000,
"ativo_nao_circulante": 104717000000,
"passivo_circulante": 7530000000,
"passivo_nao_circulante": 13660000000,
"passivo_total": 21190000000,
"patrimonio_liquido": 98582000000,
"passivo_e_pl_total": 119772000000
},
"resultado": {
"trimestre": {
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 2231000000,
"custo": -1683000000,
"lucro_bruto": 548000000,
"lucro_operacional": 4975000000,
"lucro_liquido": 5264000000
},
"derivado": false,
"consistente": true,
"ranqueavel": null,
"documentos_origem": [
"https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api"
]
},
"acumulado": {
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 4250000000,
"custo": -3148000000,
"lucro_bruto": 1102000000,
"lucro_operacional": 9832000000,
"lucro_liquido": 9726000000
},
"derivado": false,
"consistente": true,
"ranqueavel": null,
"documentos_origem": [
"https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api"
]
},
"doze_meses": {
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 8475000000,
"custo": -6295000000,
"lucro_bruto": 2180000000,
"lucro_operacional": 19157000000,
"lucro_liquido": 18228000000
},
"derivado": false,
"consistente": true,
"ranqueavel": true,
"documentos_origem": [
"https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api",
"https://balancos.ai/documentos/945117df-e4dd-e815-350a-d3871b4e289d?utm_source=api",
"https://balancos.ai/documentos/fd597410-ff36-16e0-3cc7-5a9aac17694e?utm_source=api"
]
}
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-19T16:08:57",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/companhias/{chave}/resultados?periodo=&desde=&ate=&visao=
cap. —Os resultados da série num só período: trimestre, acumulado, 12m ou anual (sem valor, todos). Mesmas marcas de /trimestres; ranqueavel só existe no 12m.
curl "https://api.balancos.ai/v1/cvm/companhias/61532644000115/resultados?periodo=12m&desde=2026-01-01" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"companhia": {
"cnpj": "61532644000115",
"cd_cvm": "7617",
"denominacao": "ITAÚSA S.A.",
"empresa": {
"razao_social": "ITAUSA S.A.",
"slug": "itausa",
"link": "https://balancos.ai/empresas/itausa?utm_source=api"
}
},
"periodo": "12m",
"visao": "consolidado",
"visao_solicitada": null,
"resultados": [
{
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 8475000000,
"custo": -6295000000,
"lucro_bruto": 2180000000,
"lucro_operacional": 19157000000,
"lucro_liquido": 18228000000
},
"derivado": false,
"consistente": true,
"ranqueavel": true,
"documentos_origem": [
"https://balancos.ai/documentos/6e70a010-8190-f2b8-1023-7a7508818e00?utm_source=api",
"https://balancos.ai/documentos/945117df-e4dd-e815-350a-d3871b4e289d?utm_source=api",
"https://balancos.ai/documentos/fd597410-ff36-16e0-3cc7-5a9aac17694e?utm_source=api"
],
"data_referencia": "2026-06-30",
"inicio_exercicio": "2026-01-01",
"trimestre_exercicio": 2,
"periodo": "12m",
"visao": "consolidado",
"familia": "comercial"
},
{
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 8365000000,
"custo": -6247000000,
"lucro_bruto": 2118000000,
"lucro_operacional": 18568000000,
"lucro_liquido": 17057000000
},
"derivado": false,
"consistente": true,
"ranqueavel": true,
"documentos_origem": [
"https://balancos.ai/documentos/15b73655-c853-c044-7c44-9cc2b1ae9568?utm_source=api",
"https://balancos.ai/documentos/945117df-e4dd-e815-350a-d3871b4e289d?utm_source=api",
"https://balancos.ai/documentos/9e3fa67a-0949-df64-58e6-3cebeaf7e3ba?utm_source=api"
],
"data_referencia": "2026-03-31",
"inicio_exercicio": "2026-01-01",
"trimestre_exercicio": 1,
"periodo": "12m",
"visao": "consolidado",
"familia": "comercial"
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-19T16:08:57",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/cvm/ranking-12m?metrica=&data_referencia=&visao=&familia=&limite=&inicio=
cap. 100 por páginaMaiores companhias abertas por receita ou lucro dos doze meses encerrados na data de referência. Sem data_referencia, usa a mais recente com cobertura (ao menos 80% das companhias). Só entra 12M ranqueável: escala suspeita na fonte e receita negativa ficam fora. Pagina por posição: inicio é a posição do primeiro item (padrão 1); a resposta traz total e, havendo mais, proximo_inicio (desde a release 1.3.0).
curl "https://api.balancos.ai/v1/cvm/ranking-12m?metrica=lucro&limite=10" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"metrica": "lucro",
"data_referencia": "2026-06-30",
"visao": "consolidado",
"familia": null,
"inicio": 1,
"total": 412,
"proximo_inicio": 11,
"companhias": [
{
"posicao": 1,
"cnpj": "33000167000101",
"denominacao": "PETROLEO BRASILEIRO S A PETROBRAS",
"familia": "comercial",
"valor_em_reais": 133756000000,
"consistente": true,
"empresa": {
"razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
"slug": "petroleo-brasileiro-s-a-petrobras",
"link": "https://balancos.ai/empresas/petroleo-brasileiro-s-a-petrobras?utm_source=api"
}
},
{
"posicao": 2,
"cnpj": "60872504000123",
"denominacao": "ITAU UNIBANCO HOLDING S.A.",
"familia": "financeira",
"valor_em_reais": 47943000000,
"consistente": true,
"empresa": {
"razao_social": "ITAU UNIBANCO HOLDING S.A.",
"slug": "itau-unibanco-holding",
"link": "https://balancos.ai/empresas/itau-unibanco-holding?utm_source=api"
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-19T16:08:57",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}instituições financeiras
BCB: nove rotas sobre o IF.data
O IF.data é o portal do Banco Central com os dados trimestrais de toda instituição supervisionada — bancos, cooperativas, financeiras, corretoras, instituições de pagamento — desde 2000, em três níveis de consolidação:individual, financeiro (conglomerado financeiro) eprudencial (conglomerado prudencial). A API serve a série macro por trimestre, a DRE derivada, os 22 relatórios do portal conta a conta (demonstrações, capital, carteira de crédito por modalidade, PF/PJ, CNAE, porte, região, segmentação), os conglomerados com seus membros e o ranking por data-base.
Chaves e convenções: {chave} aceita o CodInst (o código da instituição no portal), o CNPJ ou a raiz do CNPJ;nivel sem valor usa o nível padrão da instituição na última data-base;data_base é AAAAMM com mês 03, 06, 09 ou 12; valores em reais como a fonte publica; índices (Basileia, imobilização, alavancagem) vêm como fração (0,152 = 15,2 %). O plano de contas mudou em 2025 (era = cosif_2000 até 2024-12,cosif_2025 depois): o comparativo com o ano anterior só é preenchido dentro da mesma era, e comparavel diz quando isso acontece.
GET v1/bcb/instituicoes?q=&uf=&tipo=&consolidado_bancario=&limite=&cursor=
cap. 100 por páginaCatálogo das instituições individuais do IF.data. q filtra por trecho do nome ou prefixo de CNPJ/raiz; tipo é o código TI e consolidado_bancario o código TCB (b1, b2, b3S, b3C, b4, n1, n2, n4).
curl "https://api.balancos.ai/v1/bcb/instituicoes?q=bradesco&uf=SP" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"instituicoes": [
{
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"cnpj_raiz": "60746948",
"tipo": {
"codigo": "8",
"nome": "Banco múltiplo"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"segmento_prudencial": "S1",
"sede": {
"uf": "SP",
"municipio": "OSASCO"
},
"conglomerados": {
"financeiro": "10045",
"prudencial": "1000080075"
},
"primeira_data_base": "200003",
"ultima_data_base": "202606",
"n_data_bases": 106,
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
}
}
],
"proximo_cursor": null
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/instituicoes/{chave}
cap. —Ficha da instituição: cadastro do IF.data, identidade na Receita, os níveis de consolidação que ela tem (individual, financeiro, prudencial), o nível padrão e o resumo da última data-base. {chave} = CodInst, CNPJ ou raiz do CNPJ.
curl "https://api.balancos.ai/v1/bcb/instituicoes/60746948000112" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"instituicao": {
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"cnpj_raiz": "60746948",
"tipo": {
"codigo": "8",
"nome": "Banco múltiplo"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"segmento_prudencial": "S1",
"sede": {
"uf": "SP",
"municipio": "OSASCO"
},
"conglomerados": {
"financeiro": "10045",
"prudencial": "1000080075"
},
"primeira_data_base": "200003",
"ultima_data_base": "202606",
"n_data_bases": 106,
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
},
"receita": {
"razao_social": "BANCO BRADESCO S.A.",
"situacao": "Ativa",
"cnae": "6422100"
},
"niveis": [
{
"nivel": "individual",
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"padrao": false
},
{
"nivel": "financeiro",
"codinst": "10045",
"nome": "BRADESCO",
"padrao": false
},
{
"nivel": "prudencial",
"codinst": "1000080075",
"nome": "BRADESCO",
"padrao": true
}
],
"nivel_padrao": "prudencial",
"ultima_data_base_resumo": {
"data_base": "202606",
"data_referencia": "2026-06-30",
"nivel": "prudencial",
"ativo_total": 2300000000000,
"carteira_credito": 990000000000,
"captacoes": 1400000000000,
"patrimonio_liquido": 175000000000,
"indice_basileia": 0.152
},
"link_ifdata": "https://www3.bcb.gov.br/ifdata/"
}
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/instituicoes/{chave}/trimestres?nivel=&desde=&ate=
cap. —Série trimestral macro desde 2000 no nível escolhido (padrão: o nível padrão da instituição): ativo, carteira, TVM, captações, PL, lucro acumulado no semestre, PR, RWA, índices e rede. Linhas de dezembro trazem o link do documento IF.data do ano.
curl "https://api.balancos.ai/v1/bcb/instituicoes/60746948/trimestres?nivel=prudencial&desde=202603" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"instituicao": {
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"cnpj_raiz": "60746948",
"tipo": {
"codigo": "8",
"nome": "Banco múltiplo"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"segmento_prudencial": "S1",
"sede": {
"uf": "SP",
"municipio": "OSASCO"
},
"conglomerados": {
"financeiro": "10045",
"prudencial": "1000080075"
},
"primeira_data_base": "200003",
"ultima_data_base": "202606",
"n_data_bases": 106,
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
}
},
"nivel": {
"nivel": "prudencial",
"codinst": "1000080075",
"nome": "BRADESCO",
"padrao": true
},
"trimestres": [
{
"data_base": "202606",
"data_referencia": "2026-06-30",
"ano": 2026,
"trimestre": 2,
"era": "cosif_2025",
"nivel_padrao": true,
"valores_em_reais": {
"ativo_total": 2300000000000,
"carteira_credito": 990000000000,
"tvm": 610000000000,
"captacoes": 1400000000000,
"patrimonio_liquido": 175000000000,
"lucro_liquido_acumulado_semestre": 11200000000,
"patrimonio_referencia": 190000000000,
"rwa": 1250000000000
},
"indices": {
"basileia": 0.152,
"imobilizacao": 0.31,
"alavancagem": 0.083
},
"rede": {
"agencias": 2480,
"postos": 3200
},
"link_documento": null
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/instituicoes/{chave}/resultados?nivel=&periodo=
cap. —DRE derivada pelo gold: trimestre isolado (T1 = mar, T2 = jun − mar, T3 = set, T4 = dez − set) e anual (jun + dez), com a flag completo. periodo = trimestre ou anual; sem ele, os dois.
curl "https://api.balancos.ai/v1/bcb/instituicoes/60746948/resultados?nivel=prudencial&periodo=anual" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"instituicao": {
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"cnpj_raiz": "60746948",
"tipo": {
"codigo": "8",
"nome": "Banco múltiplo"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"segmento_prudencial": "S1",
"sede": {
"uf": "SP",
"municipio": "OSASCO"
},
"conglomerados": {
"financeiro": "10045",
"prudencial": "1000080075"
},
"primeira_data_base": "200003",
"ultima_data_base": "202606",
"n_data_bases": 106,
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
}
},
"nivel": {
"nivel": "prudencial",
"codinst": "1000080075",
"nome": "BRADESCO",
"padrao": true
},
"resultados": [
{
"periodo": "anual",
"ano": 2025,
"trimestre": null,
"data_inicio": "2025-01-01",
"data_referencia": "2025-12-31",
"era": "cosif_2025",
"completo": true,
"valores_em_reais": {
"receita_bruta": null,
"receita_liquida": 186000000000,
"custo": 112000000000,
"lucro_bruto": 74000000000,
"lucro_operacional": 29000000000,
"lucro_liquido": 21500000000
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/instituicoes/{chave}/relatorios?nivel=&data_base=&relatorio=
cap. —Os relatórios do portal IF.data conta a conta numa data-base (padrão: a última do nível) — demonstrações, capital, carteira de crédito e segmentação — como árvore, com o valor da mesma data-base do ano anterior quando a era do plano de contas é a mesma. relatorio filtra um id.
curl "https://api.balancos.ai/v1/bcb/instituicoes/60746948/relatorios?nivel=prudencial&data_base=202606" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"instituicao": {
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"cnpj_raiz": "60746948",
"tipo": {
"codigo": "8",
"nome": "Banco múltiplo"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"segmento_prudencial": "S1",
"sede": {
"uf": "SP",
"municipio": "OSASCO"
},
"conglomerados": {
"financeiro": "10045",
"prudencial": "1000080075"
},
"primeira_data_base": "200003",
"ultima_data_base": "202606",
"n_data_bases": 106,
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
}
},
"nivel": {
"nivel": "prudencial",
"codinst": "1000080075",
"nome": "BRADESCO",
"padrao": true
},
"data_base": "202606",
"data_referencia": "2026-06-30",
"era": "cosif_2025",
"data_base_anterior": "202506",
"comparavel": true,
"relatorios": [
{
"id": 1,
"nome": "Resumo",
"grupo": "demonstracoes",
"cabecalho": "Valores em R$ mil",
"linhas": [
{
"id": 11,
"lid": -1,
"nome": "Ativo",
"descricao": null,
"profundidade": 0,
"grupo": true,
"formato": "mil",
"valor": null,
"valor_ano_anterior": null
},
{
"id": 12,
"lid": 140220,
"nome": "Ativo Total",
"descricao": null,
"profundidade": 1,
"grupo": false,
"formato": "mil",
"valor": 2300000000000,
"valor_ano_anterior": 2200000000000
},
{
"id": 14,
"lid": 79664,
"nome": "Índice de Basileia",
"descricao": null,
"profundidade": 0,
"grupo": false,
"formato": "pct",
"valor": 0.152,
"valor_ano_anterior": 0.148
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/conglomerados/{codinst}?nivel=
cap. —Um conglomerado prudencial (padrão) ou financeiro pelo CodInst, com os membros individuais em ordem de ativo total.
curl "https://api.balancos.ai/v1/bcb/conglomerados/1000080075" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"conglomerado": {
"nivel": "prudencial",
"codinst": "1000080075",
"nome": "BRADESCO",
"primeira_data_base": "201403",
"ultima_data_base": "202606",
"n_data_bases": 50,
"n_membros": 5
},
"membros": [
{
"codinst": "60746948",
"nome": "BCO BRADESCO S.A.",
"cnpj": "60746948000112",
"ativo_total": 2050000000000,
"data_base": "202606",
"empresa": {
"razao_social": "Banco Bradesco S.A.",
"slug": "banco-bradesco-sa",
"link": "https://balancos.ai/empresas/banco-bradesco-sa?utm_source=api"
}
},
{
"codinst": "6271464",
"nome": "BRADESCO BBI S.A.",
"cnpj": "06271464000119",
"ativo_total": 52000000000,
"data_base": "202606",
"empresa": null
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/data-bases
cap. —As data-bases trimestrais disponíveis desde 2000, com a era do plano de contas (cosif_2000 até 2024-12, cosif_2025 a partir de 2025-03) e quantas instituições cada uma tem.
curl "https://api.balancos.ai/v1/bcb/data-bases" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"data_bases": [
{
"data_base": "202606",
"data_referencia": "2026-06-30",
"ano": 2026,
"trimestre": 2,
"era": "cosif_2025",
"n_instituicoes": 1601,
"derivada_em": "2026-09-10T14:31:07"
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/data-bases/{data_base}/relatorios
cap. —Dicionário e árvore dos relatórios do portal numa data-base, sem valores: id e nome de cada relatório, os níveis que ele cobre e as colunas (id, lid, pai, profundidade). Use-o pra saber o que /relatorios devolve e os ids do filtro relatorio.
curl "https://api.balancos.ai/v1/bcb/data-bases/202606/relatorios" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"data_base": "202606",
"era": "cosif_2025",
"relatorios": [
{
"id": 1,
"nome": "Resumo",
"grupo": "demonstracoes",
"niveis": [
"individual",
"financeiro",
"prudencial"
],
"cabecalho": "Valores em R$ mil",
"notas": null,
"colunas": [
{
"id": 11,
"lid": -1,
"nome": "Ativo",
"descricao": null,
"pai_id": null,
"profundidade": 0,
"grupo": true,
"formato": "mil"
},
{
"id": 12,
"lid": 140220,
"nome": "Ativo Total",
"descricao": null,
"pai_id": 11,
"profundidade": 1,
"grupo": false,
"formato": "mil"
}
]
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}GET v1/bcb/ranking?data_base=&nivel=&metrica=&uf=&tipo=&consolidado_bancario=&limite=&inicio=
cap. 100 por páginaMaiores instituições numa data-base (padrão: a última) por ativo, carteira, captacoes, patrimonio, lucro (acumulado no semestre) ou basileia. nivel=padrao (uma linha por grupo, no nível padrão de cada um), individual, financeiro ou prudencial. unidade diz se valor é em reais ou fração. Pagina por posição: inicio é a posição do primeiro item (padrão 1); a resposta traz total e, havendo mais, proximo_inicio (desde a release 1.3.0).
curl "https://api.balancos.ai/v1/bcb/ranking?metrica=ativo&limite=10" \
-H "Authorization: Bearer bal_live_SEU_TOKEN"Ver exemplo de resposta
{
"dados": {
"data_base": "202606",
"data_referencia": "2026-06-30",
"nivel": "padrao",
"metrica": "ativo",
"unidade": "reais",
"inicio": 1,
"total": 1320,
"proximo_inicio": 11,
"instituicoes": [
{
"posicao": 1,
"nivel": "prudencial",
"codinst": "1000000000",
"nome": "BB",
"cnpj": "00000000000191",
"tipo": {
"codigo": "1",
"nome": "Banco do Brasil (banco múltiplo)"
},
"consolidado_bancario": {
"codigo": "b1",
"nome": "Banco comercial ou múltiplo com carteira comercial"
},
"uf": "DF",
"valor": 2500000000000,
"empresa": {
"razao_social": "Banco do Brasil S.A.",
"slug": "banco-do-brasil-sa",
"link": "https://balancos.ai/empresas/banco-do-brasil-sa?utm_source=api"
}
}
]
},
"meta": {
"versao": "v1",
"release": "1.2.0",
"dados_atualizados_em": "2026-09-14T13:40:00",
"requisicao_id": "7c1a2b3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}formatos
Envelope, chaves, cursor, escala e links
Toda resposta de sucesso vem no mesmo envelope:
{
"dados": {},
"meta": {
"versao": "v1",
"release": "1.0.0",
"dados_atualizados_em": "2026-09-06T03:12:00Z",
"requisicao_id": "uuid"
}
}E todo erro, neste outro (ver a tabela completa em Erros):
{
"erro": {
"codigo": "empresa_nao_encontrada",
"mensagem": "…"
},
"requisicao_id": "uuid"
}Chave de empresa ({chave}): aceita o slug retornado pela busca ou um CNPJ de 14 dígitos, com ou sem pontuação. Se o slug for antigo, a API segue o redirecionamento e responde 200 já com o slug canônico no payload — sem quebrar seu código.
Chaves das fontes: nas rotas da CVM, {chave} é o CNPJ (com ou sem pontuação) ou o código CVM, e {id_doc} é o número da entrega; nas do BCB, {chave} é o CodInst, o CNPJ ou a raiz do CNPJ, e {codinst} o código do conglomerado. Nenhuma delas depende de a empresa existir nas rotas de empresas — quando existe, o objeto empresa traz o slug e o link.
Cursor: os dois catálogos (/cvm/companhias e /bcb/instituicoes) paginam por limite (até 100) e cursor. O cursor é opaco: devolva em cursor exatamente o proximo_cursor da página anterior; nulo significa última página. Não há total.
Rankings: os quatro rankings (/ranking, /cvm/ranking, /cvm/ranking-12m e /bcb/ranking) paginam por posição desde a release 1.3.0: limite (até 100) e inicio, a posição do primeiro item, a partir de 1. Cada item traz posicao; a resposta traz total (o tamanho do ranking com os filtros) e proximo_inicio, nulo na última página. Dá para pular direto: inicio=201 devolve do 201º em diante. As demais rotas devolvem o conjunto inteiro — uma entrega, uma série, uma data-base — sem paginação.
Frescor por origem: meta.dados_atualizados_em é a data da origem daquela rota — a última carga aprovada da base unificada nas rotas de empresas e no macro do BCB, o último processamento do acervo da CVM ou do conta a conta do IF.data nas demais.
Escala e fonte: todo valor monetário já vem em reais. escala_publicada (unidade, milhares ou milhoes) é informativa — a granularidade declarada na publicação original. fonte é llm (extraído de PDF) ou xbrl (arquivo estruturado); em conflito no mesmo exercício, XBRL vence. Nas rotas da CVM, escala_publicada é mil, unidade ou mista e o valor já vem multiplicado; no BCB a fonte publica em reais e os índices são fração.
Links canônicos: todo link aponta pro balancos.ai (/empresas/{slug} ou /documentos/{id}) com utm_source=api, pra você abrir a página de origem sem perder a atribuição.
limites
O que conta na sua cota
Plano único: 60 chamadas por minuto por conta (não por chave — mais chaves não dão mais throughput) e até 5 chaves ativas.
- Conta: qualquer chamada admitida a uma rota de dados, mesmo terminando em
400,404ou503. - Não conta: chave inválida, o piso por IP, e as rotas
/v1/docs,/v1/openapi.json,/v1/health,/v1e/conta/*. - Um
429de cota é um evento próprio — ele não consome nem soma à sua cota.
Toda resposta de dados leva os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (epoch absoluto do fim da janela); um 429 soma Retry-After. Há também um piso por IP, independente da sua chave, pra conter tráfego malformado em massa.
erros
Códigos de erro
| HTTP | Código | Quando |
|---|---|---|
| 400 | parametro_invalido | Parâmetro fora do domínio aceito (ex.: metrica=xyz, ano não numérico). |
| 400 | requisicao_invalida | Parâmetro desconhecido na query. |
| 400 | chave_empresa_invalida | {chave} não é um slug nem um CNPJ válido. |
| 400 | chave_companhia_invalida | Na CVM, {chave} não é um CNPJ nem um código CVM. |
| 400 | chave_instituicao_invalida | No BCB, {chave} vazia ou com caractere que não é letra nem dígito. |
| 401 | chave_invalida | Bearer ausente, malformado, inexistente ou revogado. |
| 404 | empresa_nao_encontrada | Chave válida, mas a empresa não existe no gold. |
| 404 | companhia_nao_encontrada | Chave válida, mas sem DFP na CVM. |
| 404 | entrega_nao_encontrada | id_doc sem entrega de DFP. |
| 404 | demonstracao_nao_encontrada | A entrega existe, mas não tem a demonstração ou a visão pedida. |
| 404 | instituicao_nao_encontrada | Chave válida, mas sem instituição individual no IF.data. |
| 404 | conglomerado_nao_encontrado | CodInst sem conglomerado no nível pedido. |
| 404 | nivel_nao_encontrado | A instituição não tem o nível de consolidação pedido. |
| 404 | data_base_nao_encontrada | Data-base AAAAMM sem dado disponível. |
| 429 | limite_excedido | Cota da conta (60 chamadas/min) estourada. |
| 429 | limite_ip | Piso de chamadas por IP estourado. |
| 503 | indisponivel | Serviço fora do ar temporariamente; nada foi cobrado da sua cota. |
Dezessete códigos de domínio nas rotas de dados — a lista acima; os nove das rotas da CVM e do BCB chegaram na release 1.1.0; o ITR e a série trimestral da CVM, na 1.2.0, não acrescentaram código novo. Mais três códigos de transporte, que não pertencem a nenhuma rota específica e por isso não aparecem no schema OpenAPI, mas vêm no mesmo envelope:
| HTTP | Código | Quando |
|---|---|---|
| 404 | recurso_nao_encontrado | Caminho que não é uma rota desta API. |
| 405 | metodo_nao_permitido | A rota existe, mas não com esse método HTTP. |
| — | erro_http | Qualquer outra falha de transporte — rede de segurança, não acontece hoje. |
versões
Política de versionamento
O contrato de /v1 congela no lançamento: campo novo entra como release minor — a 1.1.0 acrescentou as rotas da CVM e do BCB sem tocar nas seis de empresas —, sem quebrar quem já integra. Remover um campo ou trocar o tipo de um campo existente é sempre um novo /v2 — nunca uma mudança silenciosa dentro do v1.
O schema completo e sempre atualizado está no OpenAPI, navegável pelo Swagger.