# Google Sheets
URL: /docs/examples/google-sheets.mdx

Aprenda a buscar cotações automáticas da B3 no Google Sheets usando a API brapi.dev. Inclui função personalizada em Apps Script para obter dados de ações e ETFs que não aparecem no Google Finance.

***

title: 'Google Sheets'
description: >-
Aprenda a buscar cotações automáticas da B3 no Google Sheets usando a API
brapi.dev. Inclui função personalizada em Apps Script para obter dados de
ações e ETFs que não aparecem no Google Finance.
full: false
keywords:
brapi, api, google sheets, planilha, cotações, ETFs, apps script, IMAB11,
WRLD11, automação
openGraph:
title: Integração com Google Sheets - brapi.dev
description: >-
Busque cotações automáticas da B3 no Google Sheets com a API brapi.dev.
Solução para ETFs brasileiros que não aparecem no Google Finance.
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
-----------

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

1. Acesse [brapi.dev](https://brapi.dev)
2. Crie uma conta gratuita
3. No painel de usuário, copie seu **token API**

### 2. Adicione a função personalizada

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

```javascript
/**
 * 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";
}
```

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

### 3. Use a função na 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)
```

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:

```javascript
/**
 * 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

1. **Economize requisições**: Evite usar a função em células que são recalculadas constantemente
2. **Cache de dados**: Para grandes planilhas, considere atualizar dados periodicamente e não em tempo real
3. **Limite de requisições**: O plano gratuito oferece 15.000 requisições/mês - monitore seu uso no painel
4. **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.

## Próximos Passos

* Explore outros [exemplos de integração](/docs/examples)
* Consulte a [documentação da API](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)