---
title: Google Sheets
description: Adicione, atualize, leia, limpe ou exclua linhas — e crie abas — numa planilha do Google Sheets, direto do fluxo, sem passar por IA.
---

# Google Sheets  ·  `google_sheets`

<NoCard kind="google_sheets" categoria="Ações" />

<Secao icon="info">Para que serve</Secao>

Pensa numa planilha de controle que a equipe já usa no dia a dia — leads, atendimentos, agendamentos — e que o fluxo precisa alimentar ou consultar automaticamente. O nó Google Sheets é um único bloco que faz isso: dentro dele, você escolhe a **Ação** (adicionar linha, atualizar, ler, limpar, excluir ou criar aba) e o fluxo executa a operação direto na planilha conectada, sem interpretação de IA — determinístico, como um script.

<Secao icon="clock">Quando usar</Secao>

- Registrar leads, atendimentos ou eventos numa planilha de controle
- Manter um cadastro atualizado (upsert por uma coluna-chave, como CPF ou telefone)
- Consultar dados de uma planilha para decidir o próximo passo do fluxo
- Limpar ou reorganizar uma planilha entre execuções (ex.: relatório periódico)
- Criar uma aba nova por período (ex.: uma aba por mês, duplicando o modelo)

<Dica>

Se você precisa que a IA decida quando e o que fazer na planilha (em vez de um ponto fixo do fluxo), use a integração Google Sheets como ferramenta de um [Agente de IA](/guia/flow-builder/ia/agent-no) em vez deste nó dedicado.

</Dica>

---

## Pré-requisitos

O workspace precisa ter uma conta do **Google Workspace conectada** (via OAuth), com a integração Google Sheets liberada. Veja como conectar em [Conectar Google Workspace](/guia/conectar/google-workspace).

<Cuidado>

Esta integração exige o escopo do **Google Drive** (para listar as planilhas acessíveis pela conta conectada), além do escopo de Sheets. Se a conexão do seu workspace foi feita antes desse escopo existir, o seletor de **Planilha** pode não carregar — clique em **Reconectar** no card do Google Workspace, em **Conexões** → **Integrações**, para autorizar o acesso completo.

</Cuidado>

---

<Secao icon="list-checks">Passo a passo</Secao>

<Passos>
  <Passo>Na aba **Ferramentas** da paleta, arraste o item **Google Sheets** para o canvas e conecte-o ao bloco anterior. O nó já nasce configurado com a ação **Adicionar linha**.<br/><Captura legenda="Paleta de nós aberta no canvas do Flow Builder, com as categorias disponíveis para localizar e arrastar o nó desejado" src="/img/flowbuilder-paleta-aberta.png" /></Passo>
  <Passo>No painel, escolha a **Ação** desejada entre as 7 operações disponíveis. Trocar a ação atualiza os campos abaixo conforme a operação escolhida, preservando os valores em comum (Planilha, Aba, etc.).</Passo>
  <Passo>Escolha a **Planilha** na lista de planilhas acessíveis pela conta Google conectada.</Passo>
  <Passo>Escolha a **Aba** dentro da planilha selecionada. Trocar a Planilha recarrega automaticamente a lista de abas disponíveis.</Passo>
  <Passo>Preencha os demais campos, específicos de cada ação (veja a tabela abaixo).</Passo>
  <Passo>Salve e conecte a saída ao próximo nó.</Passo>
</Passos>

---

## As 7 ações

Todas as ações rodam sobre o mesmo servidor MCP `google-sheets` do workspace, resolvido automaticamente — você não escolhe servidor nem ferramenta manualmente, só a **Ação**.

### Adicionar linha  ·  `google_sheets.append_row`

Adiciona uma nova linha ao final da aba escolhida.

| Campo | O que faz |
|-------|-----------|
| **Planilha** | A planilha de destino |
| **Aba** | A aba dentro da planilha onde a linha será adicionada |
| **Colunas** | Mapa coluna → valor: uma entrada por coluna do cabeçalho, cada uma recebendo uma variável do fluxo ou um texto fixo |

**Saídas:** `updated_range` (intervalo A1 escrito), `row_number` (linha gravada), `is_error`.

---

### Atualizar linha  ·  `google_sheets.update_row`

Localiza a linha pela **Coluna-chave** + **Valor da chave** e atualiza os valores mapeados.

| Campo | O que faz |
|-------|-----------|
| **Planilha** / **Aba** | Destino da atualização |
| **Coluna-chave** | Coluna usada para localizar a linha (ex.: `CPF`, `Telefone`) |
| **Valor da chave** | Expressão do fluxo comparada com a coluna-chave |
| **Colunas** | Mapa coluna → valor. Colunas não mapeadas preservam o valor atual da linha |

**Saídas:** `updated_range`, `row_number`, `found` (booleano), `is_error`.

<Cuidado>

Quando nenhuma linha casa com a chave, a ação retorna `found=false` **e** `is_error=true` — mas não interrompe o fluxo. Trate esse caso com um nó de decisão logo depois, se precisar de um comportamento diferente para "chave não encontrada".

</Cuidado>

---

### Adicionar ou atualizar linha  ·  `google_sheets.append_or_update`

Upsert pela coluna-chave: atualiza a linha que casa com a chave, ou adiciona uma nova linha no final quando nenhuma casar.

| Campo | O que faz |
|-------|-----------|
| **Planilha** / **Aba** | Destino da operação |
| **Coluna-chave** | Coluna usada para localizar a linha existente |
| **Valor da chave** | Expressão do fluxo comparada com a coluna-chave |
| **Colunas** | Mapa coluna → valor |

**Saídas:** `updated_range`, `row_number`, `appended` (booleano — `true` quando a linha foi adicionada em vez de atualizada), `is_error`.

---

### Ler linhas  ·  `google_sheets.get_rows`

Lê linhas da aba como objetos coluna → valor, usando o cabeçalho como chave.

| Campo | O que faz |
|-------|-----------|
| **Planilha** / **Aba** | Origem da leitura |
| **Filtrar por coluna** *(opcional)* | Coluna usada para filtrar as linhas retornadas |
| **Valor do filtro** *(opcional)* | Expressão do fluxo comparada com a coluna de filtro |
| **Limite de linhas** | Quantidade máxima de linhas retornadas — padrão 100, máximo 1.000 |

**Saídas:** `rows` (lista de objetos coluna → valor, na ordem da planilha), `row_count`, `is_error`.

---

### Limpar intervalo  ·  `google_sheets.clear`

Limpa os valores de um intervalo (ou de toda a aba).

| Campo | O que faz |
|-------|-----------|
| **Planilha** / **Aba** | Onde limpar |
| **Intervalo (A1)** *(opcional)* | Intervalo em notação A1 dentro da aba (ex.: `A2:D10`). Vazio limpa a aba inteira |

**Saídas:** `cleared_range` (intervalo A1 efetivamente limpo), `is_error`.

---

### Excluir linhas ou colunas  ·  `google_sheets.delete_rows_or_columns`

Exclui linhas ou colunas da aba.

| Campo | O que faz |
|-------|-----------|
| **Planilha** / **Aba** | Onde excluir |
| **Linhas** *(opcional)* | Lista de números de linha (base 1) a excluir, para linhas não contíguas |
| **Intervalo de linhas** *(opcional)* | Intervalo contíguo `início:fim` (base 1), ex.: `5:10` |
| **Colunas** *(opcional)* | Letras das colunas a excluir, ex.: `C`, `D` |

<Cuidado>

Pelo menos um entre **Linhas**, **Intervalo de linhas** e **Colunas** é obrigatório.

</Cuidado>

**Saídas:** `is_error`.

---

### Criar aba  ·  `google_sheets.create_sheet`

Cria uma nova aba na planilha, opcionalmente duplicando uma aba existente.

| Campo | O que faz |
|-------|-----------|
| **Planilha** | Planilha onde a aba será criada |
| **Nome da nova aba** | Nome da aba a ser criada |
| **Duplicar da aba** *(opcional)* | Nome de uma aba existente a duplicar. Vazio cria uma aba em branco |
| **Posição** *(opcional)* | Posição (base 0) onde a nova aba será inserida |

**Saídas:** `sheet_title` (nome efetivo da aba criada), `is_error`.

---

<Secao icon="info">Comportamento comum a todas as ações</Secao>

- Os seletores de **Planilha**, **Aba** e **Coluna** são carregados dinamicamente a partir da conta Google conectada ao workspace.
- Erros retornados pela planilha (ex.: intervalo inválido, aba inexistente) não derrubam a execução do fluxo — eles viram `is_error=true` na saída da ação, e a decisão de como reagir fica com você (ex.: um nó **Se/Então** logo depois).
- Todas as ações aceitam configuração de **retry** (`retry_config`) para tentar novamente automaticamente em caso de falha transitória de rede ou da API do Google.

---

## Erros comuns

**Google não conectado (ou conexão expirada)**
O nó retorna erro indicando que não há uma conta Google conectada e válida para o workspace. Acesse **Conexões** → **Integrações** e conecte (ou reconecte) o Google Workspace — veja [Conectar Google Workspace](/guia/conectar/google-workspace).

**Seletor de Planilha vazio ou sem carregar**
Costuma indicar que a conexão do workspace ainda não tem o escopo do Google Drive. Reconecte o Google Workspace (veja o aviso em [Pré-requisitos](#pré-requisitos)).

**Planilha ou aba excluída**
Se a planilha ou a aba configurada no nó for excluída (ou o acesso a ela for removido) depois de o nó estar configurado, a execução falha ao tentar localizar o destino. Abra o nó, escolha novamente a Planilha e a Aba corretas e salve.

---

<Secao icon="circle-check">Exemplo</Secao>

Cenário: ao final de um atendimento, registrar ou atualizar o lead numa planilha de controle, usando o telefone como chave.

**Configuração:**
- Ação: **Adicionar ou atualizar linha**
- Planilha: `Controle de Leads`
- Aba: `Leads 2026`
- Coluna-chave: `Telefone`
- Valor da chave: <code v-pre>{{contact.phone}}</code>
- Colunas:
  - `Nome`: <code v-pre>{{contact.name}}</code>
  - `Interesse`: <code v-pre>{{extrair_parametros.interesse}}</code>

**Uso da saída:**
No nó seguinte, acesse <code v-pre>{{google_sheets.appended}}</code> para saber se o lead era novo (`true`) ou já existia (`false`) — por exemplo, para enviar uma mensagem de boas-vindas só na primeira vez.

---

## Saiba mais

- [Conectar Google Workspace](/guia/conectar/google-workspace) — como conectar a conta Google que este nó usa
- [Ação na Plataforma](/guia/flow-builder/acoes/acoes-plataforma) — operações nativas do Atende Direito
- [Ferramenta MCP](/guia/flow-builder/acoes/ferramenta-mcp) — chame outras ferramentas de serviços externos conectados