Como usar a API pública do Capital Agora em planilha ou sistema
Os endpoints disponíveis, o formato das respostas, os limites de uso e exemplos práticos de integração em planilha, painel ou aplicação.
Tudo o que o site mostra em HTML também sai em JSON, sem chave de acesso e sem cadastro. Este guia mostra como consumir os endpoints e quais cuidados tomar para não ser bloqueado por excesso de requisições.
1. Escolha o endpoint certo
Para um papel específico, use /api/ativo/{ticker}: devolve preço, variações,
faixa de 52 semanas, múltiplos e a data do balanço usado. Para listas, /api/acoes e
/api/fiis. Para séries econômicas, /api/indicador/{slug}. Para manchetes,
/api/noticias.
A documentação completa, com exemplo de resposta, está em /api.
2. Monte a requisição sem autenticação
Basta um GET na URL. Não há chave, token nem cabeçalho obrigatório. A resposta vem em JSON
com Content-Type: application/json; charset=utf-8 e datas no formato ISO (AAAA-MM-DD).
Em planilha, a função de importação de dados da web resolve: aponte para a URL do endpoint e trate o JSON retornado.
3. Respeite o cache e o limite por minuto
O limite é de 240 requisições por minuto por IP no site inteiro. Ao ultrapassar, a resposta vem com status 429 até o minuto virar.
Como os dados de origem mudam uma vez por pregão (cotações) ou uma vez por dia ou mês (indicadores),
consultar em intervalo curto não traz informação nova. Respeite o Cache-Control devolvido
em cada resposta.
4. Trate ausência de dado como ausência
Campos sem informação voltam null, nunca zero. Um P/L nulo significa que a
empresa teve prejuízo ou que falta o número de ações na última demonstração — tratar isso como zero
estraga qualquer ranking ou gráfico.
5. Cite a origem ao publicar
Se os números forem exibidos em outro site ou produto, cite o Capital Agora com link e a fonte primária correspondente: B3, CVM, Banco Central ou Tesouro Nacional. É o único pedido que fazemos em troca do uso livre.
Exemplos de uso
Planilha de carteira: uma linha por papel, puxando /api/ativo/{ticker}
uma vez por dia depois do fechamento. Basta guardar o campo preco e o
indicadores.dy_12m.
Painel de indicadores: /api/indicadores devolve o último valor de todas as
séries de uma vez — Selic, CDI, IPCA, IGP-M, dólar, euro e as demais.
Monitor de notícias por ativo: /api/noticias?ticker=PETR4 traz as
manchetes que citam aquele papel, com veículo, horário e link para a origem.
O que a API não faz
Não há preço intradiário — todos os valores são de fechamento, porque o dado de origem é o arquivo publicado pela B3 após o pregão. Também não há endpoint de carga completa: para séries históricas extensas, baixe direto dos arquivos abertos da B3, da CVM, do Banco Central e do Tesouro Nacional.
Um exemplo completo de integração
Imagine uma planilha com dez papéis. Uma requisição por papel a /api/ativo/{ticker}, uma
vez por dia após o fechamento, resolve preço, variação e dividend yield. São dez chamadas diárias — muito
abaixo do limite de 240 por minuto, e com folga para reprocessar em caso de erro.
Se a planilha precisar também de contexto macro, uma chamada a /api/indicadores traz Selic,
CDI, IPCA, IGP-M, dólar e euro de uma vez. Onze requisições no total, uma vez por dia. Esse é o padrão de
uso para o qual a API foi feita.
Para um painel que atualiza sozinho, guarde a resposta localmente com o tempo indicado no cabeçalho
Cache-Control e só refaça a chamada quando ele expirar. Isso reduz a latência do seu painel e
preserva o serviço para todo mundo.
Erros que você pode receber
404 significa papel não encontrado ou sem negociação regular — a resposta traz a
explicação no campo erro. 429 significa limite de requisições excedido:
espere e repita com intervalo crescente, sem insistir em laço. Qualquer resposta com status 200 traz o
JSON completo, e campos sem dado vêm como null.
Não há status 500 previsto em operação normal; se aparecer, é falha temporária do servidor e a requisição pode ser repetida depois de alguns segundos.
Perguntas frequentes
A API é mesmo gratuita?
É, sem cadastro e sem chave. O controle é feito por limite de requisições por IP, o que protege o serviço sem burocracia para quem usa com moderação.
Posso usar em produto comercial?
Pode, respeitando o limite de requisições e citando a origem com link. Para volume alto, escreva antes pelo contato.
Qual o intervalo recomendado entre chamadas?
Uma vez por dia para cotações, depois do fechamento do pregão; uma vez por dia para indicadores diários; uma vez por mês para índices mensais. Consultar em intervalo menor não traz dado novo, porque a origem não mudou.
Consigo o histórico completo de um indicador?
Sim, com o parâmetro limite no endpoint de indicador. Para séries muito longas, prefira baixar direto do Sistema Gerenciador de Séries Temporais do Banco Central, que é a fonte primária e não tem limite de requisição por minuto.
A API funciona em planilha?
Funciona. Qualquer planilha que importe JSON de uma URL consome os endpoints diretamente, sem autenticação. Basta apontar para o endereço do endpoint e mapear os campos que interessam.
Existe versionamento?
Os campos existentes são mantidos; novos campos podem ser acrescentados. Escreva seu código para ignorar campos desconhecidos e nada quebra.