Como Integrar Cotações da B3 no Google Sheets: O Guia Definitivo

Descubra como criar uma planilha inteligente que atualiza automaticamente as cotações de ações e ETFs da B3, incluindo aqueles que não aparecem no Google Finance.

O Problema que Todo Investidor Enfrenta

Se você usa o Google Sheets para acompanhar seus investimentos, já deve ter se deparado com esse problema frustrante: muitos ETFs brasileiros simplesmente não aparecem na função GOOGLEFINANCE.

Ativos como WRLD11, IMAB11, IB5M11 e IRFM11 - fundamentais para uma carteira diversificada - ficam de fora. Você tenta usar =GOOGLEFINANCE("BVMF:IMAB11") e recebe apenas um erro. A solução? Atualizar manualmente. Todos. Os. Dias.

Mas e se existisse uma forma de automatizar isso completamente?

A Solução: Função Personalizada com Apps Script

Vamos criar uma função personalizada chamada BRAPI_PRICE() que busca cotações diretamente da API da brapi.dev. O melhor? É tão simples de usar quanto a função GOOGLEFINANCE:

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

Por Que Esta Solução é Melhor?

1. Funciona com todos os ativos da B3 - Ações, ETFs, FIIs, BDRs e índices
2. Dados confiáveis - Acesso direto aos dados oficiais da B3
3. Gratuito - 15.000 requisições mensais sem custo
4. Fácil de usar - Sintaxe simples e familiar
5. Atualização automática - Configure e esqueça

Passo a Passo: Implementação Completa

Passo 1: Obtenha Seu Token da API

1. Acesse brapi.dev
2. Crie uma conta gratuita (leva menos de 1 minuto)
3. No painel de usuário, copie seu token API

Importante: Guarde esse token - você vai precisar dele na planilha.

Passo 2: Adicione o Código no Apps Script

1. Abra sua planilha no Google Sheets
2. Clique em Extensões > Apps Script
3. Apague todo o código que aparecer
4. Cole o código abaixo:

/**
 * Retorna o preço atual de um ticker da B3 via brapi.dev
 * 
 * @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
 * @customfunction
 */
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";
}

5. Clique em Salvar (ícone de disquete ou Ctrl+S)
6. Dê um nome ao projeto (ex: "Cotações brapi")
7. Feche a janela do editor

Passo 3: Configure Sua Planilha

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

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

Pronto! A cotação aparecerá automaticamente. 🎉

Exemplos Práticos de Uso

Ações Populares

=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
=BRAPI_PRICE("MGLU3"; $A$1)    # Magazine Luiza ON

ETFs de Renda Fixa (O Grande Diferencial!)

Estes ETFs não funcionam no Google Finance, mas funcionam perfeitamente com nossa função:

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

ETFs Internacionais

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

Índices e BDRs

=BRAPI_PRICE("^BVSP"; $A$1)    # Índice Ibovespa
=BRAPI_PRICE("AAPL34"; $A$1)   # BDR Apple
=BRAPI_PRICE("MSFT34"; $A$1)   # BDR Microsoft

Função Avançada: Busque Qualquer Dado

Se você quiser mais do que apenas o preço, use esta função avançada:

/**
 * Retorna dados completos de um ativo
 * 
 * @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
 * @customfunction
 */
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 com BRAPI_DATA:

=BRAPI_DATA("PETR4"; $A$1; "regularMarketPrice")      # Preço
=BRAPI_DATA("PETR4"; $A$1; "shortName")               # Nome
=BRAPI_DATA("PETR4"; $A$1; "currency")                # Moeda
=BRAPI_DATA("PETR4"; $A$1; "regularMarketChange")     # Variação R$
=BRAPI_DATA("PETR4"; $A$1; "regularMarketChangePercent") # Variação %
=BRAPI_DATA("PETR4"; $A$1; "marketCap")               # Valor de mercado
=BRAPI_DATA("PETR4"; $A$1; "regularMarketVolume")     # Volume negociado

Criando Uma Planilha Profissional

Aqui está um exemplo de como estruturar sua planilha:

Dica Pro: Formate a coluna E com cores condicionais:

• Verde se > 0
• Vermelho se < 0

Consumo de API: Você Está Seguro

Uma dúvida comum: "Vou estourar meu limite de 15.000 requisições?"

Resposta curta: Provavelmente não.

Exemplo real: Uma planilha com 30 ativos diferentes, atualizada 3 vezes por dia durante 30 dias:

• Cálculo: 30 ativos × 3 atualizações × 30 dias = 2.700 requisições/mês
• Isso é apenas 18% do limite gratuito!

Dicas para Economizar Requisições

1. Evite referências circulares - Não use a função em células que recalculam automaticamente
2. Use atualização manual - Configure "Cálculo: Manual" nas configurações da planilha
3. Cache de dados - Para planilhas grandes, atualize uma vez por dia
4. Monitore seu uso - Acesse o painel da brapi.dev para ver quantas requisições você fez

Troubleshooting: Soluções para Problemas Comuns

Erro: "token ausente"

Solução: Verifique se o token está na célula A1 ou sendo passado corretamente na fórmula.

Erro: "HTTP 401"

Solução: Token inválido. Copie novamente do painel da brapi.dev.

Erro: "HTTP 429"

Solução: Limite de requisições excedido. Aguarde o próximo mês ou considere o plano pago.

Erro: "Sem dados retornados"

Solução: Ticker inválido. Verifique o código correto do ativo na B3.

A função não atualiza automaticamente

Solução:

1. Configure a planilha para recalcular automaticamente
2. Ou adicione uma célula com =NOW() para forçar recálculo
3. Ou pressione Ctrl+Alt+Shift+F9 para recalcular tudo

Cotação desatualizada

Solução: O plano gratuito tem delay de ~15 minutos. Para tempo real, considere o plano pago.

Casos de Uso Avançados

1. Acompanhamento de Carteira

Crie uma planilha que calcula automaticamente:

• Valor total investido
• Valor atual da carteira
• Rentabilidade por ativo
• Rentabilidade total
• Distribuição percentual

2. Alertas de Preço

Use formatação condicional para destacar quando:

• Ação cai mais de 5% no dia
• Ação atinge preço-alvo
• Volume está acima da média

3. Histórico de Preços

Crie um script que salva os preços diariamente em uma aba separada para análise histórica.

4. Rebalanceamento Automático

Configure fórmulas que calculam quanto comprar/vender de cada ativo para manter sua alocação desejada.

Comparação: brapi.dev vs Google Finance

Próximos Passos

Agora que você tem sua planilha configurada, explore:

1. Documentação completa da API - Descubra todos os dados disponíveis
2. Exemplos em outras linguagens - Python, JavaScript, PHP e mais
3. Dashboard da brapi.dev - Monitore seu uso de API
4. Planos e preços - Considere upgrade para tempo real

Conclusão

Parabéns! Você acabou de criar uma planilha de investimentos profissional que:

✅ Atualiza cotações automaticamente
✅ Funciona com TODOS os ativos da B3
✅ Inclui ETFs que não aparecem no Google Finance
✅ É gratuita para até 15.000 requisições/mês
✅ Pode ser expandida com dados fundamentalistas

Essa solução transforma uma planilha simples em uma ferramenta poderosa de acompanhamento de investimentos, economizando horas de trabalho manual e garantindo dados sempre atualizados.

Ação agora: Abra seu Google Sheets e implemente essa solução. Em 5 minutos você terá cotações automáticas da B3!

Tem dúvidas ou sugestões? Entre em contato com nossa equipe de suporte ou compartilhe sua experiência nos comentários.

Gostou deste tutorial? Compartilhe com outros investidores que também lutam com planilhas desatualizadas!