N8n Workflow

---
name: n8n-workflow
description: "N8N Workflow — Skill especializada para n8n workflow"
license: MIT
metadata:
  version: 1.0.0
  author: Cafe Code AI
  category: 12-ia-automacao
  updated: 2026-03-01
risk: safe
---

# N8N Workflow

Esta skill capacita o Claude a projetar, configurar e depurar workflows complexos no n8n, utilizando nós específicos, expressões e manipulação de dados para automações robustas.

---

## Keywords

n8n, workflow automation, nós, expressões, webhook, HTTP request, Function, data transformation, credentials, error handling, cron, queue, sub-workflow, triggers, nodes, flows.

---

## Quick Start

1.  **Instalação e Acesso**: Garanta que o n8n esteja instalado (Docker é recomendado: `docker run -it --rm --name n8n -p 5678:5678 -v ~/.n8n:/home/node/.n8n n8nio/n8n`). Acesse a interface web em `http://localhost:5678`.
2.  **Criação do Primeiro Workflow**: No dashboard, clique em "New Workflow". Arraste um nó `Webhook` para a tela, configure o método POST e salve para obter a URL de teste.
3.  **Adição de Nó de Processamento**: Conecte um nó `Function` ao `Webhook`. Dentro do nó `Function`, insira um código JavaScript simples como `return [{json: {message: 'Webhook recebido com sucesso!', data: $json}}];` para manipular os dados de entrada.
4.  **Teste e Execução**: Envie um POST request para a URL do Webhook (ex: `curl -X POST -H "Content-Type: application/json" -d '{"nome": "Maria", "email": "maria@exemplo.com"}' SEU_WEBHOOK_URL`). Observe os dados fluindo pelos nós no painel de execução do n8n.
5.  **Ativação do Workflow**: Após testar e validar o fluxo, ative o workflow usando o toggle no canto superior direito para que ele comece a processar requisições em produção.

---

## Core Workflows

### Workflow 1: Captura de Leads via Webhook e Envio para Google Sheets e Slack

Este workflow automatiza a captura de leads de um formulário web (via webhook) e os registra em uma planilha Google Sheets, além de enviar uma notificação em tempo real para um canal do Slack.

**Passos Detalhados:**

1.  **Trigger `Webhook`**:
    *   **Configuração**: Arraste um nó `Webhook` para a tela.
    *   **Method**: Selecione `POST`.
    *   **Authentication**: `None` (para formulários simples) ou `Header Auth` se o formulário enviar um token.
    *   **Path**: `lead-form`.
    *   **Teste**: Salve o workflow. A URL de teste será algo como `https://your.n8n.url/webhook-test/lead-form`.
    *   **Exemplo de Payload de Entrada**:
        ```json
        {
          "nome": "João Silva",
          "email": "joao.silva@empresa.com",
          "telefone": "+5511987654321",
          "origem": "Landing Page X"
        }
        ```

2.  **Node `Google Sheets` (Append Row)**:
    *   **Conexão**: Conecte o nó `Google Sheets` ao nó `Webhook`.
    *   **Credentials**: Adicione uma nova credencial `Google Sheets API`. Siga os passos de autenticação OAuth2 (crie um projeto no Google Cloud Console, habilite a Google Sheets API, gere credenciais de cliente OAuth e configure no n8n).
    *   **Operation**: Selecione `Append Row`.
    *   **Spreadsheet ID**: Cole o ID da sua planilha Google Sheets (ex: `1ABCDEFG_HIJKLMNOPQRSTUVWXYZ1234567890`).
    *   **Sheet Name**: `Leads` (certifique-se de que a aba exista).
    *   **Data to Append**: Use expressões para mapear os dados do webhook para as colunas.
        *   `Nome da Coluna 1`: `{{$json.nome}}`
        *   `Nome da Coluna 2`: `{{$json.email}}`
        *   `Nome da Coluna 3`: `{{$json.telefone}}`
        *   `Nome da Coluna 4`: `{{$json.origem}}`
        *   `Data de Registro`: `{{new Date().toISOString()}}`

3.  **Node `Slack` (Send Message)**:
    *   **Conexão**: Conecte o nó `Slack` ao nó `Google Sheets` (ou diretamente ao `Webhook` se a ordem não importar).
    *   **Credentials**: Adicione uma nova credencial `Slack API`. Gere um token de bot no painel de apps do Slack e configure no n8n.
    *   **Channel**: `#leads-novo` (ou o ID do canal).
    *   **Text**: Crie uma mensagem formatada.
        ```
        Novo Lead Capturado! 🚀
        Nome: {{$json.nome}}
        Email: {{$json.email}}
        Telefone: {{$json.telefone}}
        Origem: {{$json.origem}}
        ```

### Workflow 2: Monitoramento de Disponibilidade de Produto e Notificação Telegram

Este workflow verifica a disponibilidade de um produto em um e-commerce a cada hora e envia uma notificação via Telegram se o produto estiver de volta ao estoque.

**Passos Detalhados:**

1.  **Trigger `Cron`**:
    *   **Configuração**: Arraste um nó `Cron` para a tela.
    *   **Mode**: `Every X`.
    *   **Value**: `1`.
    *   **Unit**: `Hours`.
    *   **Start Hour**: `0` (começa à meia-noite).
    *   **End Hour**: `23` (termina às 23h).

2.  **Node `HTTP Request` (GET para API do Produto)**:
    *   **Conexão**: Conecte o nó `HTTP Request` ao nó `Cron`.
    *   **URL**: `https://api.ecommerce.com/products/SKU12345` (substitua pela URL real da API ou página a ser scrapeada).
    *   **Method**: `GET`.
    *   **Send Headers**: `User-Agent: n8n-monitor/1.0` (boa prática).
    *   **Response Format**: `JSON`.
    *   **Exemplo de Resposta (supondo JSON):**
        ```json
        {
          "product_id": "SKU12345",
          "name": "Smartphone XYZ",
          "price": 999.99,
          "availability": "out_of_stock",
          "last_updated": "2023-10-26T10:00:00Z"
        }
        ```

3.  **Node `Function` (Lógica de Verificação)**:
    *   **Conexão**: Conecte o nó `Function` ao nó `HTTP Request`.
    *   **Código JavaScript**:
        ```javascript
        const previousAvailability = this.getWorkflowStaticData('productAvailability') || 'unknown';
        const currentAvailability = items[0].json.availability;
        const productName = items[0].json.name;

        if (currentAvailability === 'in_stock' && previousAvailability !== 'in_stock') {
          this.setWorkflowStaticData('productAvailability', 'in_stock');
          return [{ json: { message: `${productName} está AGORA em estoque!`, status: 'in_stock' } }];
        } else if (currentAvailability === 'out_of_stock' && previousAvailability !== 'out_of_stock') {
          this.setWorkflowStaticData('productAvailability', 'out_of_stock');
          // Opcional: notificar quando esgotar
          // return [{ json: { message: `${productName} esgotou.`, status: 'out_of_stock' } }];
        } else {
          // Não houve mudança de estado relevante para notificação
          return []; // Retorna vazio para não prosseguir no workflow
        }
        ```
    *   **Explicação**: Este nó usa `workflowStaticData` para persistir o estado de disponibilidade entre execuções. Ele só passa o item adiante se houver uma mudança de "fora de estoque" para "em estoque".

4.  **Node `Telegram` (Send Message)**:
    *   **Conexão**: Conecte o nó `Telegram` ao nó `Function`.
    *   **Credentials**: Adicione uma nova credencial `Telegram API`. Crie um bot via BotFather, obtenha o token e o chat ID do usuário/grupo.
    *   **Chat ID**: `YOUR_CHAT_ID` (ex: `-1001234567890` para grupo, ou ID do seu usuário).
    *   **Text**: `{{$json.message}}` (utiliza a mensagem gerada pelo nó Function).

---

## Templates

### Template: Webhook para Envio de Mensagem Discord

```json
{
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "discord-message",
        "options": {}
      },
      "name": "Webhook Lead",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [640, 300]
    },
    {
      "parameters": {
        "channel": {
          "__rl": true,
          "value": "123456789012345678",
          "mode": "id"
        },
        "text": "Novo lead capturado via webhook!\nNome: {{$json.leadName}}\nEmail: {{$json.leadEmail}}\nEmpresa: {{$json.companyName}}",
        "options": {}
      },
      "name": "Discord Send Message",
      "type": "n8n-nodes-base.discord",
      "typeVersion": 1,
      "position": [900, 300],
      "credentials": {
        "discordApi": {
          "id": "YOUR_DISCORD_CREDENTIAL_ID",
          "name": "Discord Bot"
        }
      }
    }
  ],
  "connections": {
    "Webhook Lead": {
      "main": [
        [
          {
            "node": "Discord Send Message",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}
```
**Como usar**: Importe este JSON no n8n. Configure suas credenciais do Discord Bot (com permissão para enviar mensagens no canal desejado). A URL do webhook será `https://your.n8n.url/webhook-test/discord-message`. Envie um POST com payload `{"leadName": "Alice", "leadEmail": "alice@exemplo.com", "companyName": "TechCorp"}`.

### Template: Função JavaScript para Filtragem e Transformação de Dados

```javascript
// Recebe um array de itens do nó anterior
const items = $input.all();
const outputItems = [];

for (const item of items) {
  const originalData = item.json;

  // Exemplo 1: Filtrar itens com base em uma condição
  if (originalData.status === 'completed' && originalData.value > 100) {
    // Exemplo 2: Transformar e adicionar novos campos
    outputItems.push({
      json: {
        id: originalData.id,
        description: `Processo ${originalData.name} finalizado.`,
        finalValue: originalData.value * 1.05, // Adiciona 5%
        processedAt: new Date().toISOString()
      }
    });
  }
}

// Retorna o array de itens transformados
return outputItems;
```
**Como usar**: Insira este código em um nó `Function`. Ele processará itens de entrada (espera `id`, `name`, `status`, `value`), filtrará por `status === 'completed'` e `value > 100`, e transformará os dados adicionando `description`, `finalValue` e `processedAt`.

---

## Checklist

- [x] Credenciais sensíveis configuradas com segurança (ex: usar Secrets, não valores hardcoded).
- [x] Testes de execução manual para cada nó do workflow.
- [x] Tratamento de erros configurado (nó `Error Workflow` ou `Continue On Error` nos nós relevantes).
- [x] Utilização de expressões para dinâmica de dados (`{{$json.campo}}`, `{{$node["Nome do Nó"].json.resultado}}`).
- [x] Workflow ativado somente após validação completa em ambiente de teste.
- [x] Monitoramento de logs e execuções para identificar falhas rapidamente.
- [x] Otimização de nós `Function` para evitar sobrecarga de memória em grandes datasets.
- [x] Documentação interna dos workflows complexos com `Notes` para facilitar manutenção.
- [x] Uso de `Set` e `Merge` para manipular a estrutura de dados de forma eficiente.
- [x] Consideração de concorrência e idempotência para webhooks e triggers recorrentes.

---

## Métricas de Referência

| Métrica                      | Benchmark (Ideal) | Meta (Aceitável) |
|------------------------------|-------------------|------------------|
| Latência Média de Execução   | < 500 ms          | < 2000 ms        |
| Taxa de Sucesso do Workflow  | > 99.5%           | > 98%            |
| Consumo de Memória por Exec. | < 256 MB          | < 512 MB         |
| Execuções/Minuto (Webhook)   | > 100             | > 50             |
| Erros de Credenciais/API    | 0%                | < 0.1%           |
| Tempo de Resolução de Erro   | < 30 min          | < 60 min         |

---

## Erros Comuns

1.  **Credenciais Inválidas ou Expiradas**: Ao configurar um nó como `Google Sheets` ou `Slack`, as credenciais OAuth podem expirar ou ter permissões insuficientes.
    *   **Como evitar**: Sempre verificar as permissões no provedor de serviço (Google Cloud Console, Slack Apps) e reautenticar as credenciais no n8n se necessário. Use credenciais com escopo mínimo necessário.
2.  **JSON Malformado em `HTTP Request` ou `Webhook`**: Dados de entrada com chaves ou valores incorretos, ou corpo da requisição não sendo um JSON válido quando esperado.
    *   **Como evitar**: Utilize o painel "Test Webhook" ou "Execute Node" para inspecionar a entrada. Use o nó `JSON` para parsear strings e `Set` para formatar JSON de saída. Valide o payload com ferramentas como `jsonlint.com`.
3.  **Expressões Incorretas ou Caminhos de Dados Ausentes**: Tentar acessar `{{$json.campoInexistente}}` ou `{{$node["Nó que Falhou"].json.dado}}` quando o nó anterior não produziu o dado esperado.
    *   **Como evitar**: Verifique a saída do nó anterior no painel de execução. Use `try...catch` em nós `Function` para lidar com dados ausentes e `IF` para criar branches condicionais baseadas na existência de dados. Use o `dot notation` ou `bracket notation` corretamente, e teste as expressões no editor de expressões do n8n.

---

## Dicas Avançadas

1.  **Orquestração de Sub-Workflows com `Execute Workflow`**: Para workflows complexos e modularização, crie sub-workflows que realizam tarefas específicas (ex: validação de dados, envio de notificação genérica). O nó `Execute Workflow` permite chamar esses sub-workflows, passando dados de entrada e recebendo resultados, mantendo o workflow principal mais limpo e reutilizável.
    *   **Exemplo**: Um workflow `ProcessarPagamento` pode chamar um sub-workflow `EnviarEmailConfirmacao` e `AtualizarEstoque` sequencialmente, cada um com sua própria lógica e tratamento de erros encapsulados.
2.  **Persistência de Dados entre Execuções com `Workflow Static Data`**: O objeto `this.getWorkflowStaticData()` e `this.setWorkflowStaticData()` dentro de um nó `Function` permite armazenar pequenas quantidades de dados que persistem entre as execuções do workflow. Ideal para contadores, estados de máquina, ou valores de referência (como o preço monitorado no exemplo do Telegram).
    *   **Exemplo de Uso**: `this.setWorkflowStaticData('lastRunTimestamp', new Date().toISOString());` para saber quando foi a última execução bem-sucedida para lógica de retry customizada.
3.  **Manipulação de Arrays com `Split In Batches` e `Item Lists`**: Ao lidar com grandes volumes de dados ou arrays complexos, os nós `Split In Batches` e `Item Lists` são cruciais. `Split In Batches` divide um array em pacotes menores para processamento paralelo ou sequencial, evitando timeouts. `Item Lists` permite adicionar, remover ou obter itens de arrays.
    *   **Exemplo**: Dividir uma lista de 1000 emails em batches de 50 para enviar via API de email, controlando limites de taxa.
4.  **Uso de `Webhook Response` para Feedback Síncrono**: Em workflows iniciados por `Webhook`, o nó `Webhook Response` é essencial para enviar uma resposta HTTP de volta ao serviço que disparou o webhook. Você pode configurar o status code (ex: 200, 400), headers e o corpo da resposta (JSON, texto).
    *   **Exemplo**: Após receber um pedido, retornar um `200 OK` com `{"status": "received", "orderId": "XYZ123"}`. Se houver falha na validação, retornar `400 Bad Request` com `{"error": "invalid_data"}`.
5.  **Variáveis de Ambiente para Configurações Dinâmicas**: Utilize variáveis de ambiente no n8n para gerenciar URLs de API, chaves públicas, ou outras configurações que mudam entre ambientes (desenvolvimento, staging, produção). Acesse-as via `{{$env.MY_VARIABLE_NAME}}` nas configurações dos nós.
    *   **Exemplo**: Em vez de hardcodar a URL de uma API, use `{{$env.CRM_API_URL}}`. O valor será injetado do arquivo `.env` do seu n8n.