Como obter o histórico de dividendos da bolsa brasileira via API

Por que histórico de dividendos importa

Existe uma diferença prática entre olhar o DY atual de uma ação e olhar o histórico. O DY publicado em sites resume os últimos doze meses em um único número, geralmente sem informar quais pagamentos compõem essa janela, se vieram de JCP ou Dividendo, e se houve algum provento extraordinário. Para quem monta planilha de renda passiva, declara imposto, calcula yield on cost ou projeta a renda do próximo trimestre, o número agregado não basta. É preciso o detalhamento pagamento a pagamento.

A B3 publica os eventos corporativos no sistema CEI e nos arquivos diários, mas em formatos heterogêneos: parte como evento de bonificação, parte como evento de juros, parte como arquivo de eventos com colunas separadas por ponto e vírgula em Latin-1. Reconciliar tudo num histórico limpo é o trabalho que a API entrega pronto.

Anatomia de um pagamento de dividendo

Todo provento pago por uma companhia listada na B3 tem cinco campos relevantes para o investidor. Conhecer cada um evita erros comuns como comprar uma ação no dia da data ex achando que receberá o provento.

A distinção entre data com e data ex é onde o investidor iniciante tropeça com mais frequência. Quem compra a ação no dia da data ex recebe o papel sem o direito ao provento declarado. Quem compra no dia da data com, ou em qualquer pregão anterior, embolsa o pagamento na data de pagamento, mesmo que venda a ação antes. A API entrega a ex_date diretamente; a data com é o pregão imediatamente anterior, que pode ser calculado com um calendário B3.

Endpoint /dividends/{ticker}

A bolsai expõe o histórico de proventos no endpoint /api/v1/dividends/{ticker}. A resposta inclui o resumo agregado, o yield dos últimos doze meses e a lista completa de pagamentos ordenada por data ex (mais recente primeiro). Funciona para ações ordinárias, preferenciais, units, BDRs com pagamento e fundos imobiliários (HGLG11, KNRI11, MXRF11). Tickers descontinuados, como VIIA3, redirecionam automaticamente para o histórico do ticker sucessor (BHIA3, no exemplo).

O parâmetro opcional years controla a janela de histórico (1 a 20 anos, padrão 5). O banco contém pagamentos desde 2010 para a maioria das empresas listadas há mais tempo, e a partir do IPO para companhias mais recentes. A autenticação é feita pelo header X-API-Key, e este endpoint específico requer plano Pro. O plano gratuito oferece 200 requisições por dia em endpoints públicos (cotação, fundamentos básicos), mas o histórico completo de proventos com mais de doze meses está incluído apenas no plano pago.

Exemplo 1: histórico completo de PETR4 e DY anual

O primeiro caso de uso é o mais comum: puxar o histórico, agregar por ano civil e calcular o DY anual com base no preço médio de cada ano. PETR4 é exemplo de uma ação cíclica em que o DY oscila bastante (de menos de 3% em anos de petróleo barato a mais de 30% em anos de pagamento extraordinário).

import requests
from collections import defaultdict

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

r = requests.get(f"{BASE}/dividends/PETR4", params={"years": 10}, headers=HEADERS)
data = r.json()

print(f"DY TTM: {data['dividend_yield_ttm']:.2f}%")
print(f"Preço atual: R$ {data['current_price']:.2f}")
print(f"Proventos 12m: R$ {data['ttm_per_share']:.4f} por ação\n")

# Soma por ano e separa Dividendo vs JCP
por_ano = defaultdict(lambda: {"Dividendo": 0.0, "JCP": 0.0, "n": 0})
for p in data["payments"]:
    ano = int(p["ex_date"][:4])
    por_ano[ano][p["type"]] += p["value_per_share"]
    por_ano[ano]["n"] += 1

print(f"{'Ano':<6} {'Dividendo':>12} {'JCP':>10} {'Total':>10} {'N':>4}")
for ano in sorted(por_ano):
    d = por_ano[ano]
    total = d["Dividendo"] + d["JCP"]
    print(f"{ano:<6} {d['Dividendo']:>12.4f} {d['JCP']:>10.4f} {total:>10.4f} {d['n']:>4}")

Esse recorte revela o que o DY agregado esconde: 2022 entregou R$ 19,55 por ação só de Petrobras, dos quais R$ 16,93 vieram como Dividendo (isento) e R$ 2,62 como JCP (sofreria 15% de IR retido). Em 2020, com petróleo no fundo, os mesmos acionistas receberam R$ 2,18. Para projeções futuras, vale calcular a média dos últimos três anos completos (2023-2025: R$ 7,14 por ação ao ano) em vez de extrapolar o ano excepcional.

Exemplo 2: projetar o próximo provento de BBSE3

Empresas com cadência regular de pagamento (bancos, seguradoras, utilities, holdings) oferecem um padrão estável: data ex sempre no mesmo período do trimestre, pagamento 30 a 45 dias depois, valor por ação proporcional ao lucro. BB Seguridade (BBSE3) é exemplo clássico de seguradora com dois pagamentos semestrais, geralmente em fevereiro/agosto, com algum complementar no fim do ano.

Para projetar o próximo provento, o código abaixo calcula a média dos últimos quatro pagamentos por tipo e a frequência mediana em dias entre pagamentos consecutivos:

import requests
from datetime import datetime, timedelta
from statistics import median

r = requests.get(f"{BASE}/dividends/BBSE3", params={"years": 3}, headers=HEADERS)
pagamentos = r.json()["payments"]

# Ordena cronologicamente (API retorna mais recente primeiro)
pagamentos.sort(key=lambda p: p["ex_date"])

datas = [datetime.fromisoformat(p["ex_date"]) for p in pagamentos]
gaps = [(datas[i] - datas[i-1]).days for i in range(1, len(datas))]
gap_mediano = median(gaps[-6:])

ultimos_4 = pagamentos[-4:]
valor_medio = sum(p["value_per_share"] for p in ultimos_4) / 4
ultima_ex = datas[-1]
proxima_ex = ultima_ex + timedelta(days=gap_mediano)

print(f"Último pagamento: {pagamentos[-1]['ex_date']} → R$ {pagamentos[-1]['value_per_share']:.4f} ({pagamentos[-1]['type']})")
print(f"Cadência mediana: {gap_mediano} dias")
print(f"Valor médio últimos 4: R$ {valor_medio:.4f} por ação")
print(f"\nProjeção do próximo provento:")
print(f"  Data ex estimada:  {proxima_ex.date()}")
print(f"  Valor estimado:    R$ {valor_medio:.4f} por ação")

Para uma posição de 1.000 ações de BBSE3, a projeção implica entrada bruta de R$ 1.521 no semestre seguinte. Em empresas mais erráticas, como mineradoras (VALE3) ou petroleiras (PETR4), a média histórica perde poder preditivo, e vale combinar a projeção com o guidance público da companhia. Para concessões reguladas (TAEE11, EGIE3) e bancos (BBAS3, ITUB4), o método costuma errar por menos de 10% do valor real.

Dividendos vs JCP: tributação altera o yield líquido

Os dois tipos de provento que aparecem no campo type da API obedecem regimes fiscais distintos para a pessoa física residente. Ignorar essa diferença ao calcular renda passiva subestima ou superestima o caixa real recebido.

Dividendo

Parcela do lucro líquido distribuída após a tributação na pessoa jurídica. Historicamente isento de IR para pessoa física residente, conforme o art. 10 da Lei 9.249/1995. A reforma tributária aprovada em 2025 altera parcialmente esse regime a partir de 2026, criando faixas de tributação para alta renda, mas a maior parte dos investidores PF continua sob isenção. Na API, esses pagamentos vêm com "type": "Dividendo".

JCP (Juros sobre Capital Próprio)

Mecanismo criado pelo art. 9º da Lei 9.249/1995 que permite à companhia deduzir o pagamento da base de cálculo do IRPJ e da CSLL. Em contrapartida, o JCP sofre retenção de 15% de IR na fonte sobre o valor bruto. Bancos (Itaú, Banco do Brasil, Bradesco) e utilities usam JCP intensamente pela vantagem fiscal corporativa. Na API, esses pagamentos vêm com "type": "JCP".

O snippet abaixo recalcula o DY líquido descontando 15% do JCP, modo correto de comparar duas ações com perfis distintos de provento:

def dy_liquido(ticker, ir_jcp=0.15):
    r = requests.get(f"{BASE}/dividends/{ticker}", headers=HEADERS)
    d = r.json()
    # Soma proventos dos últimos 12 meses com tributação correta
    bruto = 0.0
    liquido = 0.0
    for p in d["payments"][:20]:  # janela aproximada de 12m
        valor = p["value_per_share"]
        bruto += valor
        if p["type"] == "JCP":
            liquido += valor * (1 - ir_jcp)
        else:
            liquido += valor
    preco = d["current_price"]
    return {
        "ticker": ticker,
        "dy_bruto": round(bruto / preco * 100, 2),
        "dy_liquido": round(liquido / preco * 100, 2),
    }

for t in ["BBAS3", "ITUB4", "TAEE11", "BBSE3"]:
    r = dy_liquido(t)
    print(f"{r['ticker']:6}  DY bruto {r['dy_bruto']:5.2f}%  →  DY líquido {r['dy_liquido']:5.2f}%")

BBSE3 não usa JCP, então DY bruto e líquido coincidem. Bancos como BBAS3 e ITUB4 perdem 8% e 9% do yield para o imposto retido na fonte do JCP. TAEE11 mistura, mas a maior parte vem como Dividendo. Em uma carteira otimizada para renda passiva, o DY líquido é o número correto a comparar com outras alternativas (Tesouro IPCA+, FIIs, debêntures incentivadas), não o bruto.

Adjusted vs not-adjusted: quando o valor "muda" no histórico

O campo adjusted indica se o value_per_share foi recalculado para refletir eventos corporativos posteriores (desdobramentos, grupamentos, bonificações). A API retorna false por padrão, ou seja, o valor histórico nominal exato que entrou na conta do investidor naquela data. Esse é o número correto para reconciliação fiscal e para Imposto de Renda anual.

Há, porém, situações em que faz sentido trabalhar com valores ajustados. Considere uma empresa que pagou R$ 4,00 de dividendo em 2018 e fez um desdobramento de 1:2 em 2020. Para comparar esse pagamento, em termos de "por ação atual", com proventos de 2024, o valor ajustado é R$ 2,00. Bibliotecas de backtest (vectorbt, bt) e ferramentas como Yahoo Finance usam valores ajustados por padrão; planilhas pessoais e declarações de IR usam valores nominais.

Filtrar ações por dividend yield com o screener

Depois de entender o histórico de uma ação específica, o próximo movimento natural é descobrir candidatas a entrar na carteira. O endpoint /screener filtra as ~264 ações negociadas por indicadores, incluindo dividend_yield, ROE, dívida e payout. O DY do screener corresponde ao mesmo número retornado por /dividends/{ticker} (campo dividend_yield_ttm), garantindo consistência entre os dois endpoints.

# Top 10 ações com DY > 7% e ROE > 12%, ordenadas por DY
r = requests.get(
    f"{BASE}/screener",
    params={
        "dividend_yield_gt": 7,
        "roe_gt": 12,
        "debt_equity_lt": 2,
        "sort": "dividend_yield",
        "order": "desc",
        "limit": 10,
    },
    headers=HEADERS,
)
for row in r.json()["data"]:
    print(f"{row['ticker']:7} DY={row['dividend_yield']:5.2f}%  "
          f"ROE={row['roe']:5.2f}%  P/L={row['pl']:5.2f}")

Combinar o screener para descobrir candidatas com o endpoint de histórico para auditar a cadência de cada pagamento é o fluxo padrão de quem monta carteira de dividendos. O tutorial de carteira completa mostra esse fluxo ponta a ponta, com pesos, rebalanceamento e simulação de renda passiva mensal.

Erros comuns no consumo do histórico

• Confundir data com com data ex. Comprar a ação na própria data ex significa receber o papel sem o direito ao provento. A ordem precisa ser executada até o pregão da data com (anterior).
• Somar JCP bruto no rendimento. O IR de 15% é retido na fonte; o investidor recebe apenas 85% do valor nominal do JCP. Calcular yield on cost com valor bruto superestima a renda passiva real.
• Extrapolar ano excepcional. Petrobras em 2022 e Vale em 2021 pagaram extraordinários que não se repetem. Usar a média de 3 a 5 anos completos reduz o ruído.
• Ignorar mudança de ticker. Via Varejo virou Casas Bahia (VIIA3 → BHIA3); a API redireciona automaticamente, mas planilhas manuais frequentemente perdem o histórico anterior à mudança.
• Misturar dividendos de FIIs e ações. FIIs pagam mensalmente, são isentos de IR para PF (com regras específicas) e o ticker termina em 11. Ações pagam tri/semestralmente, e a tributação varia conforme o tipo (Dividendo ou JCP).

Perguntas frequentes

Qual a diferença entre data com, data ex e data de pagamento?

A data com é o último pregão em que o investidor que compra a ação ainda tem direito ao provento. A data ex é o pregão seguinte, em que a ação passa a ser negociada sem o direito ao dividendo declarado. A data de pagamento é quando o valor efetivamente cai na conta da corretora, geralmente entre 30 e 90 dias após a data ex. A API retorna ex_date e payment_date diretamente no endpoint /dividends/{ticker}.

Como o histórico de dividendos é fornecido pela API da bolsai?

O endpoint /dividends/{ticker} retorna a lista completa de proventos de uma ação ou FII com data ex, data de pagamento, tipo (Dividendo ou JCP) e valor por ação, além de resumo anual agregado e dividend yield dos últimos 12 meses. O parâmetro years controla a janela (1 a 20 anos, padrão 5). Os dados começam em 2010 e cobrem todas as ações negociadas na B3, incluindo histórico de empresas que mudaram de ticker.

Dividendos e JCP têm tributação diferente?

Sim. Juros sobre Capital Próprio (JCP), instituídos pela Lei 9.249/1995, sofrem retenção de 15% de imposto de renda na fonte para pessoa física. Dividendos foram historicamente isentos no IRPF, regime alterado pela reforma tributária aprovada em 2025, que cria tributação em faixas de alta renda a partir de 2026. Ao calcular o rendimento líquido do investidor, é necessário descontar 15% sobre o valor bruto dos JCP retornados pela API.

Como projetar o próximo dividendo de uma ação?

A projeção mais simples usa o padrão histórico de cadência: empresas como BBAS3 pagam trimestralmente, ITSA4 e ABEV3 trimestralmente, TAEE11 semestralmente e poucos FIIs e ações pagam mensalmente. Calcular a média dos últimos 4 ou 8 pagamentos e somar a frequência projetada ao último ex_date oferece uma estimativa razoável, com margem de erro maior em empresas cíclicas (commodities) e menor em concessões reguladas.

Leia também

Comece agora

Consumir o histórico estruturado de dividendos via API resolve a parte mais tediosa da análise de renda passiva: reconciliar datas, separar JCP de Dividendo, projetar o próximo pagamento e atualizar o yield on cost. O plano gratuito permite testar a estrutura da resposta com 200 requests/dia. O endpoint completo de histórico (/dividends/{ticker}) está incluído no plano Pro a partir de R$29/mês, junto do screener, dos dados históricos profundos e do MCP para integração com Claude. A documentação completa traz todos os endpoints, parâmetros e exemplos prontos para copiar.

Os exemplos numéricos refletem dados disponíveis em 01 de maio de 2026 e podem variar conforme a publicação de novos eventos corporativos. Conteúdo educacional, não constitui recomendação de investimento. Decisões financeiras devem considerar o perfil, o horizonte e os objetivos do investidor.