Empresas
Endpoints relacionados a dados cadastrais, tickers, cotações/market data, indicadores (ratios), relatórios financeiros padronizados, transações de insiders, documentos oficiais e eventos corporativos.
Recomendação padrão: use
tickerem 99,9% dos casos.
Mesmo quando uma empresa troca de ticker, a base emenda as séries para manter continuidade — então, na prática, você pode indexar o seu sistema por ticker com alta segurança.
Como modelar sua integração (recomendado)
Fluxo ideal
- Use
GET /companies(lista de empresas) para montar o seu índice local. - Salve a lista de tickers associados à empresa.
- Para consumir qualquer endpoint da árvore de
companies, usecompanyIdentifier = <ticker>.
Por que isso funciona bem:
- é o identificador que aparece para o usuário final (UI, portfólio, negociações)
- resolve a maioria absoluta dos casos de produto
- facilita telas, alertas, carteiras e integrações com sistemas externos
- quando há mudança de ticker, as séries ficam “costuradas” para manter histórico contínuo
Boa prática: trate
tickercomo sua primary key externa e mantenha uma tabela simplesticker -> company(e opcionalmentecompany -> [tickers]) atualizada viaGET /companies.
Empresa vs Ativo (ticker)
- Empresa: entidade jurídica e seus dados cadastrais.
- Ticker: ativo negociado associado à empresa (classe específica).
Uma empresa pode ter vários tickers (ON/PN/UNIT etc.). No seu produto, quase sempre a navegação e a identidade começam pelo ticker — por isso ele é o padrão.
Identificadores (companyIdentifier)
A maioria das rotas aceita ticker, symbol ou company_id.
Aqui vai a diferença — com preferência brutal por ticker:
ticker (preferido)
- Identificador do ativo (ex.:
PETR4,VALE3). - É o que faz sentido para o usuário e para 99,9% dos fluxos (carteira, alertas, telas, screening, notícias, conciliação).
- As séries são mantidas contínuas mesmo quando há troca de ticker (histórico “emendado”).
Use sempre que puder.
company_id (CNPJ)
- Identificador jurídico.
- Útil quando você precisa:
- conciliar com bases legais/ERP por CNPJ
- deduplicar entidades em integrações corporativas
- fazer match com cadastros internos que já são CNPJ-first
Na prática: ótimo para “backoffice” e integrações enterprise, mas raramente necessário em produtos voltados ao investidor.
symbol (ID canônico interno)
- Um identificador normalizado/canônico da companhia dentro da base.
- Bom para casos técnicos (ex.: chaves internas, migrações, normalização), mas não é o “idioma” do usuário.
Na prática: use se você tiver um motivo específico; caso contrário, prefira ticker.
Detalhe: endpoints que têm parâmetros como
stock_type,isin, ou retornam dados por classe podem se comportar diferente dependendo se você entrou viatickerou via identificador de empresa. Prefiracompany_idquando sua intenção é a empresa, etickerquando sua intenção é o ativo.
Tipos de tickers (classes mais comuns)
No mercado brasileiro, tickers geralmente indicam a classe do papel:
- ON (Ordinária): normalmente termina com 3 (ex.:
VALE3) - PN (Preferencial): normalmente termina com 4 (ex.:
PETR4) - PNB/PNC/PND/PNE: variações históricas de preferenciais, geralmente terminam em 5, 6, 7 e 8 (menos comuns, mas existentes)
- UNIT: pacote de mais de uma classe (geralmente termina com 11, ex.:
SANB11) - BDR: recibos de ações estrangeiras negociados no Brasil (padrões variam)
Detalhe: o sufixo numérico é uma convenção forte, mas não deve ser o único critério de inferência. Para consistência, use os campos de classificação retornados pela API (quando disponíveis) ou filtros como
stock_typequando o endpoint suportar.
BDRs (Brazilian Depositary Receipts)
BDRs são recibos de valores mobiliários emitidos no Brasil que representam ações de empresas estrangeiras. Eles permitem que investidores brasileiros tenham exposição a empresas listadas em bolsas internacionais (como NYSE, NASDAQ, LSE etc.) sem precisar abrir conta no exterior.
BDRs Patrocinados vs Não Patrocinados
Existem duas categorias principais de BDR:
BDR Patrocinado É emitido com a participação direta da empresa estrangeira emissora. A empresa contrata uma instituição depositária no Brasil para emitir os recibos e participa ativamente do programa, divulgando informações financeiras e mantendo comunicação com o mercado brasileiro.
BDR Não Patrocinado É emitido sem a participação direta da empresa estrangeira. Uma instituição depositária brasileira toma a iniciativa de criar o programa e emitir os recibos por conta própria, sem envolvimento formal da empresa cujas ações são representadas.
Cobertura na Partnr API
A Partnr oferece cobertura completa para BDRs Patrocinados, incluindo todos os dados disponíveis para empresas nacionais: dados cadastrais, indicadores, relatórios financeiros, cotações, eventos corporativos, proventos e documentos.
Para BDRs Não Patrocinados, a cobertura é limitada a dados de eventos corporativos e proventos em dinheiro, refletindo a menor disponibilidade de informações públicas dessas empresas no mercado brasileiro.
Por padrão, endpoints como GET /companies e GET /companies/cash-corporate-actions retornam apenas empresas brasileiras. Para incluir BDRs na resposta, use o parâmetro bdr=true.
Setorização (metodologia própria)
A Partnr classifica as companhias listadas na B3 com uma metodologia própria, baseada na estrutura de quatro níveis do GICS (Global Industry Classification Standard) e adaptada ao mercado brasileiro.
- Os dois níveis superiores (setor e grupo setorial) seguem o padrão global sem adaptação. Uma carteira classificada pela Partnr pode ser comparada, nesses dois níveis, com carteiras classificadas por provedores internacionais.
- Os dois níveis inferiores (indústria e sub-indústria) têm adaptações ao mercado brasileiro.
A taxonomia tem 11 setores, 24 grupos setoriais, 56 indústrias e 99 sub-indústrias. Toda companhia do universo tem classificação nos quatro níveis.
A taxonomia é adaptada a partir da arquitetura do GICS, mas não é o GICS e não é endossada, revisada ou certificada pela MSCI ou pela S&P Dow Jones Indices. Diferenças em relação a provedores internacionais são esperadas, principalmente em indústria e sub-indústria.
O que cada nível significa
| Nível | Campo | Definição | Para que serve |
|---|---|---|---|
| Setor | sector | Bloco da economia em que a companhia atua. | Alocação estratégica e comparação global. |
| Grupo setorial | industry_group | Conjunto de indústrias do setor que respondem aos mesmos fatores. | Análise de fatores macro e setoriais comuns. |
| Indústria | industry | Conjunto de sub-indústrias com atividades similares; indica o modelo de negócio. | Comparação de estrutura operacional e margens. |
| Sub-indústria | sub_industry | Recorte operacional que define o negócio principal. | Seleção de pares para múltiplos comparáveis. |
Exemplo: o Itaú Unibanco está em Financeiro (FINANCIALS) → Bancos (BANKS) → Bancos (BANKS) → Bancos Diversificados (DIVERSIFIED_BANKS).
Como a classificação é decidida
- Fonte. A fonte primária é a Seção 1.3 do Formulário de Referência (FRE, Resolução CVM nº 80/2022), em que a própria companhia divulga a receita líquida por segmento operacional. Quando o FRE é insuficiente, a metodologia usa, nesta ordem, a nota de informações por segmento das demonstrações financeiras, os comunicados e fatos relevantes e, só para companhias pré-operacionais, o objeto social.
- Predominância da receita. A companhia recebe a sub-indústria do segmento com a maior participação na receita líquida consolidada. É predominância relativa, não maioria absoluta.
- Herança. A classificação é atribuída só na sub-indústria. Indústria, grupo setorial e setor são os ancestrais dessa sub-indústria, por isso os quatro níveis de uma companhia são sempre coerentes entre si.
- Desempate. Quando a diferença entre os dois maiores segmentos é menor que 2 pontos percentuais, decide, nesta ordem: a participação no lucro, a proporção de ativos operacionais, a participação média na receita dos três últimos exercícios e o foco estratégico declarado.
- Estabilidade. Uma companhia já classificada só muda de sub-indústria quando o novo segmento supera o anterior por 3 pontos percentuais ou mais, ou quando há evento societário relevante (incorporação, cisão, venda de segmento relevante, mudança substancial do negócio).
- Holdings. Holding de ativo único recebe a sub-indústria da controlada. Holding operacional recebe a classificação do ramo das suas operações. Quando nenhum segmento atinge 50% da receita e os segmentos pertencem a dois ou mais setores, a companhia é classificada em Holdings Multissetoriais (
MULTI_SECTOR_HOLDINGS). - Receita imaterial. Quando a receita é imaterial diante do ativo total ou do valor de mercado (companhia pré-operacional ou casca societária), a classificação é decidida pela composição do ativo.
A revisão é anual e acompanha a entrega dos Formulários de Referência. Eventos societários relevantes disparam revisões extraordinárias.
Adaptações ao mercado brasileiro
- Imobiliário. O Brasil não tem REITs. Quem vende imóveis (incorporadoras, operadoras, serviços) fica em Gestão e Desenvolvimento Imobiliário. Quem aluga (shopping centers, galpões logísticos, portfólios diversificados) fica em Investimento Imobiliário.
- Sem categoria residual. Nenhuma sub-indústria é um "outros". Holdings Multissetoriais é definida por um teste objetivo, não por exclusão.
- Bancos. Bancos Diversificados e Bancos Regionais são separados pela abrangência geográfica, não pelo tamanho do balanço.
- Sucroenergético. Companhias de açúcar, etanol e cogeração ficam em Produtos e Serviços Agrícolas (Consumo Básico), porque a receita de energia é minoritária.
- Saúde suplementar. Operadoras de planos de saúde e odontológicos ficam em Planos de Saúde Gerenciados (Saúde), mesmo com rede própria. Corretoras e administradoras de benefícios ficam em Corretoras de Seguros (Financeiro).
- Locação de equipamentos. Locadoras de máquinas e frota pesada têm sub-indústria própria, separada das distribuidoras.
Universo e limitações
- Universo. Companhias abertas com valores mobiliários negociados na B3. BDRs e fundos listados têm taxonomias próprias e estão fora desta classificação.
- Companhias deslistadas. Uma companhia que sai da bolsa mantém a sua última classificação, para as séries históricas continuarem corretas. Duas sub-indústrias só têm companhias deslistadas: Serviços Portuários (
MARINE_PORT_SERVICES) e Embalagens e Recipientes (CONTAINERS_PACKAGING). Não use essas duas em comparações correntes. - Um rótulo por companhia. Uma companhia com dois segmentos relevantes recebe só o rótulo do maior. Para medir a exposição efetiva, use a abertura por segmento.
- Sub-indústrias com uma só companhia. Muitas sub-indústrias têm uma única companhia. Nesses casos não há par comparável no Brasil, e a comparação relevante é internacional, nos níveis de setor e grupo setorial.
- Defasagem. A classificação reflete o último Formulário de Referência entregue.
Onde isso aparece na API
GET /companieseGET /companies/{id}comshow_sector=truedevolvem os quatro níveis como objetos{ id, name }:sector,industry_group,industryesub_industry.GET /companies/sectorsdevolve a taxonomia completa em árvore, eGET /companies/sectors/{id}devolve as companhias de qualquer nível.- O screener devolve os mesmos identificadores em campos planos (por exemplo,
sector_idesector_name).
O id é estável e vem em caixa alta com underline: use-o em filtros e integrações. O name é o rótulo de exibição em português e pode ser ajustado sem aviso.
Dica: use
sectorpara uma visão macro (dashboards e agrupamentos amplos) esub_industrypara escolher pares comparáveis.
Modelos e agregações: INDIVIDUAL vs CONSOLIDATED
Essa distinção aparece em dois contextos diferentes na rota companies:
- Relatórios financeiros
- Relatórios de transações de insiders
1) Financeiro (Balanços/DRE/DFC/DVA) — reports
Aqui aggregation é contábil:
- INDIVIDUAL: apenas a controladora (sem consolidar subsidiárias).
- CONSOLIDATED: controladora + subsidiárias (visão consolidada do grupo).
Use CONSOLIDATED quando:
- você quer enxergar o negócio “como um todo”
- a empresa tem subsidiárias relevantes
- maneira mais utilizada para a análise de ativos e cálculo de indicadores
Use INDIVIDUAL quando:
- você precisa da visão da controladora (ex.: análises específicas, comparações, estrutura societária)
- algumas empresas podem apenas reportar relatórios individuais
Detalhe: empresas de setores específicos (ex.: financeiro/seguros) podem seguir modelos de reporte distintos; isso afeta quais campos aparecem em
datae quais seções existem.
2) Insiders — insider-transactions
Aqui aggregation não é “contábil”, é organizacional (como a CVM estrutura o reporte):
- INDIVIDUAL (Inciso I): visão por estrutura societária (companhia, tesouraria, controladas e coligadas).
- CONSOLIDATED (Inciso II): visão por órgãos estatutários (Conselho, Diretoria, Fiscal, comitês etc.).
Em termos práticos:
- Quer saber ações da própria empresa em tesouraria ou movimentações de controladas/coligadas? →
INDIVIDUAL - Quer saber movimentações agregadas por Conselho/Diretoria? →
CONSOLIDATED
Frequências e janelas: ANNUAL, QUARTERLY, TTM, YTD
Essas opções aparecem principalmente em relatórios padronizados e indicadores derivados.
ANNUAL (anual)
- Período fechado do ano (ex.: 01/01 a 31/12).
- Bom para análises históricas e comparações ano a ano.
QUARTERLY (trimestral)
- Período fechado do trimestre (ex.: Q1, Q2, Q3, Q4).
- Bom para acompanhar sazonalidade e evolução intra-ano.
TTM (Trailing Twelve Months)
- “Últimos 12 meses” rolando.
- Útil para métricas que você quer suavizar sazonalidade (ex.: lucro, receita, margens).
- Considera últimos 12 meses corridos, ao calcular indicadores de preço e últimos 4 balanços, nos demais casos.
Detalhe: TTM é uma janela móvel construída a partir de relatórios publicados; se houver lacunas ou mudanças de padrão, a composição pode variar.
YTD (Year-To-Date)
- “Ano corrente até a data” (acumulado).
- Útil para acompanhar performance do ano sem esperar fechar o ano inteiro.
Detalhe: YTD depende do ponto do calendário e dos relatórios disponíveis; comparar YTD entre empresas exige alinhar datas.
Detalhes gerais dos endpoints de companies
1) Disponibilidade depende do “modelo” da companhia
Nem toda empresa reporta os mesmos campos/linhas.
Por isso:
- o objeto
datapode variar em chaves (IDs) - alguns campos podem ser
null
2) null pode significar ausência de dado (não é sempre “zero”)
null pode ocorrer por:
- divisão por zero em métricas derivadas
- campo não reportado pela companhia
- linha inexistente no modelo daquela empresa
3) Datas diferentes têm significados diferentes
Em vários endpoints você verá datas distintas:
reference_date: data de referência contábil (ex.: fim do período)start_date/end_date: janela do período reportadopublish_date: quando foi publicadoretrieval_date: quando foi capturado/atualizado na base
Boa prática: para “último resultado”, não confundir
reference_datecompublish_date.
4) Proventos: JCP, IR na fonte e datas (com/ex)
Alguns endpoints retornam proventos (dividendos, JCP, etc.) e datas relacionadas ao evento. Aqui vão as regras mais importantes para evitar interpretação errada.
JCP e net_value (valor líquido para o investidor)
Juros sobre Capital Próprio (JCP) sofre IR retido na fonte. Por isso, além do valor “cheio” do provento, existe o campo:
net_value: valor líquido efetivamente recebido pelo investidor após o desconto do IR na fonte (quando aplicável).
Em termos práticos:
- Se o evento for JCP, o investidor normalmente recebe menos que o valor anunciado (bruto), e
net_valuerepresenta o que cai na conta. - Para dividendos, em geral não há IR na fonte no pagamento e
net_valuetende a coincidir com o valor informado (quando ambos existem).
Boa prática: para projeções de caixa e conciliação com extratos, use
net_valuequando disponível.
prior_ex_date (data-com/data-base) e data-ex
Em eventos de proventos e alguns eventos corporativos, você vai ver campos relacionados ao “direito” ao evento. A interpretação correta é:
- Data-com (ou data-base): data em que você precisa estar posicionado no ativo para ter direito ao provento, esse é o campo
prior_ex_datena API. - Data-ex (ex-date): pregão seguinte a data-com – a partir desta data, o ativo passa a ser negociado sem direito ao provento.
Na prática:
- Se você compra na data-ex ou depois, você não recebe o provento daquele evento.
- Se você estava comprado até a data-com, você recebe (respeitando as regras de liquidação e o tipo de ativo).
prior_ex_date é a data que a API usa como referência para o marco de data-base* conforme a fonte do evento.
Em UI e regras de negócio, trate prior_ex_date como a data-chave para ordenar e filtrar eventos por “direito” (com/ex).
Boa prática: em timelines e alertas, rotule explicitamente “com” e “ex” na interface para evitar confusão do usuário final.
5) Fontes oficiais e rastreabilidade
A maioria dos endpoints retornam sources/source com:
| Campo | Tipo | Descrição |
|---|---|---|
| visualization_url | string | URL para visualização do documento na fonte oficial. |
| download_url | string | URL para download do documento na fonte oficial. |
| published_at | string (ISO 8601) | Data de publicação do documento na fonte. |
| name | string | Título/descrição textual do documento de origem. |
Isso permite auditoria e conciliação com fonte oficial (principalmente CVM).
Guia rápido: qual endpoint usar?- Cadastro da empresa / identificadores / tickers → companies/*
- Relatórios financeiros padronizados (Balanço/DRE/DFC/DVA) →
companies/[companyIdentifier]/reports - Transações de insiders (CVM – Resolução 44) →
companies/[companyIdentifier]/insider-transactions - Documentos (fatos relevantes, avisos aos acionistas e comunicados ao mercado) →
companies/[companyIdentifier]/documents - Eventos corporativos em ações (desdobramentos, grupamentos etc.) →
companies/[companyIdentifier]/corporate-actions - Lista filtrada e ranqueada (screening) →
POST /screener## Boas práticas de integração- Prefiracompany_idquando o fluxo for centrado em empresa. - Prefira
tickerquando o fluxo for centrado em ativo (tela de cotação). - Para timelines e histórico longo, use filtros por data (
start_date/end_date) para performance e consistência. - Em relatórios, sempre considere
publish_date+reference_datepara entender “o que é mais recente”.
Perguntas frequentes
ticker como padrão na maioria dos fluxos de produto (cotação, carteira, alertas e telas). Use company_id quando sua regra for jurídica/backoffice e symbol apenas em cenários técnicos específicos.CONSOLIDATED para visão do grupo econômico e INDIVIDUAL para visão da controladora. Em insiders, INDIVIDUAL e CONSOLIDATED seguem a estrutura de reporte da CVM (societário vs órgãos estatutários).reference_date com publish_date. Para “último divulgado”, priorize publish_date; para análise contábil do período, use reference_date.