Pular para o conteúdo
TickerLabData

Documentação · API v1

Integre sozinho, pela documentação

Endereço base: https://api.tickerlab.com.br/data/v1. Tudo é JSON. Datas em ISO (AAAA-MM-DD). Nomes de campos, parâmetros e códigos de erro em inglês.

Começar

No beta, as chaves são dadas por contrato a quem vai integrar: não há cadastro automático nem cobrança. Para pedir uma, escreva para [email protected] dizendo quem é a organização e o que pretende consultar. A chave pertence à organização, e as chaves dela dividem a mesma cota.

Com a chave, a primeira chamada mostra o que ela pode pedir:

curl -H "Authorization: Bearer $TICKERLAB_CHAVE" \
  https://api.tickerlab.com.br/data/v1/catalog

O catálogo não gasta cota. Ele lista, só para a sua chave, os conjuntos, os campos, a licença e a frase de atribuição de cada fonte.

Autenticação

A chave vai só no cabeçalho: Authorization: Bearer <chave> ou X-API-Key: <chave>. Pela URL ela iria parar nos logs do servidor e da Cloudflare, então um pedido com a chave na URL (api_key, key, token…) é recusado com 400 api_key_in_url, sem repetir o valor. Chave inválida, vencida ou sem contrato dá sempre o mesmo 401 invalid_api_key: a resposta não diz qual foi o motivo.

Rotas

RotaO que devolveParâmetros
GET /companiesBusca de empresas (só pessoa jurídica) por CNAE, UF, município, porte, natureza jurídica, situação, abertura, matriz, capital social e número de estabelecimentos ativos, com fonte e dia de publicação em cada campo. Capital, estabelecimentos e registros na Anvisa são sinais aproximados de porte, não faturamento. Registros na Anvisa (cosméticos, saneantes e produtos para saúde): anvisa_type escolhe o tipo, anvisa_active_min e anvisa_total_min filtram pela contagem de registros ativos e totais, com a fonte e o dia do retrato. Ordena por CNPJ, capital, branches ou anvisa (- na frente, decrescente). Exige ao menos um filtro além da situação; 50 por página (máximo 100), próxima página por next_cursor. Conjunto prospectingcnae, state, municipality, size, legal_nature, registration_status, opened_before, opened_after, head_office, capital_min, capital_max, branches_min, anvisa_type, anvisa_active_min, anvisa_total_min, sort, cursor, limit, known_at
GET /companies/{cnpj}Situação cadastral do estabelecimento na Receita (situação, data, motivo, matriz, mês do retrato)known_at
GET /companies/{cnpj}/financialsDFP e ITR da CVM: um valor por conta e período, com documento, versão e origemknown_at, period_end
GET /companies/{cnpj}/profileO perfil da empresa: o cadastro na Receita (o mesmo de /companies/{cnpj}) e, da companhia aberta, cada DFP e ITR devida até a data, com o prazo da CVM, o dia da entrega, os dias úteis de atraso e a situação (on_time, gray_zone, late, severely_late, not_filed). A situação é a regra do TickerLab sobre o índice público da CVM, não opinião sobre a empresaknown_at
GET /companies/{cnpj}/comparablesOs comparáveis da companhia aberta: as companhias do mesmo grupo de setores (pelo setor do FCA à CVM), cada uma com receita, EBITDA, lucro, patrimônio, dívida líquida, margens, ROE e dívida líquida sobre EBITDA do último DFP já entregue, e a mediana de cada razão entre os pares (só com pelo menos 8 pares). EBITDA, dívida líquida e as razões são contas do TickerLab sobre as linhas do DFPknown_at
GET /companies/{cnpj}/eventsOs eventos da companhia, do mais novo ao mais velho: cada documento entregue à CVM pelo IPE, de qualquer estabelecimento da mesma raiz (ipe_filing: protocolo, categoria, tipo, período de referência e endereço do documento; o assunto escrito pela companhia não sai) e cada troca da firma de auditoria informada nos FCAs (auditor_change: a firma anterior, a nova, o dia em que valeu e os anos com a anterior, conta do TickerLab). A página vai até o limite de linhas do plano; a seguinte, por next_cursorknown_at, types, cursor
GET /companies/{cnpj}/linksOs vínculos da empresa na rede do TickerLab, de 1 a 3 saltos: de quem ela era controlada, coligada ou participada e quem ela controlava, com a participação no capital informada no FRE (subsidiary_of, affiliate_of, investee_of), e a firma que a auditava, pelo FCA (audits). Cada ponta sai com o id na rede, a raiz do CNPJ e a razão social do retrato mensal da Receita mais novo já público no dia, com o mês dele; a ponta que é pessoa (MEI, empresário individual, sócio pessoa física) não sai. A lista vai até o limite de linhas do plano (truncated)known_at, depth, types
GET /companies/{cnpj}/assetsOs ativos da empresa nas bases abertas das agências, só pessoa jurídica. Hoje: os contratos de exploração e produção de petróleo e gás da ANP de que a empresa (qualquer estabelecimento da mesma raiz) é sócia, com rodada, fase, campo ou bloco, bacia, terra ou mar, a parte da empresa no contrato e se ela é a operadora. Cada bloco diz se achou, a fonte, o dado mais novo da base no dia e o que ela cobre; os outros sócios do contrato não saem. Não achar quer dizer que a fonte não lista a empresa, não que ela não tenha o ativo; a resposta lista o que a rota ainda não cobre (mineração, imóveis, veículos, marcas, licenças). A lista vai até o limite de linhas do plano (truncated). Conjunto assetsknown_at
GET /buyersQuem já se mexeu num setor, só pessoa jurídica: as empresas que entraram como sócias de uma empresa com estabelecimento ativo do CNAE principal (classe de 5 ou subclasse de 7 dígitos; na UF, se dada) nos últimos anos pedidos (padrão 3, até 10), e, no dia pedido, os FIPs sócios dessas empresas e as companhias abertas com controlada ou coligada no setor. Cada comprador traz os sinais e até 5 exemplos por sinal, com fonte e data; até 50 compradores (padrão 20), dentro do limite de linhas do plano. A entrada do fundador e a de dentro do mesmo grupo não contam; os limites vêm na resposta. É movimento passado, não intenção de compra. Conjunto buyerscnae, state, years, limit, known_at
GET /funds/{cnpj}Cadastro e taxas do fundo, carteira da competência mais nova já pública e, com assumed_return, o custo da taxa em 5 e 20 anosknown_at, assumed_return
GET /credit/{cnpj}Ficha de crédito do cedente ou do sacado, só fatos: situação cadastral e situação especial na Receita, fatos relevantes dos últimos 12 meses e presença como cedente em FIDCs, cada um com a fonte e o dia em que ficou público. Não é nota nem opinião de créditoknown_at
GET /sectorsOs setores que a API entrega hoje, com o dia da conta mais nova. Não gasta cotanenhum
GET /sectors/{key}Um setor (eletricas, bancos, seguros, saude_suplementar, telecom): por série da agência, o total do mercado, CR4, HHI e a faixa de concentração por ano, a fatia de cada companhia aberta, e a lista das companhias do setor. Só empresasknown_at
GET /sectors/{key}/deckO mesmo de /sectors/{key} como apresentação .pptx, com a fonte e o dia de cada tabela nas notas, o slide de fontes e o de limites. Conta como um pedidoknown_at
GET /companies/{cnpj}/deckO mesmo de /companies/{cnpj}/profile como apresentação .pptx, com a fonte e o dia de cada tabela nas notas, o slide de fontes e o de limites. Conta como um pedidoknown_at
POST /companies/batchO mesmo de /companies/{cnpj} para até 100 CNPJscorpo: cnpjs, known_at
POST /funds/batchO mesmo de /funds/{cnpj} para até 100 CNPJscorpo: cnpjs, known_at, assumed_return
POST /credit/batchO mesmo de /credit/{cnpj} para até 100 CNPJscorpo: cnpjs, known_at
GET /catalogO que a sua chave pode pedir hojenenhum
GET /usageSeu consumo do mês, limites do plano e o que falta da cotanenhum

O {cnpj} vai só com os 14 dígitos, com o dígito verificador certo. CPF nunca é aceito. assumed_return é um retorno anual que você informa (por exemplo 0.08); o custo da taxa é uma conta sobre esse número, não uma previsão de rentabilidade.

Como era na data: known_at

Toda rota de dado aceita known_at=AAAA-MM-DD. A resposta traz só o que já era público naquele dia: empresas reapresentam balanços, e a base guarda cada versão com o dia em que ficou pública. Sem o parâmetro, vale hoje. Data no futuro é recusada (400 invalid_known_at). É o que deixa um backtest honesto.

Formato da resposta

Cada valor vem num envelope com a origem:

{
  "value": …,
  "source": "cvm-hist-dfp",
  "published_at": "2025-02-27",   // o dia em que ficou público
  "observed_at": null             // quando o TickerLab o viu, se a base sabe
}

No fim da resposta, sources traz uma vez cada fonte usada, com license e attribution. As licenças abertas (ODbL da CVM, CC BY da Receita) pedem que quem redistribui cite a fonte: use a frase de attribution. Nas demonstrações, valid_until é o dia em que outra versão tomou o lugar (vazio: vale até hoje) e truncated: true avisa que o limite de linhas do plano cortou a resposta.

Lotes

Os lotes aceitam até 100 CNPJs e um known_at (e, em fundos, um assumed_return) para todos. Conta um pedido da cota por CNPJ válido e distinto; item inválido volta com status: invalid_cnpj e não conta.

curl -X POST https://api.tickerlab.com.br/data/v1/companies/batch \
  -H "Authorization: Bearer $TICKERLAB_CHAVE" -H "Content-Type: application/json" \
  -d '{"cnpjs": ["33000167000101", "33592510000154"], "known_at": "2025-04-30"}'

Erros e limites

StatusCódigoO que fazer
400api_key_in_urlMande a chave no cabeçalho e troque a chave: ela já passou pela URL.
400invalid_cnpj, invalid_known_at, invalid_assumed_returnCorrija o parâmetro (assumed_return maior que -1 e até 1).
401invalid_api_keyChave errada, vencida ou sem contrato. A resposta não diz qual.
404not_availableO dado não existe, não pode sair pelo portão de direitos ou o CNPJ não é de uma empresa que a API serve. Os três casos respondem igual.
429rate_limited, monthly_quota_exceededEspere o tempo do cabeçalho Retry-After (segundos).
503service_unavailableA base está fora do ar; o pedido não conta na cota. Tente de novo.

Versões

A versão está no endereço (/data/v1). Dentro da v1 não mudamos nome de campo, de parâmetro nem código de erro; podemos acrescentar campos e rotas. Qualquer quebra vira /data/v2, com aviso antes aos titulares de chave e a v1 convivendo por um período combinado.

Direitos por fonte

FonteConjuntoLicençaComo citar
CVM · DFP e ITR (cvm-hist-dfp, cvm-hist-itr)financials, profiles, comparablesODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · formulário de referência, controladas e coligadas (cvm-hist-fre)links, buyersODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · registro de fundos (cvm-fidc-base)buyersODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · formulário cadastral (cvm-hist-fca)comparables, events, linksODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · cadastros de companhias e de fundos e carteiras de fundos (cvm-cadastros, cvm-cda-recente, cvm-hist-cda)funds, sectorsODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · fatos relevantes (cvm-hist-ipe) e informe mensal dos FIDCs (cvm-fidc)credit, eventsODbLFonte: CVM, Portal de Dados Abertos (ODbL)
CVM · informes mensais dos FII, informes dos FIP e cadastro de administradores de FII (cvm-fii-mensal, cvm-fip-trimestral, cvm-fip-quadrimestral, cvm-fii-administradores)fundsODbLFonte: CVM, Portal de Dados Abertos (ODbL)
ANEEL · indicadores comerciais das distribuidoras (aneel-fiscalizacao)profilesODbLa frase de attribution da resposta
ANS · IDSS das operadoras (ans-qualidade)profilesCC BYa frase de attribution da resposta
ANEEL · SAMP (aneel-samp) e Banco Central · IF.data (bcb-ifdata)sectors, financialsODbLa frase de attribution da resposta
SUSEP · SES (susep-ses), ANS · beneficiários (ans-beneficiarios) e Anatel · acessos (anatel-acessos)sectorsCC BYa frase de attribution da resposta
Anvisa · registros de cosméticos, saneantes e produtos para saúde (anvisa-produtos)prospectingCC BYa frase de attribution da resposta
ANP · concessionários de exploração e produção (anp-concessionarios)assetsCC BYa frase de attribution da resposta
Receita Federal · CNPJ (rfb-cnpj)companies, credit, profiles, prospecting, links, buyersCC BYa frase de attribution da resposta

A licença exata e a frase de atribuição de cada resposta vêm no campo sources; esta tabela é só um resumo. Uma fonte sem licença conhecida não sai pela API. A chave pode ser suspensa se o uso quebrar a licença de uma fonte.

O que a API não entrega

A especificação OpenAPI desta API externa ainda não existe. A mesma chave serve ao conector MCP e à CLI, descritos em tickerlab.com.br. Os dados vêm das fontes oficiais e podem ter atraso ou erro da própria fonte. Nada aqui é recomendação de investimento.