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
| Rota | O que devolve | Parâmetros |
|---|---|---|
GET /companies | Busca 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 prospecting | cnae, 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}/financials | DFP e ITR da CVM: um valor por conta e período, com documento, versão e origem | known_at, period_end |
GET /companies/{cnpj}/profile | O 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 empresa | known_at |
GET /companies/{cnpj}/comparables | Os 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 DFP | known_at |
GET /companies/{cnpj}/events | Os 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_cursor | known_at, types, cursor |
GET /companies/{cnpj}/links | Os 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}/assets | Os 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 assets | known_at |
GET /buyers | Quem 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 buyers | cnae, 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 anos | known_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édito | known_at |
GET /sectors | Os setores que a API entrega hoje, com o dia da conta mais nova. Não gasta cota | nenhum |
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ó empresas | known_at |
GET /sectors/{key}/deck | O 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 pedido | known_at |
GET /companies/{cnpj}/deck | O 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 pedido | known_at |
POST /companies/batch | O mesmo de /companies/{cnpj} para até 100 CNPJs | corpo: cnpjs, known_at |
POST /funds/batch | O mesmo de /funds/{cnpj} para até 100 CNPJs | corpo: cnpjs, known_at, assumed_return |
POST /credit/batch | O mesmo de /credit/{cnpj} para até 100 CNPJs | corpo: cnpjs, known_at |
GET /catalog | O que a sua chave pode pedir hoje | nenhum |
GET /usage | Seu consumo do mês, limites do plano e o que falta da cota | nenhum |
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
| Status | Código | O que fazer |
|---|---|---|
| 400 | api_key_in_url | Mande a chave no cabeçalho e troque a chave: ela já passou pela URL. |
| 400 | invalid_cnpj, invalid_known_at, invalid_assumed_return | Corrija o parâmetro (assumed_return maior que -1 e até 1). |
| 401 | invalid_api_key | Chave errada, vencida ou sem contrato. A resposta não diz qual. |
| 404 | not_available | O 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. |
| 429 | rate_limited, monthly_quota_exceeded | Espere o tempo do cabeçalho Retry-After (segundos). |
| 503 | service_unavailable | A 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
| Fonte | Conjunto | Licença | Como citar |
|---|---|---|---|
CVM · DFP e ITR (cvm-hist-dfp, cvm-hist-itr) | financials, profiles, comparables | ODbL | Fonte: CVM, Portal de Dados Abertos (ODbL) |
CVM · formulário de referência, controladas e coligadas (cvm-hist-fre) | links, buyers | ODbL | Fonte: CVM, Portal de Dados Abertos (ODbL) |
CVM · registro de fundos (cvm-fidc-base) | buyers | ODbL | Fonte: CVM, Portal de Dados Abertos (ODbL) |
CVM · formulário cadastral (cvm-hist-fca) | comparables, events, links | ODbL | Fonte: 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, sectors | ODbL | Fonte: CVM, Portal de Dados Abertos (ODbL) |
CVM · fatos relevantes (cvm-hist-ipe) e informe mensal dos FIDCs (cvm-fidc) | credit, events | ODbL | Fonte: 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) | funds | ODbL | Fonte: CVM, Portal de Dados Abertos (ODbL) |
ANEEL · indicadores comerciais das distribuidoras (aneel-fiscalizacao) | profiles | ODbL | a frase de attribution da resposta |
ANS · IDSS das operadoras (ans-qualidade) | profiles | CC BY | a frase de attribution da resposta |
ANEEL · SAMP (aneel-samp) e Banco Central · IF.data (bcb-ifdata) | sectors, financials | ODbL | a frase de attribution da resposta |
SUSEP · SES (susep-ses), ANS · beneficiários (ans-beneficiarios) e Anatel · acessos (anatel-acessos) | sectors | CC BY | a frase de attribution da resposta |
Anvisa · registros de cosméticos, saneantes e produtos para saúde (anvisa-produtos) | prospecting | CC BY | a frase de attribution da resposta |
ANP · concessionários de exploração e produção (anp-concessionarios) | assets | CC BY | a frase de attribution da resposta |
Receita Federal · CNPJ (rfb-cnpj) | companies, credit, profiles, prospecting, links, buyers | CC BY | a 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
- Preços e índices da B3: não há dado aberto, só com licença da B3.
- Dado de pessoa física: nem de sócio, nem de dívida; empresário individual e MEI não saem.
- Tabelas cuja fonte não autoriza redistribuir.
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.