Google Sheets | Documentação brapi.dev

O Google Sheets é uma ferramenta poderosa para acompanhar seus investimentos de forma automática. Através do Google Apps Script, você pode criar uma função personalizada que busca cotações diretamente da brapi.dev.

Por que usar a brapi.dev no Google Sheets?

A função GOOGLEFINANCE não funciona para muitos ativos brasileiros, especialmente ETFs como IMAB11, WRLD11, IB5M11 e IRFM11. A integração com a brapi.dev resolve esse problema, oferecendo:

Dados confiáveis: Acesso direto aos dados da B3
ETFs brasileiros: Funciona com todos os ativos negociados na B3
Atualização automática: Cotações atualizadas conforme seu plano
Uso gratuito: 15.000 requisições mensais no plano gratuito

Passo a Passo

1. Obtenha sua chave API

Acesse brapi.dev
Crie uma conta gratuita
No painel de usuário, copie seu token API

2. Adicione a função personalizada

Abra sua planilha no Google Sheets
Clique em Extensões > Apps Script
Apague o código existente e cole o código abaixo:

/**
 * Retorna o preço atual de um ticker da B3 via brapi.dev
 * Uso: =BRAPI_PRICE("PETR4"; $A$1)
 * @param {string} ticker - Código do ativo (ex: "PETR4", "VALE3", "IMAB11")
 * @param {string} token - Token da API brapi.dev
 * @return {number} Preço atual do ativo
 */
function BRAPI_PRICE(ticker, token) {
  if (!ticker) return "Erro: informe ticker";
  
  // Permite passar o token como célula ou string
  if (token && typeof token === 'object' && token.length) {
    token = token[0][0];
  }
  
  // Se não informar token, tenta pegar da célula A1
  if (!token) {
    var sh = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
    token = sh.getRange('A1').getDisplayValue();
  }
  
  if (!token) return "Erro: token brapi.dev ausente";
  
  // Formata o ticker
  ticker = String(ticker).toUpperCase().trim();
  if (ticker.indexOf('.') === -1) ticker = ticker + '.SA';
  
  // Faz a requisição
  var url = 'https://brapi.dev/api/quote/' + encodeURIComponent(ticker) + 
            '?token=' + encodeURIComponent(token);
  
  var options = {
    muteHttpExceptions: true,
    headers: {'User-Agent': 'Mozilla/5.0'}
  };
  
  var response = UrlFetchApp.fetch(url, options);
  
  if (response.getResponseCode() !== 200) {
    return "HTTP " + response.getResponseCode() + ": " + 
           response.getContentText().substring(0, 200);
  }
  
  var json = JSON.parse(response.getContentText());
  var result = (json && json.results && json.results[0]) || null;
  
  if (!result) return "Sem dados retornados";
  
  return result.regularMarketPrice || result.lastPrice || 
         result.close || "Preço não encontrado";
}

Salve o projeto (Ctrl + S ou clique no ícone de disquete)
Feche a janela do editor

3. Use a função na sua planilha

Na célula A1, cole seu token da API brapi.dev
Em qualquer outra célula, use a fórmula:

=BRAPI_PRICE("PETR4"; $A$1)

A referência $A$1 garante que o endereço da célula do token não mude ao arrastar a fórmula.

Exemplos de Uso

Ações

=BRAPI_PRICE("PETR4"; $A$1)    # Petrobras PN
=BRAPI_PRICE("VALE3"; $A$1)    # Vale ON
=BRAPI_PRICE("ITUB4"; $A$1)    # Itaú Unibanco PN
=BRAPI_PRICE("BBDC4"; $A$1)    # Bradesco PN

ETFs de Renda Fixa

=BRAPI_PRICE("IMAB11"; $A$1)   # ETF IMA-B
=BRAPI_PRICE("IB5M11"; $A$1)   # ETF IMA-B 5+
=BRAPI_PRICE("IRFM11"; $A$1)   # ETF IRF-M
=BRAPI_PRICE("B5P211"; $A$1)   # ETF NTN-B Principal

ETFs Internacionais

=BRAPI_PRICE("WRLD11"; $A$1)   # ETF Global
=BRAPI_PRICE("IVVB11"; $A$1)   # ETF S&P 500
=BRAPI_PRICE("NASD11"; $A$1)   # ETF Nasdaq

Índices

=BRAPI_PRICE("^BVSP"; $A$1)    # Índice Ibovespa

Função Avançada: Múltiplos Dados

Se você quiser buscar mais informações além do preço, pode criar uma função mais completa:

/**
 * Retorna dados completos de um ativo
 * Uso: =BRAPI_DATA("PETR4"; $A$1; "symbol")
 * @param {string} ticker - Código do ativo
 * @param {string} token - Token da API
 * @param {string} field - Campo desejado (regularMarketPrice, currency, shortName, etc)
 * @return {any} Valor do campo solicitado
 */
function BRAPI_DATA(ticker, token, field) {
  if (!ticker) return "Erro: informe ticker";
  if (!field) return "Erro: informe campo";
  
  if (token && typeof token === 'object' && token.length) {
    token = token[0][0];
  }
  
  if (!token) {
    var sh = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
    token = sh.getRange('A1').getDisplayValue();
  }
  
  if (!token) return "Erro: token ausente";
  
  ticker = String(ticker).toUpperCase().trim();
  if (ticker.indexOf('.') === -1) ticker = ticker + '.SA';
  
  var url = 'https://brapi.dev/api/quote/' + encodeURIComponent(ticker) + 
            '?token=' + encodeURIComponent(token);
  
  var options = {
    muteHttpExceptions: true,
    headers: {'User-Agent': 'Mozilla/5.0'}
  };
  
  var response = UrlFetchApp.fetch(url, options);
  
  if (response.getResponseCode() !== 200) {
    return "Erro HTTP " + response.getResponseCode();
  }
  
  var json = JSON.parse(response.getContentText());
  var result = (json && json.results && json.results[0]) || null;
  
  if (!result) return "Sem dados";
  
  return result[field] || "Campo não encontrado";
}

Exemplos de uso:

=BRAPI_DATA("PETR4"; $A$1; "regularMarketPrice")  # Preço
=BRAPI_DATA("PETR4"; $A$1; "currency")            # Moeda
=BRAPI_DATA("PETR4"; $A$1; "shortName")           # Nome curto
=BRAPI_DATA("PETR4"; $A$1; "regularMarketChange") # Variação do dia
=BRAPI_DATA("PETR4"; $A$1; "marketCap")           # Valor de mercado

Dicas de Uso

Economize requisições: Evite usar a função em células que são recalculadas constantemente
Cache de dados: Para grandes planilhas, considere atualizar dados periodicamente e não em tempo real
Limite de requisições: O plano gratuito oferece 15.000 requisições/mês - monitore seu uso no painel
Erros de quota: Se exceder o limite, a API retornará erro HTTP 429

Monitoramento de Uso

Para uma ideia de consumo, uma planilha com 30 ativos diferentes, atualizada 3x ao dia, consome aproximadamente 2.700 requisições por mês (30 ativos × 3 atualizações × 30 dias), bem abaixo do limite gratuito.

Solução de Problemas

"Erro: token ausente"

Verifique se o token está na célula A1 ou se está sendo passado corretamente como parâmetro.

"HTTP 401"

Token inválido. Verifique se copiou o token completo do painel da brapi.dev.

"HTTP 429"

Limite de requisições excedido. Aguarde o próximo ciclo de faturamento ou considere o plano pago.

"Sem dados retornados"

Ticker inválido ou ativo não encontrado. Verifique o código do ativo.