Nó Google Sheets

O nó de workflow Google Sheets (google_sheets_request) lê e grava dados de planilhas via Google Sheets API v4 ou, no modo link público, via endpoint JSON gviz do Google para planilhas publicadas.

ID do nó no editor: google_sheets_request
Base da API (OAuth): https://sheets.googleapis.com/v4/spreadsheets/
Variável de token (OAuth): {{google_sheets_token}}

O que faz

A cada execução, o engine:

1. Resolve spreadsheet ID, aba da planilha, URL, headers e body
2. Injeta token OAuth do serviço conectado (modo OAuth) ou busca JSON gviz público (modo link público)
3. Faz parse de respostas gviz em JSON quando aplicável
4. Retorna status, data e headers

Pré-requisitos

Modo OAuth (ler/gravar planilhas privadas)

1. Configurações → Chaves de API → Serviços conectados
2. Adicione Google Sheets (Google OAuth)
3. No nó, selecione Serviço conectado e escolha Planilha + Aba

Obrigatório para operações de escrita (update, append, clear).

Modo link público (somente leitura)

1. Ative Link público (google_sheets_public_link: true) — padrão para nós novos
2. Cole uma URL docs.google.com/spreadsheets/...
3. A planilha deve estar publicada ou compartilhada como "Anyone with the link can view"

O engine converte a URL do doc em URL de query gviz:

https://docs.google.com/spreadsheets/d/{spreadsheet_id}/gviz/tq?tqx=out:json&gid={gid}

Nenhum token OAuth é enviado. Operações de escrita não estão disponíveis no modo público.

Como configurar

Passo 1 — Adicionar o nó

1. Abra Automações
2. Paleta → Dados → Google Sheets
3. Escolha OAuth ou link público
4. Selecione planilha e aba (OAuth) ou cole a URL pública
5. Escolha um template de operação

Passo 2 — Templates de operação

Passo 3 — Planilha e range

Modo OAuth — use os seletores da UI:

• Planilha (google_spreadsheet_id) — spreadsheet ID da URL
• Aba (google_sheet_title) — nome da aba (ex.: Sheet1, Leads)

Notação de range (sintaxe A1):

Exemplo de URL para ler range:

https://sheets.googleapis.com/v4/spreadsheets/{{spreadsheet_id}}/values/Leads!A1:E100

Variáveis funcionam em URLs: .../values/{{variables.sheet_name}}!A1:Z

Passo 4 — Payloads de escrita

Atualizar range (PUT):

{
  "values": [
    ["Name", "Phone", "Status"],
    ["{{trigger.body.name}}", "{{trigger.body.phone}}", "New"]
  ]
}

A URL deve incluir valueInputOption=USER_ENTERED (o template adiciona isso):

.../values/Leads!A1:C1?valueInputOption=USER_ENTERED

Acrescentar linhas (POST):

{
  "values": [
    ["{{date:now}}", "{{contact.name}}", "{{contact.phone}}", "{{trigger.body.source}}"]
  ]
}

Padrão de URL para append:

.../values/Leads!A:D:append?valueInputOption=USER_ENTERED

Limpar range (POST): body vazio; URL termina com :clear.

Passo 5 — Leitura com link público

Cole a URL completa do navegador, ex.:

https://docs.google.com/spreadsheets/d/1ABC.../edit#gid=0

O editor extrai spreadsheet_id e gid (aba) e monta a URL gviz automaticamente. A resposta é parseada do wrapper google.visualization.Query.setResponse(...) do Google em JSON em data.

Use nós JavaScript ou Variável para mapear colunas gviz ao formato da sua mensagem.

Passo 6 — Usar a saída

Resposta de leitura OAuth:

{
  "range": "Leads!A1:C3",
  "majorDimension": "ROWS",
  "values": [
    ["Name", "Phone", "Status"],
    ["Ana", "5511999999999", "New"]
  ]
}

Referencie em nós posteriores:

{{google_sheets_1.data.values}}
{{google_sheets_1.data.values[1][0}}

Saídas do nó

Dicas e boas práticas

• Append para logs — use Acrescentar linhas para logs de leads; evite sobrescrever com PUT a menos que seja intencional
• Linha de cabeçalho — mantenha a linha 1 como nomes de colunas; append começa abaixo dos dados existentes
• USER_ENTERED vs RAW — USER_ENTERED interpreta datas e números como digitação manual; RAW armazena literais
• Modo público é somente leitura — mude para OAuth para escrita
• Planilhas grandes — leia ranges específicos, não colunas inteiras sem limites
• Rate limits — a Google Sheets API tem quotas; adicione Delay em fluxos Loop em massa
• Combine com Condição — verifique se o phone já existe na coluna B antes do append
• Faça parse do índice de linha em values com cuidado — a linha 0 costuma ser cabeçalhos

Exemplos de casos de uso

Registrar cada lead de webhook em planilha compartilhada

1. Gatilho Webhook
2. Google Sheets (OAuth) — append de linha com timestamp, name, phone, UTM
3. Enviar WhatsApp — confirmação

Digest diário de planilha pública de relatórios

1. Gatilho agendado
2. Google Sheets (link público) — ler dados gviz
3. Texto + Enviar mensagem — resumo ao grupo da equipe

Buscar preço de produto por SKU

1. Variável — sku da mensagem
2. Google Sheets — ler Products!A:B (SKU, Price)
3. JavaScript — encontrar linha onde coluna A corresponde ao SKU
4. Enviar mensagem — responder com o preço

Sincronizar estágio do CRM com planilha

1. Gatilho CRM — card movido
2. Google Sheets — atualizar range na linha que corresponde ao contact ID na coluna A

FAQ

"Select connected service" na escrita?
Append, update e clear exigem OAuth. Modo link público só lê.

Array values vazio?
Range sem dados, nome de aba incorreto ou spreadsheet ID errado. Verifique se a notação A1 inclui o nome da aba (Sheet1!...).

401 Unauthorized?
Reconecte Google Sheets OAuth ou token expirado — reautorize em Configurações.

Erro de parse gviz no modo público?
Planilha não pública, URL incorreta ou Google alterou formato de resposta. Confirme "Anyone with link can view".

Posso criar planilha nova a partir do workflow?
Não nos templates padrão — use Google Drive API ou criação manual, depois referencie o ID.

Diferença do nó Google Drive?
Sheets é otimizado para leitura/gravação tabular (values API). Drive lida com arquivos, pastas e exports.

Referência da API

Relacionados

• Visão geral de Dados
• Nó Google Drive
• Visão geral das integrações
• Variáveis no workflow