Histórico de Dividendos e JCP da B3 com Python e API

Para baixar dividendos e JCP de ações, use /api/v2/stocks/dividends. Para rendimentos de FIIs, use /api/v2/fii/dividends.

As duas rotas são separadas porque ações e fundos imobiliários têm fontes e eventos diferentes.

curl "https://brapi.dev/api/v2/stocks/dividends?symbols=PETR4&startDate=2024-01-01&sortOrder=asc"

curl "https://brapi.dev/api/v2/fii/dividends?symbols=MXRF11&startDate=2024-01-01&sortOrder=asc"

Quais datas guardar

Um provento não cabe em uma coluna chamada apenas data. Guarde cada marco em seu campo correto:

O nome exato e a disponibilidade dos campos dependem do tipo de evento. Consulte o schema atual em dividendos de ações e dividendos de FIIs.

Baixar dividendos de ações com Python

import os
import requests
import pandas as pd

token = os.getenv("BRAPI_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}

response = requests.get(
    "https://brapi.dev/api/v2/stocks/dividends",
    params={
        "symbols": "PETR4,VALE3",
        "startDate": "2024-01-01",
        "sortBy": "paymentDate",
        "sortOrder": "asc",
    },
    headers=headers,
    timeout=30,
)
response.raise_for_status()

payload = response.json()
rows = []

for item in payload["results"]:
    data = item["data"]

    for event in data.get("cashDividends", []):
        rows.append({
            "symbol": item["symbol"],
            "eventType": "cash",
            **event,
        })

df = pd.DataFrame(rows)
print(df.head())

A resposta também pode conter dividendos em ações e subscrições. Mantenha os tipos separados, pois quantidade de ações e dinheiro recebido não são a mesma medida.

Baixar rendimentos de FIIs

response = requests.get(
    "https://brapi.dev/api/v2/fii/dividends",
    params={
        "symbols": "MXRF11,HGLG11",
        "startDate": "2024-01-01",
        "sortOrder": "asc",
    },
    headers=headers,
    timeout=30,
)
response.raise_for_status()

payload = response.json()
df_fii = pd.DataFrame(payload["dividends"])

Confirme a chave principal no schema antes de publicar o código em produção. O endpoint de FIIs usa um envelope próprio para refletir a semântica do fundo.

Exportar para CSV

for column in ["approvedOn", "lastDatePrior", "paymentDate"]:
    if column in df.columns:
        df[column] = pd.to_datetime(df[column], errors="coerce")

df.to_csv("dividendos-b3.csv", index=False, encoding="utf-8")

Preserve o ticker, o tipo de evento e as datas originais. Esses campos permitem reprocessar uma carteira quando a regra de negócio mudar.

Calcular o valor recebido

Para um evento em dinheiro:

df["grossAmount"] = df["rate"] * df["quantityOnRecordDate"]

quantityOnRecordDate deve representar a quantidade na data com direito ao provento. Usar a posição atual produz um valor errado quando houve compra ou venda entre a data com e o pagamento.

Impostos e retenções dependem do tipo de evento e da situação do investidor. Não calcule o líquido apenas subtraindo uma alíquota fixa de todos os registros.

Dividendos e preço ajustado

Há dois modos comuns de calcular retorno:

1. usar uma série ajustada que incorpore eventos;
2. usar o preço não ajustado e somar os fluxos de caixa separadamente.

Misturar os dois sem conferir a metodologia pode contar o dividendo duas vezes. Veja preço ajustado de ações antes de montar um backtest.

Casos que exigem atenção

• pagamento anunciado e depois alterado;
• evento sem data de pagamento confirmada;
• ticker renomeado entre o anúncio e a consulta;
• bonificação ou subscrição tratada como dinheiro;
• duplicata criada por versão retificada;
• quantidade atual usada no lugar da posição histórica.

Para FIIs, não invente uma data de pagamento aplicando um intervalo fixo. O número de dias varia entre fundos e competências.

Montar um calendário

Ordene pelo campo que representa a pergunta do usuário. Um calendário de recebimentos usa paymentDate. Uma tela de direitos usa lastDatePrior.

O projeto completo está em calendário de dividendos de FIIs com Python.