Como Obter Taxas de Câmbio em Tempo Real no Google Sheets (GOOGLEFINANCE, Apps Script e uma API de Câmbio)

Obter taxas de câmbio em tempo real no Google Sheets parece um problema resolvido. Escreve =GOOGLEFINANCE("CURRENCY:USDEUR"), aparece um número e segue em frente. Isso funciona bem para um orçamento pessoal de viagem. Deixa de funcionar no momento em que a folha de cálculo alimenta uma fatura, um processamento salarial, um relatório de receitas ou qualquer coisa sobre a qual um colega vá agir — por causa de uma restrição de licença, uma peculiaridade documentada nas datas e uma limitação do Apps Script que quase nenhum tutorial menciona.

Este guia cobre os três métodos práticos — a função nativa GOOGLEFINANCE, uma função personalizada em Apps Script suportada por uma API de câmbio, e uma tabela de taxas agendada e atualizada por um acionador temporal — com os números reais das quotas, a formulação exata das ressalvas da própria Google e código pronto a executar. Todas as afirmações sobre o comportamento da Google abaixo são citadas da documentação da própria Google, e todas as afirmações que não são documentadas estão assinaladas como tal.

---

As Três Formas de Trazer Taxas de Câmbio para o Google Sheets

A maioria das pessoas deve começar pelo método 1 e passar para o método 3 no momento em que a folha se torna crítica.

---

Método 1: GOOGLEFINANCE — E Exatamente o Que a Google Diz Sobre Ele

A fórmula básica de câmbio

O padrão que todos os tutoriais ensinam é um ticker CURRENCY: composto por dois códigos de moeda ISO 4217 concatenados:

=GOOGLEFINANCE("CURRENCY:USDEUR")

Para converter um montante na célula A2:

=A2 * GOOGLEFINANCE("CURRENCY:USDEUR")

Para construir o par a partir de duas células com códigos de moeda:

=GOOGLEFINANCE("CURRENCY:" & B2 & C2)

Uma ressalva honesta que nenhum artigo concorrente faz: a forma de ticker CURRENCY:XXXYYY não aparece em lado nenhum da documentação oficial da Google sobre GOOGLEFINANCE. A assinatura documentada é GOOGLEFINANCE(ticker, [attribute], [start_date], [end_date|num_days], [interval]), e o único conteúdo sobre moedas na página de ajuda é um atributo "currency" (a moeda em que um título está cotado) e um exemplo de gráfico. A sintaxe de pares CURRENCY: funciona e funciona há anos, mas é um comportamento estabelecido pela comunidade, não um contrato documentado — o que significa que a Google é livre de a alterar sem aviso de descontinuação. A Google também não publica qualquer lista de pares de moedas suportados, pelo que qualquer artigo que lhe diga que suporta "cerca de 50 moedas" está a adivinhar.

Taxas históricas: a regra dos atributos que toda a gente erra

Passe uma data e obtém dados históricos:

=GOOGLEFINANCE("CURRENCY:USDEUR", "close", DATE(2026,1,15))

=GOOGLEFINANCE("CURRENCY:USDEUR", "close", DATE(2026,1,1), DATE(2026,1,31), "DAILY")

Repare no atributo. A Google documenta-o com clareza: "Se forem especificados quaisquer parâmetros de data, o pedido é considerado histórico e apenas os atributos históricos são permitidos." Os atributos históricos são open, close, high, low, volume e all — e "price" não está entre eles. "price" está documentado apenas como atributo em tempo real ("Cotação em tempo real, com um atraso de até 20 minutos").

Vá ver agora mesmo os tutoriais de moedas para Google Sheets mais bem posicionados: a maioria entrega-lhe GOOGLEFINANCE("CURRENCY:USDEUR", "price", DATE(...)). Essa combinação contradiz a própria documentação da Google. Use "close".

Mais dois comportamentos documentados que vale a pena interiorizar:

• "Se start_date for especificado mas end_date|num_days não, apenas são devolvidos os dados desse único dia."
• "Os resultados em tempo real são devolvidos como um valor dentro de uma única célula. Os dados históricos, mesmo para um único dia, são devolvidos como uma matriz expandida com cabeçalhos de coluna." É por isto que uma fórmula histórica que parece correta derrama duas colunas e uma linha de cabeçalho no seu layout arrumado, e porque normalmente precisa de a envolver em INDEX(...,2,2).

O desvio do meio-dia UTC

Este corrompe silenciosamente relatórios com correspondência por data. Palavra por palavra, da Google:

"A Google trata as datas passadas ao GOOGLEFINANCE como sendo meio-dia UTC. As bolsas que fecham antes dessa hora podem ficar desviadas em um dia."

Se está a reconciliar um livro-razão onde cada linha tem de usar a taxa da respetiva data de lançamento, um desvio de um dia é uma quebra de reconciliação real, não uma questão de arredondamento. Se isso descreve a sua folha, leia o nosso guia sobre taxas de câmbio e reporte fiscal antes de confiar numa matriz derramada do GOOGLEFINANCE como registo de auditoria.

O atraso é de 3 minutos, não 20

Quase todos os artigos sobre este tema lhe dizem que as taxas de câmbio do GOOGLEFINANCE têm "um atraso de até 20 minutos". Esse número de 20 minutos vem do aviso genérico sobre cotações de títulos associado ao atributo "price". A própria página de aviso legal do Google Finance publica uma tabela de atrasos por tipo de ativo, e a linha correspondente a Moeda — global, fornecida pela Morningstar — é de 3 minutos. As criptomoedas também têm 3 minutos.

Portanto os dados são mais frescos do que a internet acredita. O que a Google não publica é com que frequência o Sheets recalcula a fórmula, que é o número que realmente lhe interessa — uma taxa com 3 minutos numa célula que não recalcula desde terça-feira continua a ser uma taxa de terça-feira. Quem citar um intervalo de recálculo específico está a citar algo que a Google nunca documentou.

Para comparação, a Finexly atualiza as taxas a cada minuto e devolve-as a pedido, pelo que a frescura é função do momento em que você faz a chamada, e não do momento em que a folha de cálculo decide recalcular. Se quiser perceber o que significa "em tempo real" nos vários fornecedores em geral, veja onde é que as APIs de taxas de câmbio vão buscar os dados.

A restrição de utilização que ninguém cita

Este é o parágrafo mais importante deste artigo, e não aparece em nenhum dos tutoriais mais bem posicionados. Da página de ajuda da Google sobre GOOGLEFINANCE, palavra por palavra:

"Restrições de utilização: Os dados não se destinam a uso profissional no setor financeiro nem a uso por outros profissionais em empresas não financeiras (incluindo entidades governamentais). A utilização profissional pode estar sujeita a taxas de licenciamento adicionais de um fornecedor de dados terceiro."

E do aviso legal do Google Finance:

"Concorda em não copiar, modificar, reformatar, descarregar, armazenar, reproduzir, reprocessar, transmitir ou redistribuir quaisquer dados ou informações aqui encontrados, nem em utilizar tais dados ou informações num empreendimento comercial sem obter consentimento prévio por escrito."

"A Google não pode garantir a exatidão das taxas de câmbio apresentadas. Deve confirmar as taxas atuais antes de realizar quaisquer transações que possam ser afetadas por alterações nas taxas de câmbio."

Leia isso à luz do que a sua folha faz realmente. Definir o preço de uma fatura a um cliente, converter faturas de fornecedores para a equipa de contabilidade ou exportar um valor de receita convertido para um relatório que envia a um cliente não é obviamente "para fins informativos". Uma API de taxas de câmbio licenciada elimina a questão por completo, e é essa — e não a exatidão bruta — a verdadeira razão pela qual as equipas financeiras abandonam o GOOGLEFINANCE.

E o bloqueio insuperável

"Os dados históricos não podem ser descarregados nem acedidos através da API do Sheets ou do Apps Script. Se tentar fazê-lo, verá um erro #N/A no lugar dos valores nas células correspondentes da sua folha de cálculo."

No momento em que quiser automatizar seja o que for — uma exportação noturna, uma extração via API do Sheets, um script que capture taxas — os dados históricos do GOOGLEFINANCE estão fora de questão por desenho. É essa a parede que empurra as pessoas para o método 2.

---

Método 2: Uma Função Personalizada em Apps Script Suportada por uma API de Câmbio

Uma função personalizada é uma função JavaScript em Apps Script que se chama a partir de uma célula como qualquer função nativa. A Google confirma explicitamente que isto funciona com pedidos web: as funções personalizadas "só podem chamar serviços que não tenham acesso a dados pessoais", e o URL Fetch está na lista de permitidos.

Passo 1: Obter uma chave de API e guardá-la corretamente

Obtenha uma chave gratuita no painel da Finexly — 1.000 pedidos por mês, sem cartão de crédito. Depois, e isto é importante: não a coloque diretamente no código. Dois dos tutoriais de moedas para Google Sheets mais referenciados colam a chave de API diretamente no script, num ficheiro que viaja com a folha de cálculo para toda a gente com quem a partilhar.

No editor do Apps Script (Extensões → Apps Script), execute isto uma vez a partir do editor para guardar a chave nas Propriedades do Script:

function storeApiKey() {
  PropertiesService.getScriptProperties()
    .setProperty('FINEXLY_API_KEY', 'YOUR_API_KEY');
}

Apague o literal do ficheiro depois disso. Repare nos limites documentados: o valor de uma propriedade está limitado a 9 KB, e um repositório de propriedades a 500 KB no total — mais que suficiente para uma chave, mas não é sítio para colocar dados em cache.

Passo 2: Uma função personalizada para um único par

/**
 * Returns the live exchange rate for a currency pair.
 *
 * @param {string} from Base currency code, e.g. "USD".
 * @param {string} to Quote currency code, e.g. "EUR".
 * @return The exchange rate.
 * @customfunction
 */
function FX_RATE(from, to) {
  if (!from || !to) throw new Error('Both currency codes are required.');

  var pair = String(from).toUpperCase() + '_' + String(to).toUpperCase();
  var cache = CacheService.getScriptCache();
  var hit = cache.get(pair);
  if (hit !== null) return Number(hit);

  var key = PropertiesService.getScriptProperties().getProperty('FINEXLY_API_KEY');
  var res = UrlFetchApp.fetch(
    'https://api.finexly.com/v1/rate?from=' + encodeURIComponent(from) +
      '&to=' + encodeURIComponent(to),
    {
      headers: { Authorization: 'Bearer ' + key },
      muteHttpExceptions: true
    }
  );

  var code = res.getResponseCode();
  var body = JSON.parse(res.getContentText());
  if (code !== 200) {
    throw new Error(body.error ? body.error.code + ': ' + body.error.message : 'HTTP ' + code);
  }

  cache.put(pair, String(body.rate), 300); // 5 minutes
  return body.rate;
}

Use-a numa célula:

=FX_RATE("USD","EUR")
=A2 * FX_RATE($B$1, $C$1)

O endpoint /v1/rate devolve {"pair": "USD_EUR", "rate": 0.9215}. A referência completa de parâmetros está na documentação da API Finexly.

Passo 3: Processar o intervalo em lote — a parte que todos os concorrentes ignoram

Eis o modo de falha. A Google documenta-o diretamente:

"Sempre que uma função personalizada é usada numa folha de cálculo, o Sheets faz uma chamada separada ao servidor do Apps Script. Se a sua folha de cálculo contiver dezenas (ou centenas, ou milhares!) de chamadas a funções personalizadas, este processo pode ser lento."

Arraste FX_RATE por 400 linhas e terá feito 400 idas e voltas. Com um limite de 30 segundos por execução nas funções personalizadas, vai bater em #ERROR! com a nota Exceeded maximum execution time (line 0). muito antes de atingir a quota da sua API.

A solução que a Google recomenda é o processamento em lote com matrizes: aceitar um intervalo, devolver uma matriz. O endpoint /v1/convert da Finexly aceita pares separados por vírgulas, pelo que a coluna inteira passa a ser um pedido HTTP:

/**
 * Converts a column of amounts from one currency to another in a single API call.
 *
 * @param {A2:A400} amounts Range of amounts.
 * @param {string} from Base currency code.
 * @param {string} to Quote currency code.
 * @return {Array} Converted amounts.
 * @customfunction
 */
function FX_CONVERT_RANGE(amounts, from, to) {
  var rate = FX_RATE(from, to);           // one fetch, then cached
  var rows = Array.isArray(amounts) ? amounts : [[amounts]];
  return rows.map(function (row) {
    return row.map(function (v) {
      return (v === '' || v === null) ? '' : Number(v) * rate;
    });
  });
}

=FX_CONVERT_RANGE(A2:A400, "USD", "EUR")

Uma fórmula, uma chamada de rede, menos 399 idas e voltas. Se precisar de vários pares de uma só vez, chame /v1/convert?q=USD_EUR,USD_GBP,USD_JPY e leia body["USD_EUR"].rate.

O que a Google diz de facto sobre cache em funções personalizadas

O CacheService é usado acima, mas convém ser preciso quanto ao motivo. O guia de funções personalizadas da Google classifica o serviço Cache como "Funciona, mas não é particularmente útil em funções personalizadas." A vantagem do cache só é real entre execuções separadas — recálculos repetidos do mesmo par — e não dentro de uma única matriz derramada. O processamento em lote com matrizes é a otimização documentada; o cache é um complemento útil.

Os limites documentados do cache: chaves até 250 caracteres, valores até 100 KB, um teto de 1.000 itens, e uma expiração entre 1 segundo e 21.600 segundos (6 horas), com predefinição de 600 segundos. Não existe uma quota diária publicada para chamadas ao cache.

Mais uma armadilha documentada, porque a solução alternativa circula muito: acrescentar NOW() como argumento para forçar uma atualização quebra a função. A Google: "Os argumentos de funções personalizadas têm de ser determinísticos … Se uma função personalizada tentar devolver um valor com base numa destas funções nativas voláteis, apresenta Loading... indefinidamente."

---

Método 3: Uma Tabela de Taxas Agendada (O Padrão de Produção)

As funções personalizadas recalculam quando o Sheets bem entender, o que é exatamente a propriedade errada para uma folha que outra pessoa lê. O padrão robusto é deixar de ir buscar dados a partir das células por completo: escrever as taxas numa tabela de forma agendada e depois consultá-las com fórmulas simples.

O script de atualização

var PAIRS = ['USD_EUR', 'USD_GBP', 'USD_JPY', 'USD_CAD', 'USD_AUD', 'USD_CHF'];

function refreshRates() {
  var key = PropertiesService.getScriptProperties().getProperty('FINEXLY_API_KEY');
  var res = UrlFetchApp.fetch(
    'https://api.finexly.com/v1/convert?q=' + PAIRS.join(','),
    { headers: { Authorization: 'Bearer ' + key }, muteHttpExceptions: true }
  );

  if (res.getResponseCode() !== 200) {
    console.error('Finexly refresh failed: ' + res.getContentText());
    return; // keep yesterday's rates rather than blanking the sheet
  }

  var data = JSON.parse(res.getContentText());
  var stamp = new Date();
  var rows = PAIRS.map(function (p) {
    return [p, p.split('_')[0], p.split('_')[1], data[p].rate, stamp];
  });

  var sheet = SpreadsheetApp.getActive().getSheetByName('Rates') ||
              SpreadsheetApp.getActive().insertSheet('Rates');
  sheet.clear();
  sheet.getRange(1, 1, 1, 5)
       .setValues([['Pair', 'From', 'To', 'Rate', 'Updated (UTC)']])
       .setFontWeight('bold');
  sheet.getRange(2, 1, rows.length, 5).setValues(rows);
}

Dois detalhes que distinguem isto dos scripts que encontrará por aí. Primeiro, uma única chamada a setValues(), e não uma por célula — as escritas em lote sobre intervalos são drasticamente mais rápidas. Segundo, um pedido falhado retorna de imediato em vez de limpar a tabela, pelo que uma falha do fornecedor deixa taxas desatualizadas mas identificadas como tal, em vez de uma folha cheia de brancos que transforma silenciosamente todos os totais a jusante em zero.

Criar o acionador

function installTrigger() {
  ScriptApp.getProjectTriggers().forEach(function (t) {
    if (t.getHandlerFunction() === 'refreshRates') ScriptApp.deleteTrigger(t);
  });
  ScriptApp.newTrigger('refreshRates').timeBased().everyHours(1).create();
}

A Google documenta que os acionadores temporais podem correr "com uma frequência tão alta como a cada minuto ou tão baixa como uma vez por mês", e que a hora de disparo é deliberadamente aproximada: "se criar um acionador recorrente para as 9h, o Apps Script escolhe uma hora entre as 9h e as 10h." Se usar everyMinutes(n), n tem de ser 1, 5, 10, 15 ou 30 — nenhum outro valor é aceite.

Ler as taxas

=XLOOKUP("USD_EUR", Rates!A:A, Rates!D:D)
=A2 * XLOOKUP($B$1 & "_" & $C$1, Rates!A:A, Rates!D:D)

Todas as conversões no livro passam agora a resolver-se instantaneamente a partir de células locais, usam uma taxa consistente e trazem uma marca temporal visível. Este último ponto é aquele por que os auditores perguntam.

---

Quotas e Limites Que Vai Realmente Atingir

Estes são os números publicados pela Google para o Apps Script — vale a pena conhecê-los antes de desenhar a solução:

Esse limite de 2 KB no URL é o teto prático para quantos pares consegue comprimir num único lote ?q= — confortavelmente mais de cem, mas não ilimitado.

Do lado da API, o plano gratuito da Finexly permite 1.000 pedidos por mês a 10 pedidos por minuto. Um acionador de hora a hora usa cerca de 730 pedidos por mês — dentro do plano gratuito e com folga. Acrescente um punhado de chamadas pontuais a funções personalizadas e poderá querer o plano Starter; os escalões atuais estão na página de preços. Note que as taxas históricas exigem um plano pago, por isso, se precisar de taxas retroativas e tiver orçamento zero, o GOOGLEFINANCE continua a ser a resposta honesta para uso pessoal e não profissional.

Todas as respostas trazem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Used e X-RateLimit-Units, pelo que pode registar o consumo a partir de res.getAllHeaders() e antecipar a chegada a um limite.

---

Erros Comuns e Como os Resolver

Para padrões mais aprofundados sobre repetições, backoff e invalidação de cache em produção, veja o nosso guia sobre cache e tratamento de erros em APIs de câmbio.

---

Que Método Deve Usar?

• Folha pessoal, consulta rápida, sem dinheiro em jogo: GOOGLEFINANCE. É gratuito, instantâneo, e a restrição de licença não o afeta.
• Uma coluna de conversão numa folha de cálculo de trabalho: a função personalizada em Apps Script com processamento em lote. Fonte de dados previsível, sem ambiguidade de licença, uma chamada por intervalo.
• Tudo o que um colega, cliente ou auditor leia: a tabela de taxas agendada. Uma taxa por ciclo de atualização, uma marca temporal visível e nenhuma dependência do momento em que o Sheets decide recalcular.

A trabalhar no Excel? Os métodos equivalentes — Power Query, WEBSERVICE e o tipo de dados Moedas — são abordados em como obter taxas de câmbio em tempo real no Excel. Se ainda está a avaliar fornecedores, a nossa comparação de APIs de câmbio expõe as diferenças, e pode validar qualquer taxa no conversor de moedas da Finexly.

---

Perguntas Frequentes

Como obtenho taxas de câmbio em tempo real no Google Sheets gratuitamente?

=GOOGLEFINANCE("CURRENCY:USDEUR") não custa nada e não requer configuração. Tenha em conta a restrição de utilização declarada pela Google — os dados "não se destinam a uso profissional no setor financeiro nem a uso por outros profissionais em empresas não financeiras" — e que os valores históricos não podem ser lidos via Apps Script ou API do Sheets. Para uma alternativa licenciada a custo zero, um plano gratuito de API com 1.000 pedidos por mês cobre confortavelmente uma atualização de hora a hora (cerca de 730 chamadas).

Com que frequência o GOOGLEFINANCE atualiza as taxas de câmbio?

A tabela do aviso legal do Google Finance indica um atraso de 3 minutos para os dados de moedas, com origem na Morningstar — e não os 20 minutos habitualmente repetidos online, que correspondem ao valor genérico das cotações de títulos associado ao atributo "price". Separadamente, a Google nunca publicou com que frequência o Sheets recalcula a fórmula, pelo que a idade do número na sua célula não é algo em que possa confiar.

Posso usar o GOOGLEFINANCE dentro do Apps Script?

Não para dados históricos. A Google afirma: "Os dados históricos não podem ser descarregados nem acedidos através da API do Sheets ou do Apps Script. Se tentar fazê-lo, verá um erro #N/A." Também não existe qualquer método GOOGLEFINANCE em nenhum serviço do Apps Script — um script só consegue ler um valor que uma célula já calculou. Se precisa de taxas em código, chame uma API de câmbio com o UrlFetchApp.

Porque é que a minha fórmula de câmbio no Google Sheets está lenta ou mostra #ERROR!?

Cada chamada a uma função personalizada é uma ida e volta separada ao servidor do Apps Script, e cada execução está limitada a 30 segundos. Centenas de chamadas individuais vão exceder o tempo. Aceite um intervalo e devolva uma matriz para que uma chamada cubra a coluna inteira, guarde a taxa em cache e, para tudo o que seja agendado, mova o pedido para um acionador temporal em vez de uma célula.

Posso obter taxas de câmbio históricas no Google Sheets?

Sim, de duas formas. GOOGLEFINANCE("CURRENCY:USDEUR", "close", DATE(2026,1,1), DATE(2026,1,31), "DAILY") devolve uma série diária — use "close", já que "price" não é um atributo histórico válido, e lembre-se de que a Google trata as datas como meio-dia UTC, o que pode desviar um valor em um dia. Ou obtenha taxas históricas de uma API num plano pago e escreva-as numa folha com um acionador, que é a única via que sobrevive à automação.

---

Pronto para ter taxas de câmbio licenciadas e atualizadas ao minuto na sua folha de cálculo? Obtenha a sua chave de API gratuita da Finexly — sem cartão de crédito. Comece com 1.000 pedidos por mês em mais de 170 moedas e faça upgrade quando as suas folhas crescerem para além disso.