Finanças ·

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

Aprenda a consultar o balanço patrimonial de empresas listadas na B3 via API. Acesse ativos, passivos e patrimônio líquido com dados da CVM em formato JSON, pronto para análise fundamentalista.
HD Hugo Demiglio

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:

BlocoO que representaExemplos
AtivosTudo que a empresa possui — bens e direitosCaixa, estoques, imóveis, patentes
PassivosTudo que a empresa deve — obrigaçõesEmpréstimos, fornecedores, impostos
Patrimônio LíquidoO que sobra após subtrair passivos dos ativosCapital social, reservas de lucro

A equação fundamental é simples:

Ativos=Passivos+Patrimoˆnio Lıˊquido\text{Ativos} = \text{Passivos} + \text{Patrimônio Líquido}

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

ParâmetroTipoDescrição
tickersstringTicker(s) no formato B3:SÍMBOLO. Obrigatório.
periodstringannual (padrão) ou quarterly.
start_datestringData inicial no formato yyyy-mm-dd.
end_datestringData final no formato yyyy-mm-dd.
days_agonumberFiltro por dias atrás (0 = hoje).

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": 122.7,
    "language": "pt-br"
  },
  "results": [
    {
      "ticker": "B3:PETR4",
      "unit": "currency",
      "currency": "BRL",
      "symbol": "PETR4",
      "name": "Petrobrás",
      "full_name": "Petroleo Brasileiro S.A. Petrobras",
      "statements": [
        {
          "period_type": "annual",
          "end_date": "2025-12-31",
          "fiscal_year": 2025,
          "fiscal_period": "FY",
          "assets": {
            "total": 1223389000000,
            "current_assets": 140026000000,
            "cash_and_equivalents": 35608000000,
            "short_term_investments": 15000000000,
            "accounts_receivable": 25461000000,
            "inventory": 45173000000,
            "biological_assets": 0,
            "taxes_recoverable": 11147000000,
            "prepaid_expenses": 0,
            "other_current_assets": 7637000000,
            "non_current_assets": 1083363000000,
            "non_current_receivables": 141830000000,
            "non_current_financial_investments": 0,
            "related_party_receivables": 0,
            "non_current_trade_receivables": 14000000,
            "deferred_tax_assets": 0,
            "other_non_current_assets": 0,
            "equity_method_investments": 3024000000,
            "property_plant_and_equipment": 924624000000,
            "right_of_use_assets": 0,
            "goodwill": 0,
            "intangible_assets": 13885000000
          },
          "liabilities": {
            "current_liabilities": 198368000000,
            "employee_benefits_payable": 15236000000,
            "accounts_payable": 40948000000,
            "taxes_payable": 7110000000,
            "short_term_debt": 67253000000,
            "other_current_liabilities": 45321000000,
            "current_provisions": 21934000000,
            "non_current_liabilities": 607434000000,
            "long_term_debt": 316772000000,
            "other_non_current_liabilities": 3168000000,
            "deferred_tax_liabilities": 34965000000,
            "non_current_provisions": 252529000000
          },
          "equity": {
            "total": 417587000000,
            "share_capital": 205432000000,
            "additional_paid_in_capital": 3106000000,
            "revaluation_surplus": 0,
            "legal_and_statutory_reserves": 158278000000,
            "retained_earnings": 0,
            "accumulated_oci": 48970000000,
            "valuation_adjustments": 0,
            "translation_adjustments": 0,
            "other_accumulated_oci": 48970000000,
            "non_controlling_interest": 1801000000
          }
        },
        {
          "period_type": "annual",
          "end_date": "2024-12-31",
          "fiscal_year": 2024,
          "fiscal_period": "FY",
          "assets": {
            "total": 1124797000000,
            "current_assets": 135212000000,
            "cash_and_equivalents": 20254000000,
            "short_term_investments": 26397000000,
            "accounts_receivable": 22080000000,
            "inventory": 41550000000,
            "biological_assets": 0,
            "taxes_recoverable": 12175000000,
            "prepaid_expenses": 0,
            "other_current_assets": 12756000000,
            "non_current_assets": 989585000000,
            "non_current_receivables": 127626000000,
            "non_current_financial_investments": 0,
            "related_party_receivables": 0,
            "non_current_trade_receivables": 3605000000,
            "deferred_tax_assets": 0,
            "other_non_current_assets": 0,
            "equity_method_investments": 4081000000,
            "property_plant_and_equipment": 843917000000,
            "right_of_use_assets": 0,
            "goodwill": 0,
            "intangible_assets": 13961000000
          },
          "liabilities": {
            "current_liabilities": 194808000000,
            "employee_benefits_payable": 9336000000,
            "accounts_payable": 37659000000,
            "taxes_payable": 8671000000,
            "short_term_debt": 68783000000,
            "other_current_liabilities": 50440000000,
            "current_provisions": 15501000000,
            "non_current_liabilities": 562475000000,
            "long_term_debt": 304684000000,
            "other_non_current_liabilities": 3284000000,
            "deferred_tax_liabilities": 9100000000,
            "non_current_provisions": 245407000000
          },
          "equity": {
            "total": 367514000000,
            "share_capital": 205432000000,
            "additional_paid_in_capital": -2457000000,
            "revaluation_surplus": 0,
            "legal_and_statutory_reserves": 95193000000,
            "retained_earnings": 0,
            "accumulated_oci": 67838000000,
            "valuation_adjustments": 0,
            "translation_adjustments": 0,
            "other_accumulated_oci": 67838000000,
            "non_controlling_interest": 1508000000
          }
        }
      ],
      "source": {
        "symbol": "CVM",
        "name": "CVM",
        "full_name": "Comissão de Valores Mobiliários",
        "url": "https://www.gov.br/cvm/pt-br",
        "location": {
          "timezone": "America/Sao_Paulo"
        }
      }
    }
  ]
}

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):

CampoO que significa
cash_and_equivalentsDinheiro disponível imediatamente — caixa e equivalentes
short_term_investmentsAplicações financeiras de curto prazo
accounts_receivableValores a receber de clientes
inventoryEstoques de matéria-prima e produtos
property_plant_and_equipmentImobilizado — máquinas, imóveis, veículos
intangible_assetsMarcas, patentes, software, licenças
goodwillÁgio por expectativa de rentabilidade futura
equity_method_investmentsParticipações em empresas controladas e coligadas

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:

CampoO que significa
short_term_debtEmpréstimos e financiamentos de curto prazo
long_term_debtEmpréstimos e financiamentos de longo prazo
accounts_payableDívidas com fornecedores
taxes_payableObrigações fiscais
employee_benefits_payableObrigações trabalhistas (salários, férias, encargos)
current_provisionsProvisões de curto prazo (contingências, garantias)
non_current_provisionsProvisões de longo prazo

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

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

CampoO que significa
share_capitalCapital social realizado
legal_and_statutory_reservesReservas de lucros (legal, estatutária, retenção)
retained_earningsLucros ou prejuízos acumulados
accumulated_ociOutros resultados abrangentes acumulados
non_controlling_interestParticipação de acionistas minoritários

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:

Liquidez Corrente=Ativo CirculantePassivo Circulante\text{Liquidez Corrente} = \frac{\text{Ativo Circulante}}{\text{Passivo Circulante}}

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:

Endividamento=Passivo TotalAtivo Total×100\text{Endividamento} = \frac{\text{Passivo Total}}{\text{Ativo Total}} \times 100

Campos: liabilities.total e assets.total.

Composição do endividamento

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

Composic¸a˜o=Passivo CirculantePassivo Total×100\text{Composição} = \frac{\text{Passivo Circulante}}{\text{Passivo Total}} \times 100

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

script.js
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

balanco.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
evolucao.js
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.

API B3: como acessar dados da bolsa de valores do Brasil

Aprenda como integrar dados da B3 em suas aplicações usando uma API REST. Guia prático com exemplos em JavaScript e PHP para consultar cotações de ações, FIIs, câmbio e mais.

API de clima: como colocar previsão do tempo no seu site?

Aprenda a integrar previsão do tempo no seu site usando uma API REST. Guia prático com exemplos em JavaScript e PHP para exibir temperatura, condições climáticas e previsão dos próximos dias.