Objetos e contexto

O DataBolsa organiza o mercado como objetos conectados. Um ticker é uma porta de entrada, não o limite da análise: o papel pode levar à empresa emissora, aos documentos publicados, aos fundos que o detêm, aos eventos que o afetaram e às medidas observadas ao longo do tempo.

O que um objeto reúne

• Identidade: nomes e identificadores como ticker, CNPJ, ISIN ou código da série.
• Fatos: medidas com valor, data de referência, unidade e procedência.
• Histórico: a evolução temporal de uma ou mais medidas.
• Propriedades: características descritivas do objeto.
• Relações: conexões explícitas com outros objetos, como emite, detém, administra ou compõe.
• Evidências e eventos: documentos e acontecimentos associados ao sujeito.

Nem todo objeto possui todos os capítulos. Ausência de dado não vira zero e uma relação só é apresentada quando existe uma afirmação sustentada pela fonte.

Papéis históricos

O cadastro de equity_security inclui ações e units históricas quando há negociação observada e identificação inequívoca do emissor. A recuperação usa a família do instrumento no ISIN brasileiro (ACN ou CDA), além do código de negociação; ticker e código de mercado isolados não distinguem ações, BDRs, fundos e índices.

O FCA é uma fonte de confirmação, mas sua ausência não prova que um papel não existia. Documentos oficiais revisados podem sustentar a associação exata entre ticker, ISIN, classe e CNPJ; o registro conserva o endereço e o hash do documento. Essa evidência não autoriza outros papéis da mesma raiz. Divergências entre emissores ou classes impedem a recuperação automática, e todas as versões de ISIN observadas sob o código precisam resolver para um único emissor. A concordância com o FCA é uma checagem cadastral, não uma prova independente quando o próprio FCA é a origem do vínculo.

A presença de um objeto não confirma negociação atual. A primeira e a última cotação disponíveis também não são, por si só, datas oficiais de listagem ou encerramento. Identificadores de domínios diferentes podem coincidir: informe kind: "equity_security" ao resolver um código quando quiser especificamente o papel.

Recuperar um código histórico não afirma automaticamente uma renomeação. Renomes documentados da mesma emissora e classe podem preservar esse vínculo mesmo quando o sucessor deixa de aparecer no cadastro de negociação recente. Mesmo quando os códigos resolvem para o mesmo objeto, confira a cobertura do histórico retornado antes de montar uma série contínua. O cadastro não garante sozinho um universo histórico completo ou a reconstrução das informações conhecidas em cada data.

Nem todo código com ISIN de ação ou unit é um papel: cestas de bônus de subscrição e recibos de subscrição (por exemplo, os códigos com sufixo 13 ou 97 a 99) ficam fora do cadastro com o motivo registrado, em vez de virar um objeto. Um mesmo código também pode ter sido usado em mais de um trecho de negociação, com outro código do mesmo papel no intervalo; por isso a primeira e a última cotação de um código não delimitam um período contínuo.

Dias sem cotação seguem o calendário de pregões: feriados nacionais (o calendário de feriados do mercado), os dias em que a B3 não abre além deles (24/12, o último dia útil do ano e, até 2021, os feriados paulistas) e fechamentos extraordinários documentados. Um dia útil sem pregão fora dessas regras é uma falha de coleta, não um dia sem negociação.

As duas datas de um provento

Um provento em dinheiro tem quatro datas: a aprovação, a data-com (o último pregão em que comprar ainda dá direito), a data ex (o pregão seguinte, em que o preço passa a negociar sem o provento) e o pagamento (quando o valor entra na conta). Data-com e data ex são o mesmo limite visto dos dois lados, em pregões consecutivos.

Perguntas diferentes se respondem por datas diferentes, e duas bases atravessam toda a plataforma:

• Direito — o limite é a data-com: quem estava posicionado no fechamento daquele pregão recebe, ainda que venda no dia seguinte. É a base do retorno total, porque o preço cai na data ex e reconhecer o provento ali mantém a série contínua. As medidas desta base são dividend_per_share, jcp_per_share e o rendimento de fundo imobiliário, carimbadas pela data ex — o outro lado do mesmo limite. As janelas de dividend yield e de payout também são contadas por aqui.
• Caixa — a base é a data de pagamento, e somente ela. É o que determina quando o valor pode ser gasto ou reinvestido. As medidas desta base são dividend_paid_per_share, jcp_paid_per_share e dividend_paid_per_share_net, carimbadas pela data de pagamento; uma declaração sem essa data não entra nelas.

Nenhuma das duas aproxima a outra: elas respondem perguntas distintas e ambas são corretas no seu eixo. Uma data de pagamento ausente nunca é substituída pela data ex, nem em cálculo nem em exibição.

A cobertura das duas bases é bem diferente, e isso é limitação de fonte, não de modelagem. A data-com tem cobertura praticamente integral desde 1998. A data de pagamento de ação existe em cerca de 3% das declarações e em nenhuma anterior a 2025, porque a B3 só a publica na janela móvel recente do suplemento; consultas às medidas de caixa acima devolvem vazio fora dessa janela, e o retorno realizado de períodos anteriores não pode ser derivado delas. Em fundo imobiliário a mesma data vem do informe de rendimentos e cobre acima de 96% das distribuições desde 2017.

Um valor a que a carteira teve direito e cuja data de pagamento não é publicada permanece um direito comprovado: ele não é descartado nem datado por aproximação, e sim somado à parte, fora de qualquer série de caixa.

Proventos e mudanças de código

Renomes documentados identificam o mesmo papel. Quando a fonte republica um provento sob códigos antigos e novos, o histórico consolida essa ocorrência no código canônico, sem criar um segundo direito de recebimento. Classes distintas continuam separadas. A associação de proventos ao papel preserva a classe exata informada pela B3, incluindo PNA, PNB, PNC e PND. O ISIN do suplemento e das cotações permite distinguir esses direitos. Quando o ISIN da cotação está ausente, a especificação do COTAHIST pode fornecer a classe; a última data de negociação não decide qual classe recebe um pagamento. Uma associação ausente ou ambígua fica pendente de reconciliação, sem escolher arbitrariamente um papel. Caixa e ajuste de retorno total usam essa mesma resolução. Essa evidência de classe não substitui a validação histórica de identidade e das transformações do instrumento.

Declarações ou parcelas distintas não devem ser confundidas apenas por terem valores iguais. O suplemento da B3 fornece o calendário observado: duas parcelas iguais com pagamentos em datas diferentes permanecem dois registros. A declaração histórica sem pagamento não acrescenta um terceiro direito quando coincide com esse calendário. A conciliação considera emissor, classe, tipo, aprovação, data-com e valor; mudanças na captura mais recente substituem o calendário anterior daquele evento.

A coleta do histórico profundo preserva as linhas originais repetidas e sua localização na resposta da B3. Essa repetição, isoladamente, não comprova parcelas adicionais: é necessário um calendário ou documento que as distinga. Capturas anteriores que já eliminaram linhas iguais não recuperam essa informação sem nova coleta.

Uma data de pagamento ausente não significa pagamento na data ex. A data ex depende do calendário observado; eventos anteriores à cobertura desse calendário não são transferidos para o primeiro pregão disponível. A cobertura de parcelas e pagamentos históricos deve ser conferida antes de calcular reinvestimento ou retorno realizado. Um calendário oficial que não informa data-com ou data ex pode completar pagamentos somente quando a aprovação identifica uma única data ex na B3 para o mesmo papel e tipo, e o total declarado coincide. Datas explícitas inválidas não são substituídas por essa inferência. Aprovações com várias datas ex continuam sem conciliação automática. Uma observação contestada por documento oficial revisado fica em quarentena: a cesta não completa pagamentos, o valor original permanece auditável e nenhuma data alternativa é aplicada automaticamente.

O valor bruto declarado e o líquido efetivamente pago podem divergir por retenções e atualizações. Um cronograma oficial deve preservar essas duas medidas e as parcelas, mesmo quando seus valores são iguais. Uma captura atual de histórico não comprova que cada valor já era público na data ex; aprovação, divulgação e captura são datas distintas.

Uma revisão documentada pode reconstruir parcelas de principal que a fonte histórica não distingue. Ela exige correspondência exata dos registros revisados; se a fonte mudar, a revisão fica pendente e não substitui os novos registros. Nesses eventos, o cálculo adota o principal nominal por parcela. Atualizações monetárias até o pagamento entram somente na liquidação, separadas do principal usado no ajuste de preços e no direito a receber. Essa convenção não calcula o valor de mercado nem a atualização diária do recebível. Eventos ainda não revisados conservam a semântica original da fonte e podem continuar misturando componentes; a correção não estabelece cobertura integral.

O líquido calculado de JCP aplica retenção padrão de 15% a aprovações anteriores a 01/01/2026 e 17,5% às aprovações a partir dessa data. A LC 224/2025, arts. 8 e 14 vincula a retenção ao pagamento ou crédito ao beneficiário. A data de aprovação da B3 é uma aproximação do crédito, não sua comprovação. Pagamento em 2026, isoladamente, não muda a retenção de uma aprovação de 2025. Sem aprovação conhecida, permanece a estimativa histórica de 15%, cuja alíquota precisa de conferência no aviso original. Esse líquido não é um extrato de pagamento nem uma apuração fiscal individual. Dividendos permanecem com líquido igual ao bruto: condições tributárias individuais, inclusive as regras de dividendos de 2026, não são modeladas nesse campo.

Pessoas

Administradores, conselheiros, membros de comitê e acionistas relevantes das companhias abertas são objetos do tipo person, a partir do Formulário de Referência entregue à CVM. A pessoa liga-se à companhia por serves_on (o cargo viaja em series e o rótulo em label) e por shareholder_of (participação em pontos percentuais, com controlador ou acordo_de_acionistas em label). A identidade é um hash irreversível (person_key): o documento da pessoa nunca é publicado, e o nome é apenas rótulo, nunca chave. Nascimento, profissão e parentesco não fazem parte do objeto.

Comece pelo que você conhece

No produto, pesquise pelo nome ou identificador. Na API, resolva primeiro a identidade e depois peça apenas o capítulo necessário:

databolsa resolveObject PETR4 --kind equity_security --json
databolsa getObjectFacts <entity_id> --facts close,dy_12m --json
databolsa getObjectHistory <entity_id> --facts close --from 2025-01-01 --json
databolsa listObjectLinks <entity_id> --relation issued_by --json

Operações especializadas continuam disponíveis quando preservam um cálculo ou uma estrutura de domínio útil. Para integrações novas, prefira a superfície de objetos e descubra as capacidades aplicáveis ao sujeito em vez de codificar uma lista fixa de endpoints.

Veja os handles tipados em SDK TypeScript e a referência completa em API · Objetos.

Coerência dos calendários de proventos

Quando uma fonte publica data-com e data ex, a data ex precisa corresponder ao próximo pregão observado após a data-com. Datas contraditórias ou explicitamente malformadas impedem usar aquele cronograma para completar um pagamento. A outra data válida não apaga o erro. Avisos oficiais revisados conservam sua referência separada, e divergências de valores continuam exigindo conciliação.