O Poder das Expressões JavaScript Dinâmicas no N8N
A automação de fluxos de trabalho, quando feita corretamente, transforma processos manuais e repetitivos em pipelines eficientes e escaláveis. No ecossistema do n8n, a maioria dos usuários inicia sua jornada arrastando nós (nodes) e conectando-os visualmente. No entanto, para alcançar o verdadeiro potencial da plataforma, é indispensável dominar as expressões dinâmicas. Elas permitem que seus workflows deixem de ser estáticos e se adaptem em tempo real aos dados recebidos, criando integrações verdadeiramente inteligentes.
Muitos desenvolvedores e sysadmins subestimam a capacidade do N8N de executar lógica JavaScript diretamente no editor visual. Ao invés de criar nós adicionais apenas para transformar strings ou calcular valores simples, você pode injetar código inline que é avaliado antes da execução do próximo nó. Neste tutorial técnico, exploraremos como configurar fluxos dinâmicos utilizando expressões JavaScript, variáveis dinâmicas e a estrutura de dados JSON típica do N8N.
Entendendo a Estrutura de Dados no N8N
Antes de escrever qualquer expressão, é crucial compreender como o N8N organiza as informações. Diferente de scripts Node.js tradicionais que operam sobre variáveis globais ou objetos simples, o N8N opera em um contexto de "item". Cada nó produz uma lista de itens (items), e cada item contém um objeto JSON com os dados.
Quando você vê o menu suspenso para inserir uma variável, está selecionando referências a campos específicos dentro desse objeto. A estrutura base geralmente se parece com isto:
[
{
"json": {
"id": 123,
"email": "[email protected]",
"metadata": {
"created_at": "2023-10-27T10:00:00Z"
}
},
"pairedItem": null
}
]O segredo das expressões dinâmicas reside na capacidade de acessar o campo json e, por extensão, qualquer propriedade aninhada dentro dele. As expressões são avaliadas no contexto do item atual sendo processado pelo nó.
Sintaxe Básica de Expressões
O N8N utiliza uma sintaxe específica para identificar trechos de código que devem ser executados dinamicamente. Diferente de muitos editores de código que usam crases (`) ou chaves duplas, o N8N utiliza colchetes angulares: {{ }}.
Qualquer texto dentro desses colchetes é interpretado como uma expressão JavaScript. Se você digitar algo fora desses colchetes, ele será tratado como uma string literal. Vamos ilustrar a diferença:
- String Literal: "O valor do ID é 123". Aqui, o texto é fixo.
- Expressão Dinâmica: "O valor do ID é {{ $json.id }}". O N8N avaliará
$json.ide substituirá pelo valor real contido no item atual.
É importante notar que, dentro dos colchetes, você não precisa usar aspas simples ou duplas para strings. A expressão é tratada como código JavaScript puro. Se você precisar de uma string literal dentro da expressão (por exemplo, para concatenar um sufixo fixo), deve usar aspas.
Acessando Dados de Nós Anteriores
A funcionalidade mais comum ao trabalhar com variáveis dinâmicas é a necessidade de passar dados de um nó para outro. No N8N, isso é feito automaticamente pelo fluxo, mas você precisa referenciar corretamente esses dados.
Referenciando o Item Atual
Para acessar os dados produzidos pelo nó imediatamente anterior (ou o nó atual, se estiver editando suas próprias saídas), utilize a variável $json. Esta é uma abreviação para $node["NomeDoNóAnterior"].json.
// Acessa o campo 'nome' do item anterior
{{ $json.nome }}Se você precisar acessar um campo aninhado, use a notação de ponto:
{{ $json.endereco.cep }}Referenciando Nós Específicos
Às vezes, você precisa pular o nó anterior e buscar dados de um nó específico que está conectado em paralelo ou em uma ramificação diferente do workflow. Para isso, use a sintaxe completa:
{{ $node["NomeDoNó"].json.campo }}Se o nó tiver múltiplos itens (o que é comum em loops ou respostas de APIs com listas), você pode especificar o índice do item desejado:
{{ $node["NomeDoNó"].json[0].campo }}Isso retorna o valor do campo campo no primeiro item ([0]) do nó NomeDoNó.
Executando Lógica JavaScript Complexa
O verdadeiro poder das expressões dinâmicas surge quando você vai além da simples leitura de variáveis e começa a manipular dados. Como o N8N roda em uma infraestrutura Node.js, você tem acesso a grande parte do ecossistema JavaScript nativo.
Manipulação de Strings
Você pode transformar formatos de texto diretamente no campo de configuração. Por exemplo, converter um e-mail para minúsculas antes de enviá-lo a um banco de dados:
{{ $json.email.toLowerCase() }}Outro exemplo prático é a extração de partes de uma string usando expressões regulares (regex). Suponha que você tenha uma URL completa e queira extrair apenas o caminho:
{{ $json.url.match(/https?:\/\/([^\/]+)/)[1] }}Esta expressão usa .match() para aplicar a regex e retorna o primeiro grupo de captura, que corresponde ao domínio.
Funções Matemáticas e Datas
O objeto global Date está disponível. Você pode calcular datas futuras ou passadas dinamicamente. Por exemplo, definir um cabeçalho HTTP com a data atual formatada:
{{ new Date().toISOString() }}Para cálculos numéricos, basta operar sobre os valores extraídos do JSON. Se o nó anterior retornou um preço e você precisa calcular o imposto de 10%:
{{ ($json.preco * 1.1).toFixed(2) }}O método .toFixed(2) garante que o resultado tenha duas casas decimais, formatando automaticamente como string.
Filtros e Mapeamentos (Map/Filter)
Em cenários avançados, você pode precisar processar um array de objetos. Se um nó anterior retornou uma lista de produtos, você pode filtrar apenas os itens em estoque usando expressões inline no nó "Edit Fields" ou até mesmo em configurações que aceitem arrays dinâmicos.
Embora a melhor prática para transformações complexas de arrays seja usar o nó dedicado Function (Função), é possível realizar operações simples em campos únicos que contenham arrays:
// Retorna apenas os IDs dos produtos que custam mais de 100
{{ $json.produtos.filter(p => p.preco > 100).map(p => p.id) }}Tratamento de Erros e Validação
Ao trabalhar com dados externos, a falta de validação é a causa número um de workflows quebrados. As expressões dinâmicas permitem que você implemente verificações rápidas antes de prosseguir.
O Operador Nullish Coalescing e Ternários
Um erro comum é tentar acessar uma propriedade que não existe, resultando em undefined. Para evitar isso, utilize o operador opcional ?.:
{{ $json.endereco?.cep }}Se endereco for nulo ou indefinido, a expressão retornará undefined em vez de lançar um erro de execução. Isso é vital para manter o workflow estável quando a estrutura da API externa varia.
Você também pode usar operadores ternários para fornecer valores padrão (fallbacks). Se o campo nome estiver vazio, use "Sem Nome":
{{ $json.nome || "Sem Nome" }}Isso é mais conciso do que uma estrutura if/else e muito mais legível em campos de configuração curtos.
Boas Práticas para Workflow Dinâmico
Para manter seus fluxos no N8N maintainable (manteníveis) e legíveis, siga estas diretrizes técnicas:
- Mantenha as Expressões Simples: Se a lógica JavaScript estiver ficando complexa demais para caber em um único campo de expressão, mova-a para um nó
Function. O nó Function permite escrever código multi-linha, definir variáveis locais e usar bibliotecas externas se necessário. - Use Nomes Descritivos para Nós: Ao referenciar nós específicos com
$node["Nome"], certifique-se de que os nomes dos nós no canvas sejam claros. Isso facilita a depuração quando algo sai errado. - Evite Side Effects: Expressões dinâmicas devem ser puras, ou seja, elas devem apenas ler e transformar dados, não modificar o estado global do workflow ou realizar chamadas de rede dentro da expressão. Chamadas de API devem sempre ser feitas por nós dedicados (HTTP Request).
- Documente Campos Complexos: Se você usa uma expressão regex ou matemática complexa, deixe um comentário no campo "Notes" (Notas) do nó ou adicione uma explicação na descrição do workflow. Isso ajuda outros membros da equipe a entenderem a lógica.
Exemplo Prático: Integração Dinâmica de CRM
Vamos aplicar tudo o que aprendemos em um cenário real. Suponha que você esteja criando um workflow que recebe um novo lead via webhook e o envia para o CRM, formatando os dados adequadamente.
O payload do webhook contém:
{
"lead_id": "abc-123",
"nome_completo": " JOÃO SILVA ",
"data_nascimento": "1990-05-15"
}No nó do CRM, você precisa:
- Limpar os espaços em branco do nome.
- Converter o nome para Title Case (João Silva).
- Calcular a idade aproximada baseada na data de nascimento.
- Inserir esses valores nos campos corretos do CRM.
No campo "Nome" do nó CRM, você configuraria a expressão dinâmica assim:
{{ $json.nome_completo.trim().split(' ').map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ') }}E no campo "Idade", a lógica seria:
{{ Math.floor((Date.now() - new Date($json.data_nascimento).getTime()) / 3.15576e+10) }}Esta expressão calcula a diferença em milissegundos entre o agora e a data de nascimento, dividindo pela constante que representa aproximadamente um ano em milissegundos.
Conclusão
O domínio das expressões JavaScript dinâmicas no N8N separa os usuários casuais dos engenheiros de automação proficientes. Ao substituir nós redundantes por lógica inline eficiente, você reduz a latência do seu workflow, simplifica a arquitetura visual e ganha flexibilidade para lidar com dados imprevisíveis.
Lembre-se: o N8N é uma ferramenta poderosa que combina a facilidade visual com a robustez do Node.js. Utilize as expressões {{ }} não apenas como pontes de dados, mas como micro-servidores de lógica dentro do seu fluxo. Pratique com cenários simples, evolua para manipulações de arrays e, quando a complexidade aumentar, migre para o nó Function. Com essa abordagem, seus workflows se tornarão verdadeiramente dinâmicos, escaláveis e resilientes.
Agora que você entende a sintaxe e a lógica, experimente abrir seu editor do N8N e substituir os valores estáticos nos campos de configuração por expressões dinâmicas. A diferença na capacidade de resposta dos seus automações será imediata.