---
title: "Planilha"
slug: "planilha"
updated: 2026-09-14T16:53:00Z
published: 2026-09-14T16:53:00Z
canonical: "docs.omnisiga.ai/planilha"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Planilha

A caixa **Planilha (Google Sheets)** integra a conversa a uma planilha do Google Sheets. Ela executa uma de duas operações:

1. **Ler dados da planilha** — consulta o conteúdo de um intervalo de células e devolve o resultado para um script da própria caixa;
2. **Adicionar/atualizar planilha** — escreve linhas no intervalo indicado, adicionando ao final do conteúdo existente ou sobrescrevendo o intervalo.

Casos de uso típicos:

- consultar uma **tabela de preços**, prazos ou status cadastrados em planilha;
- **registrar cada atendimento** (protocolo, nome, solicitação) em uma nova linha;
- atualizar um **painel de acompanhamento** mantido em planilha;
- ler listas mantidas pelo cliente (feriados, unidades, planos) sem precisar de outra integração.

A planilha é acessada com credenciais do Google informadas por arquivo JSON (conta de serviço). As credenciais ficam guardadas pela plataforma, vinculadas à caixa, e o acesso à planilha acontece na execução do atendimento.

## Onde encontrar

1. Abra **Configuração → Fluxos**.
2. Crie ou abra uma versão do fluxo no editor.
3. Na lista de caixas (nova caixa), localize **Planilha (Google Sheets)** — ela aparece diretamente na lista, sem submenu, com o ícone de planilha.
4. Selecione a caixa para abrir o painel de configuração.
5. Preencha as opções e clique em **Aplicar**. Depois, salve a versão do fluxo.

![Image](https://cdn.document360.io/d1786d22-23e4-4145-98ac-accd680324d8/Images/Documentation/image(836).png)

## Como funciona

O comportamento geral é:

```
Caixa Planilha
      │
      ├── onEnter: dispara a operação na planilha
      │       ├── Ler dados       → aguarda a resposta da planilha
      │       └── Adicionar/atualizar → grava e segue
      │
      └── após a operação, vai para a caixa seguinte
```

Na leitura, a operação é assíncrona: a caixa dispara a consulta e, quando a planilha responde, o script **a executar após a requisição** roda com o resultado disponível em `input.response`. Só depois disso a conversa segue para a caixa seguinte.

Na escrita, a caixa envia os dados e já encaminha a conversa para a caixa seguinte configurada em **Após a operação, vai para**.

> **Importante:** a caixa acessa a planilha com a conta de serviço das credenciais. Para funcionar, a planilha precisa estar **compartilhada com o e-mail dessa conta de serviço** (a planilha não precisa ser pública).

## Pré-requisito: credenciais de acesso

Antes de salvar a caixa, é obrigatório enviar o arquivo de credenciais:

1. No Google Cloud, crie (ou reutilize) uma **conta de serviço** e baixe a chave no formato **JSON**.
2. Compartilhe a planilha desejada com o e-mail da conta de serviço, com permissão de leitura (operações de leitura) ou de edição (operações de escrita).
3. No painel da caixa, envie o arquivo em **Credenciais de acesso (arquivo)** — clique no link ou arraste o arquivo para a área de upload.
4. Ao remover as credenciais (opção **Remover credenciais**), a remoção tem efeito **imediato**.

As credenciais são vinculadas à caixa pelo **nome do elemento**. Por isso:

- informe o **Nome** da caixa antes de enviar o arquivo;
- se o nome da caixa mudar depois do upload, é preciso atualizar o arquivo de credenciais — o salvamento bloqueia a alteração sem essa atualização.

## Campos da caixa

| Campo | Obrigatório | Descrição |
| --- | --- | --- |
| **Nome** | Sim | Nome da caixa no diagrama. Também identifica as credenciais vinculadas. |
| **Identificador da planilha (Google Sheets)** | Sim | O ID da planilha, presente na URL do documento entre `/d/` e `/edit` — ex.: `1AbC...xYz` em `https://docs.google.com/spreadsheets/d/1AbC...xYz/edit`. |
| **Nome da aba da planilha** | Não¹ | Aba dentro da planilha (ex.: `Preços`). Use quando o documento tiver mais de uma aba. |
| **Intervalo de células** | Sim¹ | Intervalo a ler ou escrever, no formato do Google Sheets (ex.: `A1:C50`). |
| **Operação** | Sim | Escolha entre **Adicionar/atualizar planilha** e **Ler dados da planilha**. |
| **Sobrescrever dados existentes** | Não | Só na operação de escrita. Marcado: substitui o conteúdo do intervalo. Desmarcado: adiciona as linhas abaixo do conteúdo existente. |
| **Dados a serem adicionados/atualizados (formato JSON)** | Sim² | Só na operação de escrita. Conteúdo a gravar, no formato `{"values": [[...]]}`. Aceita variáveis `{{variavel}}`. |
| **Script a executar após a requisição** | Não | Só na operação de leitura. JavaScript executado quando a planilha responde; por padrão vem `let data = input.response;`. |
| **Credenciais de acesso (arquivo)** | Sim | Upload do arquivo JSON da conta de serviço do Google. |
| **Após a operação, vai para:** | Não | Caixa seguinte do fluxo depois da operação concluída. |

¹ É obrigatório informar **pelo menos um** entre aba e intervalo; na prática, informe o intervalo e, havendo mais de uma aba, o nome da aba também.

² O campo aceita o default `{"values": [[]]}`, mas gravar um valor vazio raramente é a intenção — preencha as linhas desejadas.

![Image](https://cdn.document360.io/d1786d22-23e4-4145-98ac-accd680324d8/Images/Documentation/image(837).png)

### Variáveis nos campos

Os campos **Identificador**, **Nome da aba**, **Intervalo** e **Dados** aceitam a sintaxe `{{variavel}}`, que é resolvida com o valor da variável de sessão no momento da execução. Isso permite, por exemplo, consultar um intervalo diferente por cliente ou gravar dados coletados antes na conversa.

Também é possível usar `{{!expressão}}` para interpolar código JavaScript diretamente, no mesmo padrão dos demais campos do sistema.

## Operação “Ler dados da planilha”

1. A caixa consulta o intervalo informado na planilha.
2. Quando a resposta chega, o **Script a executar após a requisição** roda com o conteúdo em `input.response`.
3. No script, trate os dados, guarde o que for necessário em variáveis com `dialog.set(...)` e, quando quiser, use `dialog.go(...)` para direcionar a conversa.
4. Se nada for feito no script, a conversa segue para a caixa configurada em **Após a operação, vai para:** (o script gerado já inclui esse desvio).

O conteúdo lido corresponde às linhas/células do intervalo consultado. Use o modo de teste/depuração do fluxo para inspecionar `input.response` e confirmar o formato recebido antes de escrever a lógica final.

## Operação “Adicionar/atualizar planilha”

1. A caixa envia os dados JSON para a planilha.
2. O comportamento depende do checkbox **Sobrescrever dados existentes**:

| Checkbox | Comportamento |
| --- | --- |
| Desmarcado | As linhas são **adicionadas abaixo** do conteúdo atual do intervalo (append). |
| Marcado | O conteúdo do intervalo é **substituído** pelos dados enviados. |

1. A conversa segue para a caixa configurada em **Após a operação, vai para:**.

O JSON segue o formato do Google Sheets: `values` é uma lista de linhas, e cada linha é uma lista de células.

```
{
  "values": [
    ["valor A1", "valor B1", "valor C1"],
    ["valor A2", "valor B2", "valor C2"]
  ]
}
```

## Exemplos

### Exemplo 1 — Registrar cada atendimento em nova linha

**Objetivo:** ao final da coleta de dados, gravar protocolo, nome e solicitação como uma nova linha da planilha, preservando as linhas anteriores.

Configuração da caixa:

![Image](https://cdn.document360.io/d1786d22-23e4-4145-98ac-accd680324d8/Images/Documentation/image(834).png)

| Campo | Valor |
| --- | --- |
| Nome | `Registrar atendimento` |
| Identificador da planilha | `1AbCdEfGhIjKlMnOpQrStUvWxYz` |
| Nome da aba | `Atendimentos` |
| Intervalo de células | `A1:C1` |
| Operação | `Adicionar/atualizar planilha` |
| Sobrescrever dados existentes | ❌ desmarcado (adiciona abaixo) |

Dados a serem adicionados/atualizados (formato JSON):

```
{
  "values": [
    ["{{protocolo}}", "{{nomeCliente}}", "{{solicitacao}}"]
  ]
}
```

**Após a operação, vai para:** `Confirmacao registro`.

Como o checkbox fica desmarcado, cada execução acrescenta uma linha abaixo das existentes — a planilha vira um log de atendimentos.

### Exemplo 2 — Sobrescrever um painel de status

**Objetivo:** manter em `B1:B3` o status atual de três serviços, substituindo o conteúdo anterior a cada atualização.

Configuração da caixa:

![Image](https://cdn.document360.io/d1786d22-23e4-4145-98ac-accd680324d8/Images/Documentation/image(835).png)

| Campo | Valor |
| --- | --- |
| Nome | `Atualizar status` |
| Identificador da planilha | `1AbCdEfGhIjKlMnOpQrStUvWxYz` |
| Nome da aba | `Painel` |
| Intervalo de células | `B1:B3` |
| Operação | `Adicionar/atualizar planilha` |
| Sobrescrever dados existentes | ✅ marcado (substitui o intervalo) |

Dados a serem adicionados/atualizados (formato JSON):

```
{
  "values": [
    ["{{statusPortais}}"],
    ["{{statusApp}}"],
    ["{{statusTelefone}}"]
  ]
}
```

Com o checkbox marcado, o intervalo `B1:B3` passa a conter exatamente os três valores enviados.

## Validações e mensagens comuns

O salvamento da caixa verifica as seguintes situações:

| Mensagem | Motivo |
| --- | --- |
| `O campo nome não foi informado` | A caixa precisa de um nome. |
| `O campo ID da planilha não foi informado` | O **Identificador da planilha** está vazio. |
| `Deve-se informar o campo intervalo e/ou o campo de aba` | Nenhum dos dois campos foi preenchido. |
| `O arquivo de credenciais não foi informado` | A caixa não tem credenciais enviadas. |
| `Nenhuma operação foi selecionada` | Escolha uma das duas operações. |
| `Deve-se atualizar o arquivo de credenciais ao alterar o nome do elemento` | O nome da caixa mudou depois do upload das credenciais. Reenvie o arquivo. |
| `Os dados a serem adicionados/atualizados não estão em um formato válido` | O JSON dos dados é inválido ou `values` não é uma lista. |
| `Deve-se informar o campo nome antes de fazer o upload do arquivo de credenciais` | Preencha o **Nome** antes de enviar o arquivo. |
| `O arquivo de credenciais deve ser no formato ".json"` | O upload só aceita arquivo JSON. |

## Boas práticas

- Compartilhe a planilha diretamente com o e-mail da conta de serviço e dê apenas a permissão necessária: leitura para consultas, edição para gravações.
- Dê nomes funcionais às caixas, como `Consultar preco` em vez de `Planilha 1` — o nome também identifica as credenciais.
- Prefira intervalos delimitados (`A1:B200`) em vez de colunas inteiras, para reduzir leitura desnecessária.
- Ao escrever sem sobrescrever, use um intervalo de uma linha (`A1:C1`): as linhas novas são adicionadas abaixo.
- Em operações de leitura, teste o fluxo e inspecione `input.response` antes de codificar a lógica final.
- Considere o que acontece se a planilha estiver indisponível ou sem a linha esperada — trate o resultado vazio no script da leitura.
- Evite renomear a caixa depois de configurada; se renomear, atualize o arquivo de credenciais.