Planilha é o lugar onde muita gente guarda tudo: gastos, clientes, estoque, cotações. Neste tutorial você vai ensinar o n8n a escrever no Google Sheets sozinho. O exemplo é simples e útil: cada vez que o workflow roda, ele busca a cotação do dólar numa API pública e acrescenta uma linha nova na sua planilha, com data, valor de compra, valor de venda e variação do dia.
A parte do n8n é rápida. O que costuma travar quem está começando é a conexão com a conta Google, e é nela que este guia vai mais devagar, campo a campo. Se você instalou o n8n no seu computador com Docker, como no tutorial n8n do zero com Docker, o caminho certo passa pelo Google Cloud Console, e ele está explicado inteiro aqui.
O que você vai construir
Um workflow de quatro nós, ligados em sequência:
- Manual Trigger (aparece como “When clicking ‘Execute workflow’”): dá a partida quando você clica no botão Execute workflow.
- HTTP Request: consulta a cotação do dólar na AwesomeAPI, a mesma API pública usada no tutorial do dólar no e-mail.
- Edit Fields (Set): separa só os quatro dados que interessam e já converte os valores para número.
- Google Sheets: acrescenta esses dados como uma linha nova no fim da planilha (operação Append Row).
No fim, você também vai ver como trocar o clique manual por um horário fixo, para a planilha se preencher sozinha todo dia.
Diferente dos outros tutoriais da série: aqui é preciso uma conta Google e um projeto gratuito no Google Cloud. A cotação continua vindo de uma API sem cadastro, mas escrever na sua planilha exige que você autorize o n8n, e essa autorização é feita com uma credencial OAuth2. Os nomes de botões estão em inglês, como aparecem no n8n e no Google Cloud.
Pré-requisitos
- Um n8n rodando no seu computador, acessível em
http://localhost:5678. Se ainda não tem, siga antes o tutorial n8n do zero com Docker: instale e receba a cotação do dólar no e-mail. - Uma conta Google (pode ser um Gmail pessoal comum).
- Uns 30 minutos, a maior parte deles no Google Cloud Console, só na primeira vez.
Por que não basta clicar em “Sign in with Google”?
Muitos tutoriais mostram a credencial do Google sendo criada com um único clique em Sign in with Google. Isso existe, mas só no n8n Cloud, a versão paga hospedada pela própria empresa. Lá, o n8n já tem um aplicativo registrado no Google (o chamado Managed OAuth2) e usa as chaves dele.
No n8n self-hosted, que é o caso de quem instalou com Docker, esse atalho não existe. A documentação oficial do n8n é direta sobre isso: você precisa criar o seu próprio aplicativo no Google Cloud Console e copiar dois valores para o n8n, o Client ID e o Client Secret. Eles não são gerados pelo n8n; quem gera é o Google, quando você cria o aplicativo.
Pense no Client ID como o “nome de usuário” do seu aplicativo junto ao Google e no Client Secret como a “senha” dele. Com os dois, o n8n consegue pedir ao Google: “o dono desta conta autorizou este aplicativo a mexer nas planilhas dele?”. Você responde “sim” uma única vez, na tela de login do Google, e a partir daí o n8n guarda a autorização.
Cuidado: o Client Secret é uma senha. Não cole em fórum, não mande por mensagem e não publique print com ele aparecendo. Se ele vazar, apague o cliente OAuth no Google Cloud e crie outro.
Parte 1: prepare a planilha
- Abra o Google Sheets e crie uma planilha em branco.
- Dê a ela o nome Cotação do dólar (clique em “Planilha sem título”, no canto superior esquerdo).
- Na primeira linha, escreva os cabeçalhos, um por coluna:
dataem A1,compraem B1,vendaem C1 evariacaoem D1. - Deixe a aba com o nome padrão, Página1.
Escreva os cabeçalhos exatamente assim, em minúsculas e sem acento. Mais adiante o n8n vai casar cada campo com a coluna de mesmo nome, e qualquer diferença (um “Compra” com C maiúsculo, um espaço sobrando) faz o dado ir para uma coluna nova em vez da certa.
Parte 2: crie o aplicativo no Google Cloud Console
Tudo nesta parte acontece em console.cloud.google.com, entrando com a mesma conta Google dona da planilha. O uso que vamos fazer é gratuito: não é preciso cadastrar cartão de crédito para ativar as APIs do Google Sheets e do Google Drive.
2.1 Crie um projeto
- No topo da página, clique no seletor de projetos (ao lado do logotipo do Google Cloud) e depois em New project.
- Em Project name, escreva algo fácil de reconhecer, como
n8n-local. - Em Location, deixe No organization (é o normal para contas pessoais).
- Clique em Create e espere alguns segundos.
- Confira no seletor do topo se o projeto n8n-local está selecionado. Todos os passos seguintes valem para o projeto que estiver selecionado ali.
2.2 Ative as APIs do Google Sheets e do Google Drive
Um projeto novo não pode usar nenhuma API até você ativá-la. Vamos ativar duas:
- No menu lateral, vá em APIs & Services > Library.
- Pesquise por Google Sheets API, abra o resultado e clique em Enable.
- Volte à Library, pesquise por Google Drive API, abra e clique em Enable.
Por que o Drive, se vamos usar só o Sheets? Porque é pela API do Drive que o n8n lista as suas planilhas para você escolher numa lista, em vez de colar o endereço. A documentação do n8n pede as duas para o nó do Google Sheets.
2.3 Configure a tela de consentimento
A tela de consentimento é aquela janela do Google que pergunta “o aplicativo X quer acessar sua conta, permitir?”. Mesmo sendo um aplicativo só seu, ela precisa existir.
- No menu lateral, vá em APIs & Services > OAuth consent screen. O Google abre a área chamada Google Auth Platform; clique em Get started.
- App information: em App name, escreva
n8n local; em User support email, escolha o seu e-mail. Clique em Next. - Audience: escolha External. (A opção Internal só aparece para contas de empresa no Google Workspace.) Clique em Next.
- Contact Information: informe o seu e-mail para o Google avisar sobre mudanças no projeto. Clique em Next.
- Finish: marque a concordância com a política de dados do Google, clique em Continue e depois em Create.
Como você escolheu External, o aplicativo nasce em modo de teste (Testing). Nesse modo, só as contas cadastradas como usuários de teste conseguem autorizar. Então cadastre a sua:
- Ainda na Google Auth Platform, abra Audience no menu lateral.
- Em Test users, clique em Add users, digite o seu Gmail (o mesmo da planilha) e salve.
Se você pular este passo, o login do Google vai terminar num erro de acesso bloqueado (access_denied). É o erro mais comum de todo o processo.
2.4 Pegue a URL de retorno no n8n
Antes de criar o cliente OAuth, você precisa de um endereço que só o n8n sabe dizer: a OAuth Redirect URL, para onde o Google devolve você depois do login. Deixe o Google Cloud aberto numa aba e, em outra, abra o n8n:
- No n8n, clique em Create (ou no + do menu lateral) e escolha Credential.
- Pesquise por Google Sheets OAuth2 API e selecione.
- No topo do formulário aparece o campo OAuth Redirect URL. Clique nele para copiar.
Numa instalação como a do nosso tutorial de Docker, o endereço é este:
http://localhost:5678/rest/oauth2-credential/callback
O Google aceita localhost como endereço de retorno em ambiente de desenvolvimento, então você não precisa de domínio, HTTPS nem abrir portas no roteador. Se o seu n8n roda em outro endereço (um servidor com domínio, por exemplo), use o endereço que o seu n8n mostrar, e não o do exemplo. Deixe essa aba do n8n aberta; vamos voltar a ela.
2.5 Crie o cliente OAuth (Client ID e Client Secret)
- No Google Cloud, vá em APIs & Services > Credentials.
- Clique em + Create credentials > OAuth client ID.
- Em Application type, escolha Web application.
- Em Name, troque o nome automático por algo como
n8n local. - Em Authorized redirect URIs, clique em + Add URI e cole a URL copiada do n8n.
- Deixe Authorized JavaScript origins em branco; não é usado aqui.
- Clique em Create.
O Google mostra uma janela com o Client ID (um texto longo terminado em .apps.googleusercontent.com) e o Client Secret. Mantenha essa janela aberta para copiar os dois no próximo passo. Se fechar sem querer, os dados ficam em Credentials > nome do cliente.
| Campo no Google Cloud | O que colocar | Por que |
|---|---|---|
| Application type | Web application | O n8n funciona como um site que pede autorização e recebe a resposta numa URL; é o tipo que aceita URL de retorno. |
| Name | n8n local | Só para você reconhecer depois. O usuário não vê esse nome. |
| Authorized JavaScript origins | (vazio) | Serve para apps que rodam inteiros no navegador. Não é o nosso caso. |
| Authorized redirect URIs | http://localhost:5678/rest/oauth2-credential/callback | Precisa ser idêntica à do n8n, letra por letra, com http e a porta 5678. Qualquer diferença gera o erro redirect_uri_mismatch. |
Parte 3: termine a credencial no n8n
Volte à aba do n8n, onde a credencial Google Sheets OAuth2 API ficou aberta, e preencha:
| Campo no n8n | O que colocar | Observação |
|---|---|---|
| OAuth Redirect URL | (já preenchido) | É só para copiar. Não altere. |
| Client ID | o Client ID do Google | Copie e cole; cuidado com espaços no começo ou no fim. |
| Client Secret | o Client Secret do Google | Fica guardado criptografado no n8n, com a chave de criptografia da sua instalação. |
| Custom Scopes | desligado | O n8n já pede as permissões certas para o nó do Google Sheets. Só mexa nisso se souber o que está fazendo. |
Agora clique em Sign in with Google. Uma janela do Google vai abrir:
- Escolha a conta Google que você cadastrou como usuário de teste.
- Vai aparecer o aviso “Google hasn’t verified this app” (o Google não verificou este app). É esperado: o aplicativo é seu e está em modo de teste. Clique em Continue.
- Revise as permissões pedidas: ver, editar, criar e excluir as suas planilhas; ver informações (nome, data, pasta) dos arquivos do Drive, que é como o n8n monta a lista de planilhas; e acessar os arquivos que você usar com o app. Se aparecerem caixas de seleção, marque todas e clique em Continue.
- A janela fecha e o n8n mostra Account connected. Clique em Save e dê um nome à credencial, como
Google Sheets (minha conta).
Sobre o modo de teste: com o aplicativo em Testing e público External, o Google faz a autorização expirar depois de 7 dias. Quando isso acontecer, o workflow passa a falhar com erro de autenticação; basta abrir a credencial e clicar de novo em Sign in with Google. Para estudar e testar, isso é suficiente.
Parte 4: monte o workflow, nó por nó
Crie um workflow novo e chame-o de Dólar na planilha. Vamos adicionar os quatro nós na ordem.
Nó 1: Manual Trigger
No meio do canvas, clique em Add first step e escolha Trigger manually. Ele não tem nenhum parâmetro: só entrega um item vazio para dar a partida, como no tutorial da Selic, CDI e IPCA.
Nó 2: HTTP Request (cotação do dólar)
Clique no + à direita do primeiro nó, procure HTTP Request e configure:
| Campo | Valor | Por que assim |
|---|---|---|
| Method | GET | Só queremos ler um dado. |
| URL | https://economia.awesomeapi.com.br/json/last/USD-BRL | Endereço da AwesomeAPI que devolve a última cotação do dólar comercial em reais. |
| Authentication | None | A API é pública, sem chave. |
| Send Query Parameters / Headers / Body | desligados | Não são necessários nesta consulta. |
USDBRL.Clique em Execute step. No painel OUTPUT, em modo JSON, a resposta tem um objeto chamado USDBRL com vários campos. Os que vamos usar são estes:
| Campo | O que significa |
|---|---|
bid | Valor de compra |
ask | Valor de venda |
pctChange | Variação do dia, em porcentagem |
create_date | Data e hora da cotação, no horário de Brasília |
Repare que os números chegam entre aspas, como "5.1866". Para a API eles são texto. Se você mandar texto para a planilha, ela pode não reconhecer como número (no Brasil, o separador decimal é a vírgula). Por isso o próximo nó converte.
Nó 3: Edit Fields (Set)
Adicione o nó Edit Fields (Set). Em Mode, deixe Manual Mapping e crie quatro campos com Add Field. Em cada campo, escolha o tipo à direita do nome e cole a expressão no valor:
| Nome | Tipo | Valor (expressão) |
|---|---|---|
| data | String | {{ $json.USDBRL.create_date }} |
| compra | Number | {{ Number($json.USDBRL.bid) }} |
| venda | Number | {{ Number($json.USDBRL.ask) }} |
| variacao | Number | {{ Number($json.USDBRL.pctChange) }} |
Deixe a opção Include Other Input Fields desligada: assim, só esses quatro campos seguem adiante, e os nomes deles são iguais aos cabeçalhos da planilha. A função Number() transforma o texto "5.1866" no número 5,1866. Clique em Execute step e confira, na saída, um único item com os quatro campos (os números aparecem sem aspas).
compra, venda e variacao já aparecem como números, sem aspas.Nó 4: Google Sheets (Append Row)
Adicione o nó Google Sheets e, na lista de ações, escolha Append row in sheet. Preencha:
| Campo | Valor | Explicação |
|---|---|---|
| Credential to connect with | Google Sheets (minha conta) | A credencial criada na Parte 3. |
| Resource | Sheet Within Document | Vamos trabalhar dentro de uma aba de uma planilha. |
| Operation | Append Row | Acrescenta uma linha nova depois da última linha preenchida. |
| Document | From list > Cotação do dólar | A lista vem do Google Drive. Se não aparecer, troque para By URL e cole o endereço da planilha. |
| Sheet | From list > Página1 | A aba onde estão os cabeçalhos. |
| Mapping Column Mode | Map Automatically | O n8n procura, para cada coluna, um campo de mesmo nome na entrada. Como o Edit Fields já criou data, compra, venda e variacao, tudo se encaixa. |
Se preferir controlar coluna por coluna, escolha Map Each Column Manually: o n8n lê os cabeçalhos da planilha e mostra um campo para cada um, onde você pode arrastar o dado vindo do nó anterior.
Teste
Clique em Execute workflow, na parte de baixo do canvas. Os quatro nós ficam verdes e, na planilha, aparece a linha 2 com a data, a compra, a venda e a variação. Rode de novo e surge a linha 3: o Append Row nunca sobrescreve, sempre acrescenta no fim.
Parte 5 (opcional): preencher a planilha todo dia sozinho
- Apague o Manual Trigger (selecione e tecle Delete).
- Adicione um Schedule Trigger e ligue-o ao HTTP Request.
- Em Trigger Interval, escolha Days; em Days Between Triggers,
1; em Trigger at Hour, por exemplo 6pm; e em Trigger at Minute,0. - Clique em Publish, no topo do editor, para o workflow passar a rodar sozinho.
O horário segue o fuso configurado no n8n. Na instalação do nosso tutorial de Docker, ele já está em America/Sao_Paulo, pela variável GENERIC_TIMEZONE. O computador precisa estar ligado e o Docker rodando no horário marcado; se estiver desligado, aquela execução não acontece. Quer receber um aviso no celular quando o dólar passar de um valor? Veja o tutorial Alerta de dólar no celular com n8n e combine os dois.
Erros comuns e como resolver
Erro 400: redirect_uri_mismatch
A URL de retorno cadastrada no Google não é idêntica à do n8n. Copie de novo a OAuth Redirect URL da credencial e confira no cliente OAuth (Credentials > nome do cliente): http e não https, porta 5678, sem barra sobrando no fim. Depois de salvar no Google, espere uns minutos antes de tentar de novo.
Erro 403: access_denied
A conta com que você tentou entrar não está na lista de usuários de teste. Volte em Google Auth Platform > Audience > Test users e adicione exatamente o mesmo Gmail.
Erro invalid_client
O Client ID ou o Client Secret no n8n não batem com o Google. Copie os dois de novo, com cuidado para não levar espaços junto.
“Google Sheets API has not been used in project… or it is disabled”
A API não foi ativada, ou foi ativada em outro projeto. Confira o seletor de projetos no topo do Google Cloud e ative a Google Sheets API no projeto certo. A ativação pode levar alguns minutos para valer.
A planilha não aparece na lista do campo Document
Normalmente falta ativar a Google Drive API. Outra saída é trocar From list por By URL e colar o endereço da planilha.
Os dados foram para colunas novas, à direita
Algum cabeçalho da planilha está diferente do nome do campo no Edit Fields. Compare os dois lados letra por letra (maiúsculas, acentos e espaços contam). Corrija e apague as colunas extras.
Os valores aparecem como texto ou com o número errado
Confira se os três campos numéricos do Edit Fields estão com o tipo Number e com a função Number() na expressão. Se a coluna ainda mostrar o valor alinhado à esquerda, como texto, selecione a coluna no Sheets e aplique Formatar > Número.
Funcionava e, uma semana depois, parou
É a expiração de 7 dias do modo de teste. Abra a credencial no n8n e clique em Sign in with Google outra vez.
Segurança e privacidade
- O aplicativo que você criou só funciona para as contas da lista de usuários de teste. Ninguém mais consegue usá-lo.
- Não publique prints da credencial com o Client Secret, nem da planilha com dados pessoais.
- Para revogar o acesso a qualquer momento, abra a sua Conta do Google, vá em Segurança e procure a seção de conexões com apps e serviços de terceiros; lá, remova o “n8n local”. Se quiser recomeçar do zero, apague também o cliente OAuth no Google Cloud.
Workflow pronto para importar
Prefere pular a montagem dos nós? Baixe o workflow pronto. No n8n, crie um workflow novo, abra o menu … (três pontinhos) no topo do editor, vá em Import e depois em From file para abrir o arquivo.
O download é um arquivo .zip com o dolar-na-planilha.json dentro; descompacte antes de importar. Por segurança, o arquivo não traz nenhuma credencial nem planilha: depois de importar, abra o nó Append row in sheet e escolha a sua credencial (Parte 3), o Document e a Sheet.
Recapitulando
- No n8n self-hosted, a conexão com o Google exige um aplicativo seu no Google Cloud Console; o botão de um clique só existe no n8n Cloud.
- O caminho é: projeto, APIs do Sheets e do Drive, tela de consentimento com você como usuário de teste e cliente OAuth do tipo Web application com a URL de retorno do n8n.
- O Client ID e o Client Secret vêm do Google e vão para a credencial Google Sheets OAuth2 API no n8n.
- O nó Edit Fields prepara os dados com os mesmos nomes dos cabeçalhos, e o Google Sheets com Append Row e Map Automatically grava uma linha nova a cada execução.
Com a credencial pronta, você pode reaproveitá-la em qualquer workflow: guardar respostas de formulários, montar um histórico de CEPs consultados ou registrar os feriados do ano numa aba.
Fontes
Documentação oficial consultada para este tutorial:
- n8n Docs: credencial Google OAuth2 (single service)
- n8n Docs: nó Google Sheets
- n8n Docs: operações do Google Sheets (Append Row e outras)
- n8n Docs: nó Edit Fields (Set)
- n8n Docs: nó HTTP Request
- n8n Docs: nó Schedule Trigger
- Google Cloud: gerenciar o app OAuth (tela de consentimento e público)
- Google for Developers: OAuth 2.0 para aplicativos web
- Google for Developers: conceitos da API do Google Sheets
- AwesomeAPI: documentação da API de Moedas
Siga a trilha Criar do zero
Instale o n8n no seu computador e monte workflows simples, de 2 a 5 nós, usando APIs públicas brasileiras que não pedem cadastro. Cada tutorial tem vídeo, prints e o JSON para importar.
