SHEETS_APPEND - Adicionar Linhas ao Google Sheets

O que é este Node?

O SHEETS_APPEND é o node responsável por adicionar novas linhas ao final de uma tabela existente no Google Sheets sem sobrescrever dados. Insere automaticamente após a última linha com dados.

Por que este Node existe?

Adicionar registros sequenciais é uma operação comum em automações. O SHEETS_APPEND existe para:

Registro de Eventos: Adicionar logs de atividades em ordem cronológica
Cadastro de Leads: Inserir novos contatos conforme chegam
Controle de Vendas: Registrar cada venda nova sem risco de sobrescrever
Histórico de Atendimentos: Manter timeline completo de interações

Como funciona internamente?

Quando o SHEETS_APPEND é executado, o sistema:

Autentica: Valida tokens OAuth2
Localiza última linha: Encontra automaticamente onde termina os dados
Prepara inserção: Formata values como array de arrays
Executa append: Chama spreadsheets.values.append() com valueInputOption='USER_ENTERED'
Retorna confirmação: Informa quantas células/linhas foram adicionadas
Se erro: Lança exceção detalhada

Código interno (google-executors.service.ts:784-798):

case 'append':
  const appendResult = await sheets.spreadsheets.values.append({
    spreadsheetId: data.spreadsheetId,
    range: data.range || 'Sheet1!A1',
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      values: data.values,
    },
  });

  return {
    success: true,
    updatedCells: appendResult.data.updates?.updatedCells,
    updatedRows: appendResult.data.updates?.updatedRows,
  };

Quando você DEVE usar este Node?

Use SHEETS_APPEND sempre que precisar adicionar dados ao final sem alterar existentes:

Casos de uso

Log de Atividades: "Registrar cada mensagem recebida no histórico"
Formulário de Cadastro: "Adicionar novo lead à lista de contatos"
Vendas: "Inserir nova venda na planilha de controle"
Atendimentos: "Registrar cada ticket de suporte sequencialmente"
Auditoria: "Manter log de todas as ações realizadas"

Quando NÃO usar SHEETS_APPEND

Atualizar registro existente: Use NODE SHEETS_WRITE ou SHEETS_UPDATE
Posição específica: Use NODE SHEETS_WRITE com range definido
Limpar dados: Use NODE SHEETS_CLEAR

Parâmetros

Campo	Tipo	Obrigatório	Descrição
operation	string	Sim	Deve ser "append"
spreadsheetId	string	Sim	ID da planilha Google Sheets
range	string	Não	Range base (padrão: Sheet1!A1)
values	array	Sim	Array de arrays com linhas a adicionar
accessToken	string	Sim	Token OAuth2 de acesso
refreshToken	string	Sim	Token OAuth2 de atualização

Exemplo 1: Registrar Novo Lead

Objetivo: Adicionar lead capturado via WhatsApp na planilha CRM

JSON para Importar

{
  "name": "CRM - Registrar Novo Lead",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "prompt": "Qual seu nome?",
          "variableName": "nome"
        }
      }
    },
    {
      "id": "input_2",
      "type": "email_input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "prompt": "Qual seu email?",
          "variableName": "email"
        }
      }
    },
    {
      "id": "input_3",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "prompt": "Qual seu telefone?",
          "variableName": "telefone"
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Salvar Lead",
        "parameters": {
          "operation": "append",
          "spreadsheetId": "1CRM_Leads_XYZ",
          "range": "Leads!A1",
          "values": [
            ["{{nome}}", "{{email}}", "{{telefone}}", "{{NOW}}", "WhatsApp", "Novo"]
          ],
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Cadastro realizado com sucesso, {{nome}}!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "input_3" },
    { "source": "input_3", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual seu nome?
Usuário: José Silva
Sistema: Qual seu email?
Usuário: jose@email.com
Sistema: Qual seu telefone?
Usuário: 11987654321
Sistema: ✅ Cadastro realizado com sucesso, José Silva!

Exemplo 2: Log de Mensagens Recebidas

Objetivo: Registrar cada mensagem em log para auditoria

JSON para Importar

{
  "name": "Auditoria - Log de Mensagens",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Preparar Log",
        "parameters": {
          "variableName": "log_entry",
          "value": [
            ["{{NOW}}", "{{user_phone}}", "{{user_message}}", "Recebida", "{{flow_id}}"]
          ]
        }
      }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Registrar no Log",
        "parameters": {
          "operation": "append",
          "spreadsheetId": "1Audit_Log_XYZ",
          "range": "MessageLog!A1",
          "values": "{{log_entry}}",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Processar",
        "parameters": {
          "message": "Mensagem registrada. Como posso ajudar?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Mensagem registrada. Como posso ajudar?

Resposta do Node

{
  "success": true,
  "updatedCells": 6,
  "updatedRows": 1
}

Boas Práticas

✅ SIM:

Use append para adicionar registros sequenciais
Mantenha estrutura consistente (mesmo número de colunas)
Adicione timestamp para rastreabilidade
Use primeira linha como cabeçalho (append ignora automaticamente)

❌ NÃO:

Não use append para atualizar dados existentes
Não esqueça de incluir todos os campos esperados
Não adicione linhas vazias desnecessárias

Dicas

💡 Dica 1: O range em append define a área de busca, mas a inserção sempre ocorre após a última linha com dados.

💡 Dica 2: Ideal para formulários e captura de dados onde cada entrada é um novo registro.

💡 Dica 3: Combine com timestamp ({{NOW}}) para criar logs cronológicos perfeitos.

Próximo Node

→ SHEETS_WRITE - Escrever em posição específica → SHEETS_UPDATE - Atualizar células existentes → SHEETS_CLEAR - Limpar dados