Como montar uma carteira de dividendos com Python e a API bolsai
Dividend yield alto não significa boa ação. Neste tutorial, você vai aprender a consultar dividendos, filtrar empresas por critérios fundamentalistas e montar uma carteira de dividendos automatizada usando Python e a API da bolsai.
Por que automatizar a selecao de dividendos?
Investidores focados em renda passiva geralmente fazem o mesmo processo manual: abrem o Fundamentus ou StatusInvest, filtram por dividend yield, olham P/L e P/VP, e copiam os dados para uma planilha. Toda semana, todo mes.
Com Python e uma API de dados financeiros, você pode automatizar isso inteiramente:
- Consultar dividend yield e histórico de proventos de qualquer ação da B3
- Filtrar empresas por critérios como DY minimo, P/L maximo, regularidade de pagamentos
- Acompanhar a evolução da sua carteira com preços atualizados
- Gerar relatorios automaticos e exportar para CSV ou pandas
Neste tutorial, vamos usar a API da bolsai, que agrega dados oficiais da B3, CVM e BCB. Se você está começando, recomendamos também o nosso tutorial sobre dados fundamentalistas.
Setup inicial
Crie uma conta gratuita em usebolsai.com, copie sua API key no dashboard, e instale o httpx:
pip install httpxConfigure as variaveis base que vamos usar em todos os exemplos:
import httpx
API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}1. Consultar dividendos de uma ação
O endpoint GET /api/v1/dividends/{ticker} retorna o histórico completo de proventos,
dividend yield TTM (últimos 12 meses), resumo anual e cada pagamento individual.
Consulte a documentação completa para todos os parametros.
# Histórico de dividendos da Petrobras
r = httpx.get(
f"{BASE}/dividends/PETR4",
params={"years": 5},
headers=HEADERS
)
div = r.json()
print(f"Ticker: {div['ticker']}")
print(f"DY TTM: {div['dividend_yield_ttm']}%")
print(f"Proventos TTM: R${div['ttm_per_share']:.2f}/ação")
print(f"Preco atual: R${div['current_price']:.2f}")
print(f"Total pagtos: {div['total_payments']}")
# Ticker: PETR4
# DY TTM: 14.52%
# Proventos TTM: R$5.28/ação
# Preço atual: R$36.37
# Total pagtos: 42
O campo annual_summary mostra o total pago por ano, e payments lista cada provento com data-ex,
data de pagamento, tipo (dividendo, JCP, etc.) e valor por ação:
# Resumo anual de dividendos
for year in div["annual_summary"]:
print(f" {year['year']}: R${year['total_per_share']:.2f}/ação ({year['payments']} pagtos)")
# 2026: R$2.10/ação (4 pagtos)
# 2025: R$6.44/ação (10 pagtos)
# 2024: R$7.12/ação (8 pagtos)
# 2023: R$5.68/ação (9 pagtos)
# ...
# Últimos 5 pagamentos individuais
for p in div["payments"][:5]:
print(f" {p['ex_date']} {p['type']:12} R${p['value_per_share']:.4f}")
# 2026-03-14 DIVIDENDO R$0.5200
# 2026-02-07 JCP R$0.4800
# 2025-12-13 DIVIDENDO R$0.6100
# ...2. Buscar indicadores fundamentalistas
Dividend yield alto pode ser armadilha: empresas em crise pagam DY alto porque o preço caiu.
Para evitar isso, combine dividendos com indicadores fundamentalistas usando o endpoint
GET /api/v1/fundamentals/{ticker}:
# Fundamentos para avaliar qualidade da pagadora
r = httpx.get(
f"{BASE}/fundamentals/BBAS3",
headers=HEADERS
)
fund = r.json()
print(f"P/L: {fund['pl']}")
print(f"P/VP: {fund['pvp']}")
print(f"ROE: {fund['roe']}%")
print(f"Margem liquida: {fund['net_margin']}%")
print(f"Divida/PL: {fund['debt_equity']}")
# P/L: 5.87
# P/VP: 1.12
# ROE: 19.1%
# Margem liquida: 22.5%
# Divida/PL: None (bancos usam metrica diferente)3. Consultar preço atual
O endpoint GET /api/v1/stocks/{ticker}/quote retorna a cotação mais recente,
incluindo abertura, maxima, minima, fechamento e volume:
# Cotação atual de uma ação
r = httpx.get(
f"{BASE}/stocks/TAEE11/quote",
headers=HEADERS
)
quote = r.json()
print(f"Ticker: {quote['ticker']}")
print(f"Data: {quote['trade_date']}")
print(f"Fechamento: R${quote['close']:.2f}")
print(f"Volume: {quote['volume']:,}")
# Ticker: TAEE11
# Data: 2026-03-28
# Fechamento: R$35.80
# Volume: 4,521,3004. Montar um screener de dividendos
Agora vamos combinar tudo. O script abaixo consulta dividendos e fundamentos de uma lista de ações conhecidas por pagar bons dividendos, e filtra por critérios de qualidade:
import httpx
API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}
# Ações conhecidas por dividendos
candidatas = [
"PETR4", "BBAS3", "TAEE11", "BBSE3", "ITUB4",
"CPLE6", "VIVT3", "CMIG4", "VALE3", "ABEV3",
"TRPL4", "EGIE3", "SBSP3", "KLBN11", "SANB11",
]
# Critérios de filtragem
DY_MIN = 6.0 # Dividend yield minimo de 6%
PL_MAX = 15.0 # P/L maximo de 15
ROE_MIN = 10.0 # ROE minimo de 10%
ANOS_PAGANDO = 3 # Pelo menos 3 anos consecutivos pagando
aprovadas = []
for ticker in candidatas:
# 1. Buscar dividendos
r_div = httpx.get(
f"{BASE}/dividends/{ticker}",
params={"years": 5},
headers=HEADERS
)
div = r_div.json()
dy = div.get("dividend_yield_ttm")
# 2. Verificar consistencia de pagamentos
anos = [a["year"] for a in div.get("annual_summary", [])]
anos_consecutivos = 0
for i, ano in enumerate(sorted(anos, reverse=True)):
if i == 0 or ano == sorted(anos, reverse=True)[i-1] - 1:
anos_consecutivos += 1
else:
break
# 3. Buscar fundamentos
r_fund = httpx.get(
f"{BASE}/fundamentals/{ticker}",
headers=HEADERS
)
fund = r_fund.json()
pl = fund.get("pl")
roe = fund.get("roe")
# 4. Aplicar filtros
if (
dy and dy >= DY_MIN
and pl and 0 < pl <= PL_MAX
and roe and roe >= ROE_MIN
and anos_consecutivos >= ANOS_PAGANDO
):
aprovadas.append({
"ticker": ticker,
"dy": dy,
"pl": pl,
"roe": roe,
"anos": anos_consecutivos,
})
# Resultado: ações que passaram nos filtros
aprovadas.sort(key=lambda x: x["dy"], reverse=True)
print(f"{'Ticker':8} {'DY':>6} {'P/L':>6} {'ROE':>6} {'Anos':>4}")
print("-" * 34)
for a in aprovadas:
print(f"{a['ticker']:8} {a['dy']:>5.1f}% {a['pl']:>6.1f} {a['roe']:>5.1f}% {a['anos']:>4}")
# Ticker DY P/L ROE Anos
# ----------------------------------
# PETR4 14.5% 5.3 26.6% 5
# BBAS3 10.2% 5.9 19.1% 5
# CPLE6 9.8% 7.2 18.4% 4
# BBSE3 8.7% 9.1 22.3% 5
# CMIG4 8.1% 6.8 15.2% 4
# TAEE11 7.3% 10.4 25.1% 55. Analisar consistencia de pagamentos
Uma boa pagadora de dividendos não paga so um ano excepcional - ela paga de forma recorrente e crescente. Vamos visualizar a evolução dos pagamentos:
# Comparar evolução de dividendos de 3 ações
tickers = ["BBAS3", "TAEE11", "PETR4"]
for ticker in tickers:
r = httpx.get(
f"{BASE}/dividends/{ticker}",
params={"years": 5},
headers=HEADERS
)
div = r.json()
print(f"\n{ticker} (DY TTM: {div['dividend_yield_ttm']}%)")
for year in div["annual_summary"]:
bar = "#" * int(year["total_per_share"] * 2)
print(f" {year['year']}: R${year['total_per_share']:>6.2f} {bar}")
# BBAS3 (DY TTM: 10.2%)
# 2026: R$ 1.80 ###
# 2025: R$ 4.52 #########
# 2024: R$ 3.98 #######
# 2023: R$ 3.41 ######
# 2022: R$ 2.87 #####
#
# TAEE11 (DY TTM: 7.3%)
# 2026: R$ 0.95 #
# 2025: R$ 3.21 ######
# 2024: R$ 3.05 ######
# ...6. Calcular yield on cost da carteira
Uma vez que você montou a carteira, pode acompanhar o yield on cost (YOC) - o rendimento baseado no preço que você pagou, não no preço atual. Vamos usar o endpoint de cotações para isso:
# Carteira exemplo com preços de compra
carteira = [
{"ticker": "PETR4", "qtd": 200, "preço_medio": 28.50},
{"ticker": "BBAS3", "qtd": 150, "preço_medio": 24.00},
{"ticker": "TAEE11", "qtd": 100, "preço_medio": 33.20},
]
print(f"{'Ticker':8} {'Qtd':>5} {'PM':>8} {'Atual':>8} {'DY TTM':>7} {'YOC':>7} {'Renda/ano':>10}")
print("-" * 62)
total_investido = 0
total_renda_anual = 0
for pos in carteira:
# Buscar preço atual
r_quote = httpx.get(
f"{BASE}/stocks/{pos['ticker']}/quote",
headers=HEADERS
)
quote = r_quote.json()
# Buscar dividendos TTM
r_div = httpx.get(
f"{BASE}/dividends/{pos['ticker']}",
headers=HEADERS
)
div = r_div.json()
preço_atual = quote["close"]
dy_ttm = div["dividend_yield_ttm"] or 0
div_por_ação = div["ttm_per_share"]
# Yield on cost = dividendo anual / preço medio de compra
yoc = (div_por_ação / pos["preço_medio"]) * 100
renda_anual = div_por_ação * pos["qtd"]
total_investido += pos["preço_medio"] * pos["qtd"]
total_renda_anual += renda_anual
print(f"{pos['ticker']:8} {pos['qtd']:>5} R${pos['preço_medio']:>6.2f} "
f"R${preço_atual:>6.2f} {dy_ttm:>5.1f}% {yoc:>5.1f}% R${renda_anual:>8.2f}")
print("-" * 62)
print(f"Total investido: R${total_investido:,.2f}")
print(f"Renda anual: R${total_renda_anual:,.2f}")
print(f"YOC medio: {(total_renda_anual/total_investido)*100:.1f}%")
# Ticker Qtd PM Atual DY TTM YOC Renda/ano
# --------------------------------------------------------------
# PETR4 200 R$ 28.50 R$ 36.37 14.5% 18.5% R$ 1,056.00
# BBAS3 150 R$ 24.00 R$ 28.45 10.2% 12.1% R$ 435.00
# TAEE11 100 R$ 33.20 R$ 35.80 7.3% 7.9% R$ 261.00
# --------------------------------------------------------------
# Total investido: R$12,720.00
# Renda anual: R$1,752.00
# YOC medio: 13.8%7. Exportar para CSV e pandas
Todos os endpoints da bolsai suportam ?format=csv.
Voce pode baixar os dados diretamente para análise no pandas ou no Excel:
import pandas as pd
from io import StringIO
# Baixar dividendos como CSV direto pro pandas
r = httpx.get(
f"{BASE}/dividends/PETR4",
params={"format": "csv", "years": 10},
headers=HEADERS
)
df = pd.read_csv(StringIO(r.text))
print(df.head())
print(f"\nTotal recebido (10 anos): R${df['value_per_share'].sum():.2f}/ação")
# ex_date payment_date type value_per_share adjusted
# 0 2026-03-14 2026-04-15 DIVIDENDO 0.5200 False
# 1 2026-02-07 2026-03-10 JCP 0.4800 False
# 2 2025-12-13 2026-01-15 DIVIDENDO 0.6100 False
# 3 2025-11-08 2025-12-10 JCP 0.5500 False
# 4 2025-09-15 2025-10-15 DIVIDENDO 0.7200 False
#
# Total recebido (10 anos): R$48.73/açãoCritérios para uma boa carteira de dividendos
Com base nos dados que a API fornece, aqui estao os critérios que investidores experientes costumam usar:
- Dividend yield entre 6% e 15% — DY acima de 15% pode indicar que o preço caiu demais (armadilha de valor)
- P/L abaixo de 15 — empresas com multiplos razoaveis, não sobrevalorizadas
- ROE acima de 10% — indica eficiencia na geração de lucro com o patrimonio
- Pelo menos 3-5 anos de pagamentos consecutivos — use o
annual_summarypara verificar - Payout sustentavel — compare os proventos com o lucro liquido (via
/fundamentals) - Divida controlada — verifique
debt_equityenet_debt_ebitda
Setores classicos de dividendos
No mercado brasileiro, alguns setores sao conhecidos por pagar dividendos de forma consistente. Todos podem ser analisados via API:
Energia eletrica
TAEE11, TRPL4, CPLE6, CMIG4, EGIE3
Bancos
BBAS3, ITUB4, SANB11, BBDC4
Seguros
BBSE3, PSSA3, CXSE3
Saneamento e telecom
SBSP3, VIVT3, SAPR11
Integração com IA (Claude, ChatGPT, Cursor)
A bolsai se integra diretamente com assistentes de IA. No Claude e Cursor, use o servidor MCP. No ChatGPT, use via GPT Actions. Pergunte em linguagem natural: "Quais ações pagaram mais dividendos nos últimos 3 anos?"
Próximos passos
Com os endpoints que vimos, você pode construir desde um screener simples ate um sistema completo de acompanhamento de carteira. Algumas ideias:
- Agendar o script para rodar semanalmente e enviar alertas por email
- Criar um dashboard com Streamlit ou Gradio para visualizar a carteira
- Combinar com dados de FIIs (
/fiis/{ticker}) para diversificar a renda passiva - Usar o histórico trimestral (
/fundamentals/{ticker}/history) para identificar tendências
Leia também
- API de Fundos Imobiliários (FII): dividendos em Python — P/VP, DY, segmentação por tipo e tributação isenta para pessoa física
- Dividend Yield (DY) via API da B3 — fórmula, JCP vs dividendos, screening por proventos sustentáveis
- Como acessar dados fundamentalistas da B3 via API Python — tutorial detalhado de todos os endpoints de fundamentos
- Como automatizar a análise fundamentalista de ações brasileiras — screening automático por P/L, ROE, DY e EV/EBITDA
- Documentação completa — todos os endpoints, parâmetros e exemplos
Comece agora
O plano gratuito da 200 requisições por dia - suficiente para montar e testar seu screener. O plano Pro (R$49/mês) libera 10.000 requisições, histórico completo e todos os endpoints.