API de Indicadores Fundamentalistas da B3 com Python

Na API v2 da brapi, indicadores e demonstrações financeiras ficam separados. Isso evita baixar um pacote grande quando você precisa apenas de P/L, P/VP, ROE, margem ou dívida.

Os dois primeiros endpoints para uma análise são:

/api/v2/stocks/statistics?symbols=PETR4&mode=current
/api/v2/stocks/financial-data?symbols=PETR4&mode=current

statistics reúne múltiplos de mercado. financial-data reúne rentabilidade, margens, caixa, dívida, receita e fluxo de caixa.

Onde está cada indicador

Os nomes refletem o contrato JSON. Não troque um campo nulo por zero. Nulo significa que o dado não estava disponível ou não se aplica naquele contexto.

Consultar indicadores com Python

import os
import requests
import pandas as pd

BASE = "https://brapi.dev/api/v2/stocks"
TOKEN = os.getenv("BRAPI_TOKEN")
HEADERS = {"Authorization": f"Bearer {TOKEN}"} if TOKEN else {}

def get(endpoint, symbols):
    response = requests.get(
        f"{BASE}/{endpoint}",
        params={"symbols": ",".join(symbols), "mode": "current"},
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["results"]

symbols = ["PETR4", "VALE3", "ITUB4"]
statistics = get("statistics", symbols)
financial = get("financial-data", symbols)

stats_rows = [
    {"symbol": item["symbol"], **item["data"]}
    for item in statistics
]
financial_rows = [
    {"symbol": item["symbol"], **item["data"]}
    for item in financial
]

df = pd.DataFrame(stats_rows).merge(
    pd.DataFrame(financial_rows),
    on="symbol",
    how="outer",
)

columns = [
    "symbol",
    "trailingPE",
    "priceToBook",
    "enterpriseToEbitda",
    "returnOnEquity",
    "debtToEquity",
    "ebitdaMargins",
    "profitMargins",
]

print(df[columns])

O limite é de 20 símbolos por chamada. Para um universo maior, use a listagem de tickers, divida os símbolos em lotes e respeite o rate limit do plano.

Dados atuais e séries históricas

Use mode=current para o retrato atual ou TTM. Para acompanhar a evolução, use mode=history e escolha period=annual ou period=quarterly.

curl "https://brapi.dev/api/v2/stocks/statistics?symbols=WEGE3&mode=history&period=annual"

Você também pode limitar a série com startDate e endDate:

/api/v2/stocks/financial-data?symbols=WEGE3&mode=history&period=quarterly&startDate=2023-01-01

Uma comparação setorial fica mais útil quando você observa o nível atual e a tendência. Um P/L baixo com margem caindo e dívida subindo conta uma história diferente de um P/L baixo com fundamentos estáveis.

Consultar as demonstrações financeiras

Para conferir o número que está por trás do indicador, use os endpoints de demonstrações:

Essas rotas aceitam period=annual ou period=quarterly. Elas são melhores para auditoria, cálculo próprio e estudos que precisam das contas publicadas, não apenas de um múltiplo pronto.

Como calcular ROIC

ROIC exige uma definição consistente de lucro operacional após impostos e capital investido. A API oferece as contas usadas no cálculo, mas você precisa declarar a fórmula adotada.

Não trate ROIC de um site e ROIC calculado por você como números idênticos sem comparar as definições. Veja o exemplo em como calcular ROIC com a API da brapi.

Evitar um screener enganoso

Antes de ordenar empresas por um indicador:

• compare negócios do mesmo setor;
• preserve valores nulos;
• filtre empresas sem histórico suficiente;
• registre a data de referência;
• confira eventos extraordinários;
• não misture dados anuais, trimestrais e TTM sem sinalizar.

P/L negativo, por exemplo, costuma indicar lucro negativo. Isso não transforma automaticamente a ação em barata. O múltiplo perdeu a interpretação usual.

As páginas de estatísticas e dados financeiros mostram o contrato atual de cada resposta.