N8N como camada de orquestração — além do "conecta isso aqui"

A maioria das pessoas descobre N8N assim: “preciso mandar um email quando alguém preenche um formulário”. Conecta dois nodes, funciona, feliz.

Depois de um tempo trabalhando com N8N em produção, em sistemas reais com volume real, aprendi que essa ferramenta é capaz de muito mais — e também que ela tem limites sérios que vão te morder se você não souber onde estão.

Esse post é sobre o N8N que vai além do tutorial. Arquitetura, decisões que tomei, erros que cometi e o que ficou de lição.

Separar o determinístico do não-determinístico

O maior salto de qualidade que tive usando N8N veio de uma regra simples que passei a aplicar em tudo:

Lógica determinística vai pro backend. Lógica não-determinística vai pro N8N.

Parece óbvio quando escrito assim, mas na prática você vai ser tentado a colocar tudo num lugar só — especialmente quando o N8N parece tão conveniente pra tudo.

O que entra em cada lado:

Backend (determinístico):

  • Validação de dados
  • Regras de negócio com resultado previsível
  • Persistência
  • Cálculos financeiros
  • Controle de acesso

N8N (não-determinístico / orquestração):

  • Chamadas a LLMs e IA
  • Integração com APIs externas que podem falhar
  • Pipelines de processamento de documentos
  • Roteamento baseado em contexto semântico
  • Workflows com retries e fallbacks complexos
  • Tudo que precisa de visibilidade de execução

Essa separação tem uma consequência importante: o backend não sabe que o N8N existe. Ele expõe uma API, o N8N consome. Se amanhã eu precisar trocar o N8N por outra coisa, o backend não muda.

A arquitetura que funciona na prática

Depois de muitas iterações, cheguei num padrão que funciona bem:

Cliente / Evento externo
        ↓
   [Webhook N8N]
        ↓
  Roteador central  ←── decide qual sub-workflow chamar
        ↓
  Sub-workflow A / B / C
        ↓
  API do backend (POST /processar)
        ↓
   Resposta → notificação / próximo passo

A chave aqui é o roteador central. Em vez de ter um workflow gigante com mil branches, tenho um workflow pequeno que só decide pra onde ir e chama o sub-workflow correto via Execute Workflow.

Vantagens:

  • Cada sub-workflow pode ser testado isoladamente
  • Quando um quebra, o erro é localizado
  • Fácil de adicionar novos tipos sem mexer no fluxo principal

Gotchas que ninguém conta no tutorial

1. HTTP Request não faz fan-out

Esse foi caro. Se você tem um array de items e manda pro HTTP Request node, ele processa só o primeiro item.

❌ array de 50 items → HTTP Request → processa 1
✅ array de 50 items → Split In Batches → HTTP Request → processa todos

Sempre que precisar iterar sobre uma lista e fazer uma chamada HTTP pra cada item, use Split In Batches antes.

2. Pin data não funciona com Cron

Pra testar um workflow com trigger manual, você pode “pinar” dados de teste. Problema: isso não funciona quando o trigger é um Cron ou Webhook em produção. O N8N usa os dados reais nesses casos.

A solução que uso: desabilito o trigger de produção, adiciono um Manual Trigger temporário pro teste, e removo depois. Parece trabalhoso mas evita surpresas.

3. Memory nodes poluem contextos compartilhados

Se você usa Window Buffer Memory ou outros nodes de memória em mais de um workflow que rodam próximos, eles podem se misturar dependendo de como você configura o session_id.

Aprendi da forma difícil quando um workflow de resumo diário começou a incluir contexto de conversas de suporte de outros flows. A solução: sempre use um session_id único e explícito por tipo de workflow, nunca deixe o padrão.

4. Erros silenciosos em sub-workflows

Quando você chama um sub-workflow via Execute Workflow e ele falha internamente, o workflow pai recebe o erro — mas dependendo de como você trata, ele pode continuar executando como se tudo estivesse bem.

Sempre adicione um If node após cada Execute Workflow para verificar se a resposta contém erro antes de continuar.

N8N e LLM

O caso de uso que mais me impressionou foi usar N8N como orquestrador de pipelines de IA. Em vez de rodar LLMs direto no backend (o que cria acoplamento e custo de infraestrutura), o N8N fica no meio:

Documento entra
      ↓
Extrai texto (Code node)
      ↓
Chama Gemini Flash pra classificação
      ↓
  Se confiança > 0.9 → processa automaticamente
  Se confiança < 0.9 → fila para revisão humana
      ↓
POST no backend com resultado + metadados

O que isso dá:

  • Visibilidade total: cada execução fica logada no N8N com input, output e duração
  • Retry sem código: se o Gemini retornar erro temporário, o N8N tenta de novo automaticamente
  • Troca de modelo sem deploy: quero testar Claude em vez de Gemini? Troco o node, sem tocar no backend
  • Threshold ajustável: o 0.9 de confiança pode mudar num campo, sem redeploy

Quando NÃO usar N8N

N8N não é bala de prata. Tem casos onde ele atrapalha mais do que ajuda:

Alta frequência: N8N não foi feito pra processar milhares de eventos por segundo. Se você tem um endpoint que recebe 500 requests por minuto, o N8N vai ser um gargalo. Use uma queue (Redis, RabbitMQ) com workers direto.

Lógica de negócio complexa: Se o workflow tem 50 nodes com muita lógica de if/else aninhada, você perdeu o benefício da visibilidade. Nesse ponto é melhor código testável.

Transações críticas: N8N não tem transações atômicas. Se você precisa que A e B aconteçam juntos ou não aconteça nenhum, isso é trabalho pro banco de dados, não pro N8N.

O que organiza um N8N de verdade

Depois de um número alto de workflows, a organização se torna o maior desafio. O que funciona:

Pastas por domínio: agrupe workflows por área (financeiro, comunicação, dados, IA). Não por tipo de trigger.

Nomenclatura consistente: eu uso [DOMÍNIO] Descrição do que faz. Ex: [FINANCEIRO] Concilia NF com banco ou [IA] Classifica documento entrada.

Sub-workflows para lógica reutilizada: se você perceber que copiou o mesmo trecho de nodes mais de uma vez, extraia pra um sub-workflow.

Documentação no sticky note: cada workflow complexo tem um Sticky Note no início explicando o que faz, quando é acionado e o que produz. Futuramente você vai agradecer.

Conclusão

N8N é uma das ferramentas mais versáteis que tenho na stack — mas só depois que parei de tratá-lo como “ferramenta de automação simples” e comecei a tratá-lo como camada de orquestração de sistemas.

A separação determinístico/não-determinístico foi o maior aprendizado. O backend fica limpo e testável. O N8N fica com a complexidade de integração e IA. Cada coisa no seu lugar.

Se você está começando com N8N, invista tempo entendendo os limites antes de depender dele em produção. Os gotchas existem — mas são contornáveis quando você sabe onde estão.