Como puxar cotação da B3 com API: guia prático da brapi.dev

Se você está montando um app com gráfico de ação, um painel de carteira ou um backtest em cima da B3, o problema não é achar o preço de PETR4 no Google. O problema é ter cotação, série histórica, dividendos e fundamentos num JSON estável, com ticker brasileiro, sem parsear HTML que muda toda semana.

A brapi.dev é uma API REST pensada pra isso: dados do mercado financeiro brasileiro pra plugar em app, planilha, dashboard ou script. A documentação descreve cotações, histórico OHLCV, dividendos detalhados e fundamentos a partir de fontes públicas como CVM, Banco Central e Tesouro Direto. Este guia cobre o caminho prático, o que puxar em cada endpoint e o que não misturar com conselho de investimento.

O que uma API da B3 precisa resolver

Cotação de bolsa no Brasil não é só último preço. O ticker vem com sufixo (PETR4, VALE3, MXRF11), o provento mistura dividendo e JCP, e o fundamento mora em demonstração entregue à CVM, não num card de corretora.

Uma API útil pra produto precisa de quatro blocos:

• Preço e variação do dia, volume, máxima, mínima e valor de mercado
• Série histórica OHLCV (open, high, low, close, volume) pra gráfico e backtest
• Dividendos, JCP e as datas com, ex e pagamento
• Fundamentos: cadastro da empresa, múltiplos, receita, EBITDA, balanço, DRE e fluxo de caixa

A brapi cobre ativos listados na B3: ações, FIIs, BDRs, ETFs, units e índices como o Ibovespa. Também existem endpoints de câmbio, cripto, inflação (IPCA, IGP-M) e Selic histórica. Se o seu produto é bolsa, comece pelas ações e só depois abra o resto.

Para integrações novas, a documentação pede os endpoints /api/v2/stocks/*: um tipo de dado por chamada, resposta menor. O legado /api/quote/{tickers} continua funcionando, sem data de remoção, e ainda junta cotação, histórico, dividendos e módulos numa resposta só. Essa resposta fica grande e mistura dado que muda a cada minuto com dado que muda a cada trimestre. Se você está começando agora, prefira o v2.

Primeira cotação: um curl e o JSON

Quatro tickers respondem sem token e com todos os recursos: PETR4, MGLU3, VALE3 e ITUB4. Se você misturar um desses com qualquer outro ticker na mesma requisição, a chamada inteira passa a exigir autenticação.

No terminal, o exemplo da documentação é este: curl https://brapi.dev/api/quote/PETR4.

A resposta vem em JSON, com um item em results. Sem parâmetros extras, você já recebe symbol, shortName, currency, regularMarketPrice, regularMarketChange, regularMarketChangePercent, regularMarketVolume, regularMarketDayHigh, regularMarketDayLow, fiftyTwoWeekHigh, fiftyTwoWeekLow e marketCap. Dá pra montar o card de cotação do app com isso: preço, variação do dia, volume e range de 52 semanas.

O equivalente v2, também documentado pra teste sem token, é GET /api/v2/stocks/quote?symbols=PETR4. Em produção, mande o token no header Authorization: Bearer SEU_TOKEN (ou no query token, se a ferramenta não aceitar header). O token sai do dashboard da brapi, na seção de chaves de API, depois do login.

Não coloque o token no frontend público. Cacheie a cotação no seu backend, respeite o intervalo de atualização do plano e trate 429 (limite estourado), 401 (sem autorização) e 404 (ticker inexistente) como estados de produto, não como crash da tela. Lista e busca de ativos ficam em /api/quote/list: use isso no autocomplete, não num scrape de página de corretora.

Histórico OHLCV pra gráfico e backtest

Gráfico de candlestick e backtest pedem série, não snapshot. No legado, isso entra quando você passa range e interval: a resposta ganha historicalDataPrice.

interval aceita 1d, 5d, 1wk, 1mo e 3mo. range aceita 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd e max. O quanto de histórico você enxerga depende do plano. Também dá pra recortar com startDate e endDate.

No v2, o endpoint dedicado é /api/v2/stocks/historical, com os mesmos symbols, range e interval. A série traz OHLCV, volume e preço ajustado: insumo de gráfico, backtest de regra simples e indicador calculado no seu lado. Você pede a barra. Você não pede um sinal de compra.

Dois cuidados de produto. Primeiro: o plano gratuito documenta histórico dos últimos 3 meses, 1 ativo por requisição, 15 mil chamadas no mês e atualização a cada 30 minutos. Planos pagos aumentam volume, quantidade de tickers por chamada, frequência (a documentação cita 15 minutos no Startup e 5 minutos no Pro) e profundidade (o Pro fala em mais de 10 anos de cotação). Confira o limite atual na página de planos, porque o recorte muda o que o backtest consegue ver. Segundo: OHLCV de pregão não é dado de ordem a mercado. Dá pra simular estratégia no seu código. Não dá pra fingir que você está executando na B3.

Se o gráfico é o coração do app, chame histórico só quando a tela precisa e grave a série se o usuário volta todo dia no mesmo ticker. Repetir max a cada refresh é o jeito mais rápido de queimar cota.

Dividendos, JCP e fundamentos da CVM

Provento brasileiro não cabe num campo único chamado dividend. Tem dividendo, JCP, bonificação e, no pacote da brapi, também subscrição. No legado, dividends=true devolve dividendsData. No v2, o endpoint é /api/v2/stocks/dividends. A documentação destaca datas com, ex e pagamento: o mínimo pra calendário de proventos, tela de rendimento e conferência de posição. Isso alimenta produto. Não alimenta promessa de renda.

Fundamento é outro contrato. A brapi amarra isso aos documentos que as companhias entregam à CVM, sem você baixar PDF e parsear tabela. No legado, o parâmetro modules pede o bloco:

• summaryProfile: cadastro (CNPJ, setor, descrição, site, funcionários)
• defaultKeyStatistics: múltiplos em 12 meses (P/L, P/VP, ROE, dividend yield)
• financialData: receita, EBITDA, margens e dívida em 12 meses
• balanceSheetHistory, incomeStatementHistory, cashflowHistory, valueAddedHistory: balanço, DRE, fluxo de caixa e DVA anuais

Cada histórico tem a versão trimestral com sufixo Quarterly. defaultKeyStatistics e financialData também aceitam History e HistoryQuarterly.

No v2, isso vira endpoints separados: /api/v2/stocks/profile, /api/v2/stocks/statistics, /api/v2/stocks/financial-data e as demonstrações (balanço, DRE, DFC, DVA). O financial-data resume receita, lucro, EBITDA, margens, dívida líquida, caixa e fluxo de caixa livre. O padrão mode=current traz os últimos doze meses. Com mode=history você recebe a série, escolhendo period=annual ou period=quarterly, e recorta com startDate e endDate.

Use isso pra tela de empresa, comparativo de múltiplos ou filtro de universo. Não use pra empurrar ordem de compra. A própria brapi classifica o dado como informativo, vindo de fonte pública, sem orientação de compra ou venda. Trate o JSON do mesmo jeito no seu produto: número na tela, nunca texto do tipo "está barato".

Como encaixar no app (e o que não fazer)

O fluxo mínimo de um produto de mercado no Brasil costuma ser este:

• Buscar o ticker em /api/quote/list
• Mostrar o snapshot em /api/v2/stocks/quote (ou no legado /api/quote/{tickers})
• Desenhar o gráfico com /api/v2/stocks/historical
• Listar proventos com /api/v2/stocks/dividends
• Abrir o fundamental só na tela de detalhe (profile, statistics e financial-data)

A API REST fala qualquer linguagem. A documentação traz exemplos em JavaScript, TypeScript, Python, Java e Go. Há ainda MCP pra consultar o mercado a partir de assistentes como Cursor, Claude e VS Code, se o seu fluxo for agente e não só HTTP.

Cuidados que evitam incidente:

• Token só no servidor
• Um tipo de dado por chamada no v2, a menos que você realmente queira o payload misturado do legado
• Cache alinhado à frequência do plano
• PETR4 de teste não é o universo da B3: em produção, autentique
• Trate o JSON como dado de mercado, não como recomendação

A brapi.dev publica planos com volume, atualização e profundidade diferentes. O gratuito serve pra protótipo e o primeiro gráfico. App em produção com vários tickers e histórico longo precisa olhar o dashboard e o limite do plano, não chutar. Este texto descreve como puxar dado pra software. Não é análise, carteira sugerida nem sinal.

Quem está no mapa do Os 27 ou no histórico de ocupações já está pedindo visita ao site. Se o produto é API de bolsa, a visita tem que cair na documentação e num curl que responde. Abra a brapi.dev, rode o curl de PETR4 e só então desenhe a tela. Cotação, OHLCV, dividendo e fundamento são contratos diferentes. Trate cada um como tal.