N8N

Filosofia: fluxo vs código

O N8N é uma ferramenta de automação de workflows com interface visual — você conecta nodes (nós) em um canvas, define gatilhos e deixa o fluxo rodar sozinho. É o equivalente open-source do Zapier ou do Make, mas que você instala e controla no seu próprio servidor.

Roda na nuvem deles.
Você paga por execução.
Dados passam por servidores deles.
Limite de steps/mês.
Sem acesso ao código interno.

Roda no seu VPS.
Sem custo por execução.
Dados ficam no seu servidor.
Ilimitado (memória é o limite).
Código aberto, extensível.

Quando o N8N faz sentido?

• Integrar sistemas sem API nativa em comum (ex.: CRM + Planilha + Slack)
• Automatizar tarefas repetitivas sem escrever scripts avulsos
• Substituir webhooks manuais por fluxos visuais com tratamento de erro
• Monitorar APIs externas e reagir a eventos (preço, status, novo item)
• Processar dados em lote com agendamento (substituindo cron + PHP)
• Proteger dados sensíveis — tudo permanece no seu servidor

Instalação

O N8N pode ser instalado de três formas. Para um VPS Ubuntu com NGINX, o Docker é o caminho recomendado — isola o processo, facilita updates e não conflita com o PHP-FPM da stack existente.

Via Docker (recomendado para VPS)

1. Instalar Docker se ainda não tiver

2. Criar volume para persistir dados

3. Rodar o container

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 127.0.0.1:5678:5678 \
  -e N8N_HOST=n8n.seudominio.com \
  -e N8N_PORT=5678 \
  -e N8N_PROTOCOL=https \
  -e WEBHOOK_URL=https://n8n.seudominio.com/ \
  -e GENERIC_TIMEZONE=America/Belem \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Via npm (sem Docker)

Para desenvolvimento local (rápido)

Abre em http://localhost:5678. Dados ficam em ~/.n8n.

Verificar se está rodando

Resposta esperada: {"status":"ok"}

Interface

Ao abrir o N8N pela primeira vez, você cria uma conta local (admin). A interface tem três áreas principais:

Ações essenciais no canvas

Conceitos essenciais

Workflow

Um workflow é um fluxo de automação salvo. Ele começa com um trigger (gatilho) e encadeia nodes até completar a tarefa. Um workflow pode estar ativo (roda automaticamente) ou inativo (só executa manualmente).

Node

Cada bloco no canvas é um node. Ele recebe dados, processa, e passa adiante. Há três tipos:

• Trigger nodes — iniciam o workflow (Webhook, Cron, evento de API…)
• Action nodes — fazem algo (HTTP Request, enviar e-mail, gravar arquivo…)
• Logic nodes — controlam o fluxo (IF, Switch, Loop, Merge…)

Item

A unidade de dados que flui entre nodes. Um node pode produzir um item (um registro) ou vários (uma lista). O próximo node recebe todos os itens e processa cada um.

# Estrutura de um item
{
  "json": {
    "nome": "Daniel",
    "email": "daniel@exemplo.com"
  }
}

Execução

Cada vez que o workflow roda é uma execução. O N8N guarda o histórico de execuções com status (sucesso/erro), tempo e dados de cada etapa. Acesse em Executions na sidebar.

Trigger vs. Polling

Nodes essenciais

O N8N tem mais de 400 integrações. Conhecer os nodes fundamentais permite construir qualquer automação — o resto é só configuração específica de serviço.

Node HTTP Request — o mais importante

Conecta o N8N a qualquer API. Configurações principais:

Node Code — JavaScript nativo

Quando os nodes visuais não bastam, use o node Code. Dois modos:

// Recebe todos os itens de uma vez
const items = $input.all();
const result = items.map(item => ({
  json: {
    nome: item.json.name.toUpperCase(),
    total: item.json.qty * item.json.price
  }
}));
return result;

// Roda uma vez por item
// $input.item é o item atual
const nome = $input.item.json.name;
const preco = $input.item.json.price;

return {
  json: {
    resumo: `${nome}: R$ ${preco}`
  }
};

Expressões

Expressões permitem usar dados dinâmicos em qualquer campo de qualquer node. A sintaxe é {{ expressão }} e usa JavaScript dentro das chaves duplas.

Acessar dados do node anterior

# Item atual (saída do node imediatamente anterior)
{{ $json.campo }}
{{ $json.objeto.campo_aninhado }}
{{ $json.lista[0] }}

# Todos os itens do node anterior
{{ $input.all() }}
{{ $input.first().json.campo }}
{{ $input.last().json.campo }}

Referenciar nodes específicos por nome

# Acessa a saída de um node com nome exato
{{ $('Nome do Node').item.json.campo }}
{{ $('Nome do Node').all() }}
{{ $('Nome do Node').first().json.email }}

Variáveis de contexto

Exemplos práticos

# Formatar data
{{ $now.toFormat('dd/MM/yyyy') }}
{{ $now.minus({ days: 1 }).toISO() }}

# Concatenar texto
{{ 'Olá, ' + $json.nome + '!' }}
{{ `Pedido #${$json.id} — R$ ${$json.total.toFixed(2)}` }}

# Condicional inline
{{ $json.status === 'ativo' ? 'Ativo' : 'Inativo' }}

# Tratar valor nulo
{{ $json.email ?? 'sem-email@exemplo.com' }}

# Acessar campo com espaço no nome
{{ $json['nome completo'] }}

Credenciais

Credenciais armazenam chaves de API, senhas e tokens de forma criptografada. Você configura uma vez e reutiliza em qualquer node sem expor os valores nos workflows.

Criar uma credencial

Tipos comuns de credencial

Self-hosting com NGINX

Com o container rodando em 127.0.0.1:5678, configure o NGINX como proxy reverso para expor o N8N num subdomínio com HTTPS.

/etc/nginx/sites-available/n8n

server {
    listen 80;
    server_name n8n.seudominio.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name n8n.seudominio.com;

    # Gerenciado pelo Certbot:
    ssl_certificate     /etc/letsencrypt/live/n8n.seudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/n8n.seudominio.com/privkey.pem;
    include             /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam         /etc/letsencrypt/ssl-dhparams.pem;

    # Tamanho máximo do body — útil para workflows com uploads
    client_max_body_size 50M;

    location / {
        proxy_pass         http://127.0.0.1:5678;
        proxy_http_version 1.1;

        # WebSockets — necessário para o editor do N8N
        proxy_set_header   Upgrade    $http_upgrade;
        proxy_set_header   Connection 'upgrade';

        proxy_set_header   Host       $host;
        proxy_set_header   X-Real-IP  $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;

        # Timeout maior para workflows longos
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

Ativar o site e emitir certificado

Proteger com autenticação básica (opcional)

Se quiser uma camada extra de proteção antes do login do N8N:

Adicione dentro do bloco location /:

auth_basic           "N8N";
auth_basic_user_file /etc/nginx/.htpasswd;

Location para webhooks sem auth

location /webhook/ {
    proxy_pass         http://127.0.0.1:5678;
    proxy_http_version 1.1;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    # Sem auth_basic aqui
}

Comandos essenciais

Atualizar para nova versão

Rode novamente o comando docker run da instalação — o volume n8n_data preserva todos os workflows e credenciais.

Backup dos dados

Os dados ficam no volume Docker. Para exportar:

Para restaurar:

Exportar/importar workflows via CLI

# Exportar todos os workflows para JSON
docker exec n8n n8n export:workflow --all --output=/tmp/workflows.json
docker cp n8n:/tmp/workflows.json ./workflows.json

# Importar workflows de um arquivo
docker cp ./workflows.json n8n:/tmp/workflows.json
docker exec n8n n8n import:workflow --input=/tmp/workflows.json

Fluxo de trabalho recomendado

# 1. Criar e testar o workflow no editor visual
# 2. Ativar o toggle "Active" quando pronto
# 3. Monitorar as primeiras execuções
docker logs n8n -f --since=10m

# 4. Verificar execuções com erro na interface
#    Workflows → Executions → filtrar por "Error"

# 5. Fazer backup antes de atualizações
docker exec n8n n8n export:workflow --all --output=/tmp/backup.json

Referência geral

Expressões — cola rápida

Nodes por categoria

Variáveis de ambiente do container