Expressão no n8n é um trecho entre chaves duplas que troca um valor fixo por um dado que veio do node anterior. A forma mais usada é {{ $json.campo }} — o $json aponta para o item que está sendo processado agora, e o que vem depois do ponto é o caminho até o campo. Com isso e mais meia dúzia de variáveis internas você resolve praticamente tudo. Este texto é a referência que faltava em português.
Neste artigo
A sintaxe, em uma linha
Tudo que está entre {{ e }} é avaliado; o resto é texto literal. Isso significa que dá para misturar os dois na mesma caixa:
Olá {{ $json.nome }}, seu pedido {{ $json.numero }} foi confirmado.O n8n resolve as duas expressões e mantém o texto ao redor. É assim que se monta mensagem personalizada sem node nenhum de template.
Não digite o caminho: arraste o campo do painel de entrada para dentro da caixa. O n8n escreve a expressão com o caminho correto, inclusive os níveis aninhados. Digitar à mão só quando o campo não estiver visível na entrada.
$json: o que você vai usar 90% do tempo
$json é o item atual. Como o n8n processa um item por vez, ele sempre aponta para o registro que está sendo tratado naquele momento.
{{ $json.email }}
{{ $json.cliente.telefone }}
{{ $json["nome do campo"] }}A terceira forma resolve um problema comum: quando o nome do campo tem espaço, hífen ou acento, o ponto não funciona. Use colchetes com aspas.
O caso do webhook
Vale destacar porque confunde quase todo mundo. O dado que chega por webhook não vem solto — vem organizado em headers, params, query e body. O conteúdo que interessa quase sempre está no body:
{{ $json.body.nome }}Quem escreve {{ $json.nome }} num fluxo de webhook recebe vazio e passa meia hora procurando o erro no lugar errado.
As variáveis internas que valem a pena
| Variável | Devolve | Serve para |
|---|---|---|
$json | O item atual | Tudo |
$itemIndex | A posição do item na lista | Numerar, tratar o primeiro diferente |
$runIndex | Quantas vezes o node já rodou | Controlar repetição em loop |
$prevNode.name | Nome do node anterior | Log e mensagens de erro |
$workflow.name | Nome do fluxo | Identificar a origem no aviso |
$workflow.id | Identificador do fluxo | Referência em registro |
$execution.id | Identificador da execução | Rastrear uma rodada específica |
$execution.mode | Se foi teste ou produção | Não enviar de verdade em teste |
$execution.resumeUrl | URL para retomar o fluxo pausado | Aprovação humana no meio |
$vars | Variáveis definidas na instância | Valores reutilizáveis |
$env | Variáveis de ambiente | Configuração do servidor |
$secrets | Segredos do cofre externo | Credenciais em plano empresarial |
Duas merecem comentário. $execution.mode permite montar um fluxo que não dispara mensagem de verdade quando você está testando — proteção barata contra o acidente de enviar cinquenta e-mails de teste. E $execution.resumeUrl é a base de fluxos com aprovação humana: o fluxo pausa, alguém abre aquela URL, o fluxo continua.
Data e hora
Expressões aceitam manipulação de data direto, sem código. O padrão que aparece na documentação:
{{ $today.minus(7, 'days') }}Isso devolve a data de sete dias atrás no formato correto — exatamente o que se usa para buscar "os registros da última semana" em qualquer API.
Transformar dado: use o node certo
Aqui vai uma recomendação que vem da própria documentação e que poupa manutenção: se o seu objetivo é transformar dados, e não fazer outra operação junto, use o node Edit Fields (Set) em vez de espalhar expressões complexas por vários parâmetros de nodes diferentes.
O motivo é organização. Preparar os dados num ponto só e passar o resultado adiante deixa o fluxo legível. Vinte expressões complicadas espalhadas por oito nodes deixam o fluxo impossível de manter — e quem vai sofrer é você daqui a três meses.
Regra prática: se a expressão não cabe confortavelmente na caixa, ela não deveria estar ali. Mova a transformação para um Edit Fields antes e deixe o node de destino recebendo um campo pronto.
O erro mais comum, e a correção
Expressão devolvendo vazio quase sempre é caminho errado. A sequência que resolve:
Abra o painel de entrada do node e confirme que o campo existe naquele item.
Confira maiúsculas e minúsculas — os nomes diferenciam.
Se o campo estiver aninhado, desça todos os níveis com pontos.
Se o nome tiver espaço ou acento, troque o ponto por colchetes com aspas.
Na dúvida, apague e arraste o campo.
Com {{ $json.campo }}, a tabela de variáveis internas e o hábito de arrastar em vez de digitar, você cobre a esmagadora maioria das expressões que vai escrever.
Esta aula faz parte do Curso de n8n do zero ao avançado, com todas as aulas em portugues.
Perguntas frequentes
Como usar expressões no n8n?
Escrevendo o trecho entre chaves duplas dentro de qualquer campo que aceite expressão. A forma mais comum é {{ $json.campo }}, que pega um valor do item atual. Texto fora das chaves permanece literal, o que permite montar frases com valores dinâmicos no meio.
O que significa $json no n8n?
É a variável que aponta para o item que está sendo processado naquele momento. Como os nodes processam um item por vez, ela sempre se refere ao registro atual, e o caminho após o ponto indica qual campo buscar.
Por que a expressão do meu webhook retorna vazio?
Porque o dado do webhook chega organizado em seções: headers, params, query e body. O conteúdo enviado fica dentro de body, então o caminho correto costuma ser {{ $json.body.campo }} e não {{ $json.campo }}.
Como pegar um campo cujo nome tem espaço?
Trocando a notação de ponto por colchetes com aspas: {{ $json["nome do campo"] }}. A mesma solução vale para nomes com hífen, acento ou qualquer caractere que quebre a notação de ponto.
Como saber se o fluxo está rodando em teste ou produção?
Usando {{ $execution.mode }}. É a base de uma proteção simples e muito útil: condicionar o envio real de mensagens ao modo de produção, evitando disparos acidentais durante os testes.
Onde colocar transformações complexas?
Num node Edit Fields (Set) dedicado, antes dos nodes que vão usar os dados. A própria documentação recomenda separar transformação de lógica de negócio, em vez de espalhar expressões complicadas por vários parâmetros — o fluxo fica muito mais fácil de entender depois.
