Pular para o conteúdo principal
Cole no ChatGPT/Claude e peça para resumir/gerar SDK.

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 ticker em 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​

  1. Use GET /companies (lista de empresas) para montar o seu índice local.
  2. Salve a lista de tickers associados à empresa.
  3. Para consumir qualquer endpoint da árvore de companies, use companyIdentifier = <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 ticker como sua primary key externa e mantenha uma tabela simples ticker -> company (e opcionalmente company -> [tickers]) atualizada via GET /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 via ticker ou via identificador de empresa. Prefira company_id quando sua intenção é a empresa, e ticker quando 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_type quando 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.

Como incluir BDRs nas consultas

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.

Relação com o GICS

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ívelCampoDefiniçãoPara que serve
SetorsectorBloco da economia em que a companhia atua.Alocação estratégica e comparação global.
Grupo setorialindustry_groupConjunto de indústrias do setor que respondem aos mesmos fatores.Análise de fatores macro e setoriais comuns.
IndústriaindustryConjunto de sub-indústrias com atividades similares; indica o modelo de negócio.Comparação de estrutura operacional e margens.
Sub-indústriasub_industryRecorte 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​

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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).
  6. 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).
  7. 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 /companies e GET /companies/{id} com show_sector=true devolvem os quatro níveis como objetos { id, name }: sector, industry_group, industry e sub_industry.
  • GET /companies/sectors devolve a taxonomia completa em árvore, e GET /companies/sectors/{id} devolve as companhias de qualquer nível.
  • O screener devolve os mesmos identificadores em campos planos (por exemplo, sector_id e sector_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 sector para uma visão macro (dashboards e agrupamentos amplos) e sub_industry para escolher pares comparáveis.

Modelos e agregações: INDIVIDUAL vs CONSOLIDATED​

Essa distinção aparece em dois contextos diferentes na rota companies:

  1. Relatórios financeiros
  2. 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 data e 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 data pode 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 reportado
  • publish_date: quando foi publicado
  • retrieval_date: quando foi capturado/atualizado na base

Boa prática: para “último resultado”, não confundir reference_date com publish_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_value representa o que cai na conta.
  • Para dividendos, em geral não há IR na fonte no pagamento e net_value tende a coincidir com o valor informado (quando ambos existem).

Boa prática: para projeções de caixa e conciliação com extratos, use net_value quando 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:

CampoTipoDescrição
visualization_urlstringURL para visualização do documento na fonte oficial.
download_urlstringURL para download do documento na fonte oficial.
published_atstring (ISO 8601)Data de publicação do documento na fonte.
namestringTí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- Prefira company_id quando o fluxo for centrado em empresa.
  • Prefira ticker quando 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_date para entender “o que é mais recente”.

Perguntas frequentes

Use 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.
Em relatórios financeiros, use 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).
Não confunda reference_date com publish_date. Para “último divulgado”, priorize publish_date; para análise contábil do período, use reference_date.