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.

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.

recursos

As seis rotas de dados

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 resultados

Busca por razão social ou prefixo de CNPJ.

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 anos

Balanç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 anos

Demonstraçõ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=

cap. 50 empresas

metrica ∈ 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.

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').",
    "empresas": [
      {
        "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"
  }
}

formatos

Envelope, chave de empresa, 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.

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.

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, 404 ou 503.
Não conta: chave inválida, o piso por IP, e as rotas /v1/docs, /v1/openapi.json, /v1/health, /v1 e /conta/*.
Um 429 de 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.
401	chave_invalida	Bearer ausente, malformado, inexistente ou revogado.
404	empresa_nao_encontrada	Chave válida, mas a empresa não existe no gold.
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.

Dez códigos de domínio, um por operação — a lista acima. 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 (ex.: 1.1.0), 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.