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.

Setorização (metodologia própria)

A Partnr usa uma metodologia própria de setorização, inspirada no GICS (Global Industry Classification Standard), para corrigir inconsistências comuns em categorizações prontas (ex.: classificações que não acompanham mudanças de modelo de negócio, holdings mal rotuladas, empresas “multi-linha” jogadas em um setor genérico, etc.).

A classificação é hierárquica e segue quatro níveis:

• sector (Setor Econômico)
• industry_group (Grupo de Indústrias)
• industry (Indústria)
• sub_industry (Subindústria)

Princípio central: classificamos a companhia pela origem da receita / atividade principal (“o que realmente gera receita recorrente e domina o mix”), e não apenas pelo rótulo histórico ou pela natureza jurídica.

O que cada nível significa

Organizamos empresas em uma hierarquia de 4 níveis (Setor → Grupo → Indústria → Subindústria), onde cada empresa pertence a uma única categoria em cada nível.

1) sector — Setor Econômico

É o nível mais amplo: responde “em qual grande parte da economia a empresa atua?”
Ex.: Financeiro, Energia, Tecnologia, Saúde, etc.

2) industry_group — Grupo de Indústrias

É um recorte dentro do setor, agrupando negócios com dinâmicas semelhantes (modelo operacional, riscos e drivers).
Ex.: dentro de Financeiro, separar bancos, seguros, gestão de ativos, serviços financeiros, etc.

3) industry — Indústria

Nível mais específico: responde “qual é a indústria dominante do negócio?”
Ex.: “Bancos Diversificados” vs “Bancos Regionais” (exemplo ilustrativo de granularidade).

4) sub_industry — Subindústria

É o nível mais fino e “de produto”: responde “o que a empresa faz exatamente?”
Ex.: um nicho bem específico dentro de uma indústria (ex.: meios de pagamento, adquirência, software vertical, etc).

Como decidimos (regras práticas)

A classificação é baseada em receita e atividade econômica predominante:

1. Identificamos a origem da receita (principal linha de negócio e suas variações).
2. Escolhemos a atividade principal (o “core” que explica valuation, risco e comparáveis).
3. Em empresas com múltiplas linhas relevantes, classificamos pelo segmento dominante e usamos dados auxiliares (descrição operacional, notas explicativas e comunicação ao mercado) para evitar distorções.
4. Holdings e estruturas societárias são tratadas pelo negócio econômico subjacente, sempre que possível.

Resultado prático: comparáveis melhores, filtros de screener mais úteis e menos “lixo” em setores genéricos.

Onde isso aparece na API

Sempre que você encontrar campos como:

• sector_id, sector_name
• industry_group_id, industry_group_name
• industry_id, industry_name
• sub_industry_id, sub_industry_name

…eles seguem essa taxonomia.

Dica: use sector quando você quer uma visão macro (dashboards e agrupamentos amplos) e desça para industry/sub_industry quando o objetivo é filtragem fina (screener e análise de 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:

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- 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”.