Como automatizar a análise fundamentalista de ações brasileiras com Python

O problema do web scraping financeiro

Se você já tentou automatizar análise de ações brasileiras com Python, provavelmente começou assim: abriu o Fundamentus no navegador, inspecionou o HTML, escreveu um scraper com BeautifulSoup ou Selenium. Funcionou por uma semana. Depois o site mudou uma classe CSS e tudo parou.

Esse ciclo é comum porque não existe uma API pública oficial da B3 ou da CVM que entregue indicadores fundamentalistas prontos. As fontes primárias publicam dados brutos em formatos arcaicos — CSVs com encoding Latin-1, arquivos de largura fixa de 245 bytes por linha, contas financeiras que mudam de escala sem aviso.

A bolsai resolve isso: é uma API REST que agrega dados oficiais da B3, CVM e BCB e entrega indicadores fundamentalistas calculados, normalizados e prontos para consumo programático. Sem scraping, sem manutenção.

O que é análise fundamentalista

Análise fundamentalista é o estudo dos indicadores financeiros de uma empresa para avaliar se o preço da ação está justo em relação ao seu valor intrínseco. Os principais indicadores são:

• P/L (Preço/Lucro) — quantos anos de lucro atual seriam necessários para pagar o preço da ação. Quanto menor, mais "barata" a empresa aparenta estar
• P/VP (Preço/Valor Patrimonial) — relação entre o preço de mercado e o patrimônio líquido por ação. Abaixo de 1 pode indicar ação subvalorizada
• ROE (Retorno sobre Patrimônio) — mede a eficiência da empresa em gerar lucro a partir do capital dos acionistas
• EV/EBITDA — compara o valor da empresa (incluindo dívida) com seu lucro operacional antes de juros, impostos, depreciação e amortização
• Margens (bruta, EBIT, EBITDA, líquida) — indicam quanto de cada real de receita vira lucro em diferentes etapas da operação
• Dividend Yield — percentual de dividendos pagos nos últimos 12 meses em relação ao preço atual

Automatizar a consulta desses indicadores permite fazer screening (filtro) de centenas de ações em segundos, comparar empresas de um setor e acompanhar a evolução trimestral — tudo com código.

Configurando o ambiente

Você vai precisar de Python 3.8+ e do httpx como cliente HTTP. Crie uma conta gratuita em usebolsai.com/dashboard e copie sua API key.

pip install httpx

Configure a chave e a URL base que usaremos em todos os exemplos:

import httpx

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

Exemplo 1: Consultar fundamentos de uma ação

O endpoint GET /api/v1/fundamentals/{ticker} retorna 27 indicadores calculados com TTM (Trailing Twelve Months) para qualquer ação da B3. Vamos consultar a Petrobras:

# Buscar fundamentos atuais da Petrobras
r = httpx.get(
    f"{BASE}/fundamentals/PETR4",
    headers=HEADERS
)
data = r.json()

print(f"Empresa:    {data['corporate_name']}")
print(f"P/L:        {data['pl']}")            # 5.32
print(f"P/VP:       {data['pvp']}")           # 1.42
print(f"EV/EBITDA:  {data['ev_ebitda']}")     # 3.27
print(f"ROE:        {data['roe']}%")          # 26.6%
print(f"Net Margin: {data['net_margin']}%")   # 22.23%
print(f"Mkt Cap:    R${data['market_cap']:,.0f}")

A resposta inclui preço atual, market cap, e indicadores de valuation, endividamento, eficiência e rentabilidade. O cálculo usa TTM automaticamente — se a empresa publicou ITR Q3 2025 e DFP 2024, a API combina os dois para gerar o valor dos últimos 12 meses.

Exemplo 2: Comparar múltiplas ações

Um caso de uso comum é comparar os fundamentos de várias empresas lado a lado. Basta iterar sobre uma lista de tickers e montar uma tabela:

tickers = ["PETR4", "VALE3", "ITUB4", "WEGE3", "ABEV3"]

print(f"{'Ticker':<8} {'P/L':>8} {'P/VP':>8} {'ROE':>8} {'EV/EBITDA':>10}")
print("-" * 44)

for ticker in tickers:
    r = httpx.get(
        f"{BASE}/fundamentals/{ticker}",
        headers=HEADERS
    )
    d = r.json()
    print(
        f"{ticker:<8}"
        f"{d['pl'] or 'N/A':>8}"
        f"{d['pvp'] or 'N/A':>8}"
        f"{str(d['roe']) + '%' if d['roe'] else 'N/A':>8}"
        f"{d['ev_ebitda'] or 'N/A':>10}"
    )

# Ticker      P/L     P/VP      ROE  EV/EBITDA
# --------------------------------------------
# PETR4      5.32     1.42   26.6%       3.27
# VALE3     27.31     1.75    6.41%      12.45
# ITUB4      9.99     2.13   21.32%       N/A
# WEGE3     28.46    10.39    39.5%      20.12
# ABEV3     14.13     3.85   18.82%       9.87

Com poucas linhas de código, você tem uma visão comparativa que demoraria minutos para montar manualmente em sites como Fundamentus. E como os dados vêm de uma API, você pode integrar essa lógica em qualquer pipeline, dashboard ou notebook.

Exemplo 3: Screening automático de ações

Screening é o processo de filtrar ações por critérios fundamentalistas. Digamos que você quer encontrar ações com:

• Dividend Yield TTM > 6%
• P/L < 10
• ROE > 15%

Como a bolsai tem endpoint de dividendos separado, combinamos /fundamentals/{ticker} e /dividends/{ticker} para montar o screening completo:

# Lista de tickers para screening (blue chips + mid caps)
candidates = [
    "PETR4", "VALE3", "ITUB4", "BBDC4", "BBAS3",
    "WEGE3", "ABEV3", "RENT3", "SUZB3", "GGBR4",
    "CPLE6", "VIVT3", "CMIG4", "TAEE11", "BBSE3",
]

# Critérios de screening
MIN_DY = 6.0     # Dividend Yield > 6%
MAX_PL = 10.0    # P/L < 10
MIN_ROE = 15.0   # ROE > 15%

approved = []

for ticker in candidates:
    # Buscar fundamentos
    fund = httpx.get(
        f"{BASE}/fundamentals/{ticker}",
        headers=HEADERS
    ).json()

    # Buscar dividend yield
    div = httpx.get(
        f"{BASE}/dividends/{ticker}",
        headers=HEADERS
    ).json()

    pl = fund.get("pl")
    roe = fund.get("roe")
    dy = div.get("dividend_yield_ttm")

    # Aplicar filtros
    if pl and roe and dy:
        if dy > MIN_DY and pl < MAX_PL and roe > MIN_ROE:
            approved.append({
                "ticker": ticker,
                "pl": pl,
                "roe": roe,
                "dy": dy,
            })

print(f"\nAções aprovadas ({len(approved)}):")
print(f"{'Ticker':<8} {'P/L':>8} {'ROE':>8} {'DY':>8}")
print("-" * 34)
for a in approved:
    print(f"{a['ticker']:<8} {a['pl']:>8} {a['roe']:>7}% {a['dy']:>7}%")

# Ações aprovadas (4):
# Ticker      P/L      ROE       DY
# ----------------------------------
# PETR4      5.32   26.6%   14.23%
# BBAS3      4.87   18.9%    9.12%
# CMIG4      6.21   22.1%    8.45%
# TAEE11     8.34   27.3%   10.87%

Esse é o tipo de automação que levaria horas com web scraping e pode ser feita em 30 linhas de Python com a API. Você pode ajustar os critérios, expandir a lista de candidatos ou integrar com alertas por email/Telegram.

Exemplo 4: Histórico trimestral para análise de tendências

Indicadores pontuais podem enganar — uma empresa pode ter um trimestre excepcional que distorce o P/L. O endpoint GET /api/v1/fundamentals/{ticker}/history retorna os fundamentos trimestrais dos últimos 11 anos, cada um com TTM normalizado:

# Evolução do ROE e P/L da Petrobras nos últimos 3 anos
r = httpx.get(
    f"{BASE}/fundamentals/PETR4/history",
    params={"limit": 12},
    headers=HEADERS
)

history = r.json()["history"]

print(f"{'Período':<14} {'P/L':>8} {'ROE':>8} {'Net Margin':>12}")
print("-" * 44)

for item in history:
    print(
        f"{item['reference_date']:<14}"
        f"{item['pl'] or 'N/A':>8}"
        f"{str(item['roe']) + '%' if item['roe'] else 'N/A':>8}"
        f"{str(item['net_margin']) + '%' if item['net_margin'] else 'N/A':>12}"
    )

# Período          P/L      ROE   Net Margin
# --------------------------------------------
# 2025-12-31      5.32   26.6%       22.23%
# 2025-09-30      4.89   28.1%       23.41%
# 2025-06-30      5.01   27.3%       22.87%
# 2025-03-31      5.44   25.8%       21.95%
# ...

Com esses dados trimestrais, você pode construir gráficos de evolução, detectar tendências de deterioração ou melhoria nos fundamentos, e tomar decisões mais informadas do que olhando apenas o número atual.

Por que não fazer web scraping

A tabela abaixo resume as diferenças entre scraping de sites financeiros e usar uma API como a bolsai:

A principal vantagem é a confiabilidade: nomes de campos da API são permanentes e versionados. Seu código não vai quebrar porque alguém redesenhou um site.

Integração com IA

Além do uso direto via Python, a bolsai oferece um servidor MCP (Model Context Protocol) que permite que assistentes de IA como Claude e ChatGPT consultem dados financeiros brasileiros diretamente durante uma conversa.

Isso significa que você pode pedir ao Claude ou ChatGPT: "Compare o P/L e ROE de PETR4, VALE3 e ITUB4" — e ele vai buscar os dados na API automaticamente. Ideal para análises exploratórias ou para construir agentes de investimento que combinam dados quantitativos com raciocínio em linguagem natural.

Veja como configurar na página de integração com IA.

Próximos passos

Agora que você sabe como automatizar a análise fundamentalista, explore mais:

• Como acessar dados fundamentalistas da B3 via API Python — tutorial detalhado de todos os endpoints de fundamentos
• Dividend Yield (DY) via API da B3 — fórmula, JCP vs dividendos e screening por proventos sustentáveis
• bolsai vs brapi: comparação honesta das APIs da B3 — cobertura, preços, precisão e MCP lado a lado
• Como montar uma carteira de dividendos com Python — screening de dividendos, histórico de proventos e análise de sustentabilidade
• Documentação completa — todos os endpoints, parâmetros e exemplos
• Integração com IA — use a API com Claude, ChatGPT, Cursor e outros assistentes

Comece agora

O plano gratuito dá 200 requisições por dia — o suficiente para testar todos os exemplos deste tutorial. O plano Pro (R$29/mês) libera 10.000 requisições, dados históricos completos e todos os endpoints.