Proventos e dividend yield

A única fonte fora da CVM — e por quê

Todo o resto deste banco vem dos dados abertos da CVM (DFP, ITR, cadastro). Os proventos são a exceção: a CVM não publica um CSV de proventos comparável às demonstrações. A fonte aqui é a própria B3, pelo serviço público GetListedCashDividends, que devolve o histórico de dividendos e JCP por empresa.

O elo entre o nosso cd_cvm e o filtro que a B3 entende (tradingName) é o codeCVM do catálogo da B3 (GetInitialCompanies) — casado por igualdade codeCVM == cd_cvm, nunca por semelhança de nome. Cobertura atual: 300 das 304 empresas com ticker resolvido (98,7%). As poucas que ficam de fora são as que não aparecem no catálogo da B3 — a limitação está declarada, não escondida.

O que é guardado

Cada provento é gravado como a B3 entrega, com o tipo original preservado para auditoria:

data_com vs data-ex. A B3 informa o último dia com direito (lastDatePriorEx). A data-ex — primeiro pregão em que a ação já é negociada sem o provento — é o pregão seguinte. Não a derivamos aqui porque isso exigiria um calendário de pregões; guardamos o dado cru e deixamos a regra explícita.

Dividend yield (12 meses)

• DY 12m = soma dos proventos com data_com nos últimos 365 dias ÷ último preço de fechamento disponível (COTAHIST do ticker principal).
• O resumo anual e o DY consideram apenas a classe do ticker consultado (ON/PN/UNT, inferida pela terminação do código: 3→ON, 4→PN, 11→UNT). Somar proventos de ON e PN seria misturar ações diferentes. O bloco proventos da resposta traz todas as classes, cru.
• É yield histórico (o que foi pago), não projeção. Valor bruto: sobre JCP há retenção de 15% de IR na fonte que não é descontada aqui.

Limitações declaradas

• Fonte B3, não CVM: sujeita a mudança do serviço público. A ingestão é best-effort — se a B3 estiver indisponível no build, o histórico existente é mantido e o pipeline segue (os invariantes de proventos passam a skip em vez de reprovar).
• Só proventos em dinheiro (dividendos, JCP, rendimentos). Bonificações e desdobramentos não entram neste bloco.
• Histórico por empresa paginado em blocos de 120 (teto do serviço da B3), percorrido até o fim — sem truncar silenciosamente.
• preco_com histórico não é ajustado por desdobramento na fonte. Quando o provento por ação supera 5× o preço informado na data-com (sinal claro de preço não ajustado em dado antigo), o registro recebe a flag preco_com_nao_ajustado: o valor do provento continua confiável, mas o preco_com daquele registro, não. A flag nasce junto do número, como em todo o banco.