Automação com n8n: onde ele brilha e onde eu prefiro escrever código

O n8n é uma plataforma de automação visual baseada em nós: você liga caixas que representam APIs, bancos de dados, serviços de mercado e modelos de IA, e o fluxo resultante roda sozinho. Apresentei a ferramenta em grupo na disciplina de Fundamentos de Sistemas de Informação, na UDESC, e uso o n8n no trabalho, em integrações com parceiros de logística.

Este artigo junta as duas coisas: o que a ferramenta é, e o critério que eu uso para decidir quando ela é a resposta certa.

Gatilho, nó, ação

Todo fluxo no n8n tem a mesma anatomia em três partes.

• Gatilho: o evento que inicia o fluxo. Uma chamada de webhook, um e-mail recebido, uma linha nova numa planilha, um horário.
• Nós: as etapas intermediárias. Consultas em banco, filtros, condicionais, transformações de dados, chamadas HTTP.
• Ações: o resultado. Enviar uma mensagem, cadastrar um cliente, atualizar um registro.

Um exemplo que usamos na apresentação: um cliente envia um e-mail, um nó de código classifica a mensagem, um nó de IA gera um rascunho de resposta, um nó de PostgreSQL grava o registro e um nó do Slack avisa o time. Cinco nós, nenhuma pessoa no meio.

O que diferencia o n8n

• Self-hosting: a versão Community roda em Docker na sua infraestrutura, sem custo de licença, e os dados não saem da empresa. Existe também a versão Cloud, paga por execução.
• Low-code e pro-code no mesmo lugar: quem não programa arrasta nós; quem programa escreve JavaScript ou Python dentro de um nó, sem sair do fluxo.
• IA como nó: agentes, memória e bancos vetoriais entram no fluxo como qualquer outra etapa.
• Histórico de execuções: cada execução fica registrada com a entrada e a saída de cada nó, e pode ser repetida.

Como eu uso no trabalho

Na Alva, o fluxo de faturamento do Alva Tools é um kanban que acompanha cada pedido até a expedição. Quando um pedido chega na etapa de separação, o back-end Django não fala direto com o sistema do operador logístico: ele chama um webhook do n8n, e o fluxo do n8n faz a conversa com o parceiro.

def solicitar_separacao(pedido: Pedido) -> None:
    payload = {
        "pedido_id": str(pedido.id),
        "numero": pedido.numero,
        "itens": [{"sku": i.sku, "quantidade": i.quantidade} for i in pedido.itens.all()],
    }
    resposta = requests.post(
        settings.N8N_SEPARACAO_WEBHOOK,
        json=payload,
        headers={"X-Idempotency-Key": f"separacao:{pedido.id}"},
        timeout=15,
    )
    resposta.raise_for_status()
    pedido.registrar_evento("separacao_solicitada", resposta.json())

A divisão de responsabilidade é deliberada. O Django é dono da regra de negócio: quando um pedido pode ir para a separação, o que acontece se falhar, o histórico. O n8n é dono da cola com o parceiro: formato do arquivo, autenticação, os detalhes que mudam quando o parceiro muda alguma coisa do lado dele.

Fluxo no n8n ou código no back-end?

Depois de algum tempo usando os dois, o critério ficou mais ou menos este:

Cuidados que ninguém conta no tutorial

• Versione os fluxos. Um fluxo editado direto na tela não tem histórico de mudanças. Exporte o JSON e guarde no repositório junto com o código que chama o fluxo.
• Configure um fluxo de erro. O n8n permite apontar um workflow que roda quando outro falha. Sem isso, falhas ficam silenciosas até alguém perguntar por que o pedido não andou.
• Idempotência continua sendo sua. Se o back-end reenviar a chamada depois de um timeout, o fluxo vai rodar duas vezes. Por isso o exemplo acima manda uma chave de idempotência no cabeçalho.
• Webhooks precisam de autenticação. Uma URL de webhook pública sem verificação é uma porta aberta para qualquer um disparar o fluxo.
• Credenciais ficam no n8n, não nos nós. Use o cofre de credenciais da ferramenta em vez de colar tokens em nós de código.

Se você quer ver o outro lado dessa história, as filas e o reprocessamento que ficam no código, escrevi sobre isso em Filas que falham bem, também aqui no blog.