N8N Variáveis e Expressões: Guia Completo

Trabalhar com automações vai muito além de conectar aplicativos. O verdadeiro poder surge quando você consegue transformar dados, aplicar lógica condicional e manipular informações de forma dinâmica. É exatamente aqui que entra o domínio de N8N variáveis expressões, um conjunto de recursos que diferencia workflows básicos de automações realmente inteligentes. Se você já conhece a plataforma através do nosso guia N8N Automações: Guia Completo, agora é hora de aprofundar nesses conceitos que vão elevar suas automações a outro patamar.

Neste conteúdo, vamos explorar como utilizar variáveis, criar expressões JavaScript e manipular dados dentro dos seus workflows de forma prática e aplicável ao dia a dia.

O que são variáveis no N8N e como funcionam

Variáveis no N8N são containers que armazenam informações durante a execução do workflow. Elas permitem que você capture dados de um node e os utilize em qualquer outro ponto da automação. Diferente de linguagens de programação tradicionais, aqui as variáveis seguem um fluxo específico baseado na estrutura dos nodes.

O sistema trabalha com diferentes escopos. Você tem variáveis de ambiente, que ficam disponíveis globalmente, e variáveis de execução, que existem apenas durante o processamento de um workflow específico. Entender essa diferença evita muita dor de cabeça quando suas automações começam a crescer.

Na prática, prefiro sempre nomear minhas variáveis de forma descritiva. Em vez de usar "x" ou "temp", opto por nomes como "emailCliente" ou "valorTotal". Isso facilita a manutenção quando você revisita um workflow meses depois.

Sintaxe básica das expressões no editor

O editor de expressões do N8N utiliza uma sintaxe própria que combina notação de chaves duplas com JavaScript. Para acessar dados do node anterior, você usa {{ $json.nomeDoCampo }}. Essa estrutura é a base de tudo que você vai construir.

Quando precisa acessar dados de nodes específicos, a sintaxe muda para {{ $node["NomeDoNode"].json.campo }}. Isso dá flexibilidade para puxar informações de qualquer ponto do workflow, não apenas do node imediatamente anterior.

Manipulando dados JSON com expressões JavaScript

JSON é o formato padrão de troca de dados no N8N. Dominar sua manipulação abre possibilidades enormes. Você pode acessar propriedades aninhadas usando notação de ponto: {{ $json.cliente.endereco.cidade }}. Para arrays, utilize índices numéricos: {{ $json.itens[0].nome }}.

As expressões JavaScript dentro do N8N permitem operações mais complexas. Você consegue usar métodos como map(), filter() e reduce() para transformar arrays. Por exemplo, para extrair apenas os nomes de uma lista de objetos: {{ $json.usuarios.map(u => u.nome) }}.

Quando testei workflows mais elaborados, descobri que combinar múltiplos métodos em cadeia funciona perfeitamente. Algo como {{ $json.pedidos.filter(p => p.valor > 100).map(p => p.id) }} retorna apenas os IDs de pedidos acima de cem reais. Essa capacidade de encadear operações torna o N8N variáveis expressões um recurso absurdamente poderoso.

Um ponto que merece atenção: o editor não oferece autocomplete completo para métodos JavaScript. Você precisa conhecer a sintaxe de antemão, o que representa uma curva de aprendizado inicial. Não é um problema grave, mas seria uma melhoria bem-vinda na ferramenta.

Para objetos complexos, o método Object.keys() ajuda a listar todas as propriedades disponíveis. Já Object.values() extrai apenas os valores. Essas funções auxiliam especialmente quando você recebe dados de APIs externas e precisa entender a estrutura antes de manipular.

Funções nativas disponíveis no N8N

Além do JavaScript padrão, o N8N oferece funções próprias que simplificam tarefas comuns. A função $now retorna a data e hora atual. Você tem $today para apenas a data, sem componente de horário. Essas funções facilitam automações baseadas em tempo.

A função $evaluateExpression() permite executar expressões dinamicamente, útil quando o conteúdo da expressão vem de uma variável. Já $items() retorna todos os itens processados pelo node atual, permitindo operações em lote.

Para workflows que processam múltiplos itens, $itemIndex indica a posição atual no array. Isso ajuda a criar lógicas condicionais baseadas na ordem dos elementos.

Trabalhando com datas e formatação

Manipulação de datas costuma ser fonte de bugs em qualquer sistema. No N8N variáveis expressões, você conta com a biblioteca Luxon integrada. Para formatar uma data, use {{ DateTime.fromISO($json.data).toFormat('dd/MM/yyyy') }}. O padrão ISO evita problemas de timezone.

Cálculos com datas também ficam simples. Adicionar dias: {{ DateTime.now().plus({ days: 7 }).toISO() }}. Subtrair meses: {{ DateTime.now().minus({ months: 1 }).toISO() }}. Essas operações são essenciais para automações de follow-up, vencimentos e agendamentos.

O que funciona melhor aqui é sempre trabalhar com UTC internamente e converter para o timezone local apenas na exibição final. Isso evita confusões quando seu workflow processa dados de diferentes fusos horários.

Condicionais e operadores lógicos nas expressões

Expressões condicionais transformam workflows lineares em automações inteligentes. O operador ternário é seu aliado principal: {{ $json.status === 'ativo' ? 'Processar' : 'Ignorar' }}. Essa estrutura compacta substitui nodes IF simples em muitos casos.

Para condições mais elaboradas, combine operadores lógicos. O AND (&&) exige que todas as condições sejam verdadeiras. O OR (||) aceita qualquer uma. Você pode aninhar essas estruturas: {{ ($json.valor > 100 && $json.cliente.premium) || $json.prioridade === 'alta' ? 'Urgente' : 'Normal' }}.

O operador nullish coalescing (??) resolve elegantemente valores ausentes. A expressão {{ $json.apelido ?? $json.nome ?? 'Visitante' }} retorna o apelido se existir, senão o nome, e finalmente um valor padrão. Isso previne erros quando campos opcionais estão vazios.

Comparações de igualdade merecem cuidado. Use sempre === (igualdade estrita) em vez de == (igualdade frouxa). A versão estrita compara tipo e valor, evitando comportamentos inesperados como "1" == 1 retornando verdadeiro.

Acessando dados de nodes anteriores no workflow

Em workflows complexos, você frequentemente precisa de dados que não estão no node imediatamente anterior. O N8N variáveis expressões oferece várias formas de navegar pelo histórico de execução.

A sintaxe $node["NomeDoNode"].json acessa o output de qualquer node pelo nome. Renomeie seus nodes com nomes descritivos para facilitar essas referências. "HTTP Request" genérico vira "BuscaDadosCliente", muito mais claro.

Para acessar dados do primeiro node do workflow, use $input.first().json. O último item processado fica em $input.last().json. Quando precisa de todos os itens, $input.all() retorna o array completo.

Tratamento de erros e valores nulos

Erros acontecem. APIs falham, campos vêm vazios, estruturas mudam. Preparar suas expressões para essas situações diferencia automações frágeis de robustas. O optional chaining (?.) acessa propriedades aninhadas sem quebrar quando intermediárias são nulas: {{ $json.cliente?.endereco?.cep }}.

Combine optional chaining com nullish coalescing para valores padrão seguros: {{ $json.cliente?.telefone ?? 'Não informado' }}. Essa dupla resolve a maioria dos casos de dados faltantes sem necessidade de nodes adicionais de verificação.

Para validações mais complexas, o método typeof verifica o tipo de dado. A expressão {{ typeof $json.valor === 'number' ? $json.valor.toFixed(2) : '0.00' }} garante que formatação numérica só aconteça em números reais. Isso previne erros quando a API retorna valores como strings ou null.

Exemplos práticos de expressões avançadas

Vamos a casos reais que uso frequentemente. Para extrair domínio de emails: {{ $json.email.split('@')[1] }}. Capitalizar nome próprio: {{ $json.nome.split(' ').map(p => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join(' ') }}.

Calcular total de um carrinho de compras: {{ $json.itens.reduce((acc, item) => acc + (item.preco * item.quantidade), 0) }}. Filtrar produtos em estoque: {{ $json.produtos.filter(p => p.estoque > 0) }}.

Para gerar slugs de títulos: {{ $json.titulo.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '') }}. Essa expressão remove acentos, converte para minúsculas e substitui espaços por hífens.

Minha opinião direta: o sistema de expressões do N8N é superior ao de concorrentes como Zapier e Make quando falamos de flexibilidade. A possibilidade de usar JavaScript real, não apenas templates limitados, coloca a ferramenta em outro patamar para automações que exigem transformação de dados. Se você desenvolve no ecossistema Modo Dev, vai apreciar essa liberdade.

Boas práticas para organização e manutenção

Expressões complexas rapidamente viram código ilegível. Quebre operações longas em múltiplos nodes Set quando a lógica exigir. O custo de processamento é mínimo e a clareza compensa.

Documente expressões não óbvias usando o campo de notas dos nodes. Seu eu futuro agradece quando precisar modificar um workflow seis meses depois. Comentários dentro das expressões não funcionam, então a documentação externa é essencial.

Teste expressões isoladamente antes de integrar ao workflow completo. O painel de execução mostra o resultado de cada node, facilitando debug. Quando algo falha, verifique primeiro se os dados de entrada estão no formato esperado. Na maioria das vezes, o problema está na estrutura do JSON, não na expressão em si. Dominar N8N variáveis expressões exige prática constante, mas os resultados justificam o investimento de tempo.