API de Balanço Patrimonial: como consultar dados financeiros de empresas da B3

Quanto caixa a Petrobras tem hoje? A dívida da Vale cresceu no último trimestre? O patrimônio líquido do Itaú está se fortalecendo? Essas perguntas estão no centro de qualquer análise fundamentalista — e a resposta para todas elas está no balanço patrimonial.

O problema é que acessar esses dados de forma estruturada sempre foi trabalhoso. Baixar PDFs, extrair tabelas de relatórios, padronizar campos entre empresas diferentes. Agora existe um caminho mais direto: uma API que entrega o balanço patrimonial completo de qualquer empresa listada na B3, em JSON, pronto para uso.

O que é o balanço patrimonial?

O balanço patrimonial é a demonstração financeira que revela a situação patrimonial de uma empresa em uma data específica. Ele responde a uma pergunta direta: o que a empresa possui, o que ela deve e o que sobra para os acionistas?

A estrutura se divide em três blocos:

A equação fundamental é simples:

Se os ativos de uma empresa somam R$ 500 bilhões e os passivos totalizam R$ 350 bilhões, o patrimônio líquido é de R$ 150 bilhões — esse é o valor contábil que pertence aos acionistas.

Por que consultar balanços patrimoniais via API?

Com uma API de balanço patrimonial, você pode:

• 📊 Automatizar análises fundamentalistas — compare ativos, passivos e patrimônio de dezenas de empresas sem abrir um único PDF;
• 🏗️ Construir dashboards financeiros — alimente painéis com dados atualizados de qualquer empresa da B3;
• 📉 Monitorar endividamento — acompanhe a evolução de dívidas de curto e longo prazo trimestre a trimestre;
• 🔍 Filtrar empresas por critérios contábeis — identifique companhias com caixa elevado, dívida baixa ou patrimônio líquido crescente;
• 🤖 Alimentar modelos e algoritmos — forneça dados estruturados para sistemas de scoring, valuation ou machine learning.

O ponto central é: dados padronizados e estruturados eliminam o retrabalho. Você gasta menos tempo coletando e mais tempo analisando.

Consultando o balanço patrimonial via API

A API HG Finance disponibiliza o balanço patrimonial consolidado de empresas listadas na B3.

Endpoint

Para consultar o balanço da Petrobras, por exemplo:

GET
https://api.hgbrasil.com/v2/finance/balance-sheets?tickers=B3:PETR4&key=suachave

O formato do ticker é {fonte}:{símbolo}. Para consultar múltiplas empresas em uma única requisição, separe por vírgula:

GET
https://api.hgbrasil.com/v2/finance/balance-sheets?tickers=B3:PETR4,B3:VALE3,B3:ITUB4&key=suachave

Parâmetros disponíveis

Com esses parâmetros, você controla exatamente qual recorte temporal deseja consultar — seja o balanço anual completo dos últimos 5 anos ou os dados trimestrais do último exercício.

Exemplo de resposta

{
  "metadata": {
    "key_status": "valid",
    "cached": false,
    "response_time_ms": 1.2,
    "language": "pt-br"
  },
  "results": [],
  "errors": [
    {
      "code": "INVALID_TICKER",
      "message": "Ticker inválido.",
      "help": "https://hgbrasil.com/docs",
      "details": {
        "symbol": "B3:PETR4"
      }
    }
  ]
}

Cada item do array statements representa o balanço em uma data-base específica, contendo os objetos assets, liabilities e equity com dezenas de campos detalhados.

O que cada bloco do balanço revela

Ativos: o que a empresa possui

O objeto assets traz uma visão completa dos bens e direitos, divididos entre circulante (realizável em até 12 meses) e não circulante (longo prazo):

O campo total traz o ativo total da companhia.

Passivos: o que a empresa deve

O objeto liabilities detalha as obrigações, também separadas por prazo:

Patrimônio líquido: o que pertence aos acionistas

O objeto equity mostra o valor residual após deduzir passivos dos ativos:

Análises práticas com dados do balanço

O balanço patrimonial é a base de diversos indicadores usados em análise fundamentalista. Com os dados da API, você calcula todos eles programaticamente.

Liquidez corrente

Mede a capacidade de pagar dívidas de curto prazo:

Valor acima de 1 indica que a empresa tem recursos suficientes para cobrir suas obrigações de curto prazo. Na API, os campos são assets.current_assets e liabilities.current_liabilities.

Grau de endividamento

Mostra quanto da empresa é financiado por terceiros:

Campos: liabilities.total e assets.total.

Composição do endividamento

Revela o perfil da dívida — curto ou longo prazo:

Um percentual alto indica que a empresa concentra suas dívidas no curto prazo, o que pode representar maior pressão sobre o caixa.

Exemplo prático: comparando balanços de empresas

Vamos criar um script que consulta o balanço de múltiplas empresas e calcula indicadores financeiros para comparação.

JavaScript

const API_KEY = 'SUA_CHAVE_AQUI'

async function compararBalancos(tickers) {
  const tickerList = tickers.map((t) => `B3:${t}`).join(',')

  const response = await fetch(
    `https://api.hgbrasil.com/v2/finance/balance-sheets?key=${API_KEY}&tickers=${tickerList}`
  )
  const data = await response.json()

  return data.results.map((empresa) => {
    const balanco = empresa.statements[0]
    const ativos = balanco.assets
    const passivos = balanco.liabilities
    const pl = balanco.equity

    const liquidezCorrente = ativos.current_assets / passivos.current_liabilities
    const endividamento = (passivos.total / ativos.total) * 100

    return {
      empresa: empresa.name,
      ticker: empresa.symbol,
      periodo: `${balanco.fiscal_period} ${balanco.fiscal_year}`,
      ativoTotal: ativos.total,
      passivoTotal: passivos.total,
      patrimonioLiquido: pl.total,
      caixa: ativos.cash_and_equivalents,
      dividaCurtoPrazo: passivos.short_term_debt,
      dividaLongoPrazo: passivos.long_term_debt,
      liquidezCorrente: liquidezCorrente.toFixed(2),
      endividamento: endividamento.toFixed(1) + '%'
    }
  })
}

// Compara Petrobras, Vale e Itaú
compararBalancos(['PETR4', 'VALE3', 'ITUB4']).then((resultado) => {
  console.table(resultado)
})

PHP

<?php
$apiKey = 'SUA_CHAVE_AQUI';
$tickers = ['B3:PETR4', 'B3:VALE3', 'B3:ITUB4'];

$url = "https://api.hgbrasil.com/v2/finance/balance-sheets?key={$apiKey}&tickers=" . implode(',', $tickers);
$response = file_get_contents($url);
$data = json_decode($response, true);

foreach ($data['results'] as $empresa) {
    $balanco = $empresa['statements'][0];
    $ativos = $balanco['assets'];
    $passivos = $balanco['liabilities'];
    $pl = $balanco['equity'];

    $liquidez = $ativos['current_assets'] / $passivos['current_liabilities'];
    $endividamento = ($passivos['total'] / $ativos['total']) * 100;

    echo "{$empresa['name']} ({$empresa['symbol']})\n";
    echo "  Período: {$balanco['fiscal_period']} {$balanco['fiscal_year']}\n";
    echo "  Ativo Total: R$ " . number_format($ativos['total'], 2, ',', '.') . "\n";
    echo "  Passivo Total: R$ " . number_format($passivos['total'], 2, ',', '.') . "\n";
    echo "  Patrimônio Líquido: R$ " . number_format($pl['total'], 2, ',', '.') . "\n";
    echo "  Liquidez Corrente: " . number_format($liquidez, 2, ',', '.') . "\n";
    echo "  Endividamento: " . number_format($endividamento, 1, ',', '.') . "%\n\n";
}

Exemplo: acompanhando a evolução trimestral

Para analisar como a saúde financeira de uma empresa muda ao longo do tempo, consulte os dados trimestrais:

GET
https://api.hgbrasil.com/v2/finance/balance-sheets?tickers=B3:PETR4&period=quarterly&key=suachave

const API_KEY = 'SUA_CHAVE_AQUI'

async function evolucaoTrimestral(ticker) {
  const response = await fetch(
    `https://api.hgbrasil.com/v2/finance/balance-sheets?key=${API_KEY}&tickers=B3:${ticker}&period=quarterly`
  )
  const data = await response.json()
  const empresa = data.results[0]

  return empresa.statements.map((balanco) => ({
    periodo: `${balanco.fiscal_period} ${balanco.fiscal_year}`,
    caixa: balanco.assets.cash_and_equivalents,
    dividaTotal: balanco.liabilities.short_term_debt + balanco.liabilities.long_term_debt,
    patrimonioLiquido: balanco.equity.total,
    liquidez: (balanco.assets.current_assets / balanco.liabilities.current_liabilities).toFixed(2)
  }))
}

evolucaoTrimestral('PETR4').then((trimestres) => {
  console.table(trimestres)
})

Com essa evolução trimestral, você identifica tendências: o caixa está crescendo ou diminuindo? A dívida está sendo reduzida? O patrimônio líquido se fortalece?

Como começar

1. Crie sua chave de API em console.hgbrasil.com — o cadastro é gratuito e não exige cartão de crédito;
2. Faça sua primeira requisição usando o endpoint de balanço patrimonial;
3. Explore os dados — comece pelos campos total de cada bloco e aprofunde conforme sua análise exigir.

O balanço patrimonial é o ponto de partida para entender qualquer empresa. Com a API HG Finance, esses dados deixam de estar presos em PDFs e passam a ser parte do seu código. Consulte a documentação completa para ver todos os campos disponíveis e comece a construir suas próprias ferramentas de análise financeira.