Como usar expressões no n8n sem perder campos importantes
Uma expressão no n8n deve ir buscar o valor certo ao registo certo. Para evitar perder informação, acompanha os dados desde a entrada até à saída, preserva os identificadores necessários e testa mais do que um exemplo. Um campo preenchido pode parecer correto e pertencer a outro pedido.
Define o que tem de chegar à etapa seguinte
Antes de escrever uma expressão, identifica os campos de que a próxima etapa precisa. Inclui a informação de trabalho e os identificadores que permitem confirmar a sua origem. Depois, define o comportamento esperado quando falta um valor. Esta preparação ajuda a distinguir um erro de mapeamento de uma entrada realmente incompleta.
Imagina um workflow que recebe pedidos e prepara registos para uma folha de acompanhamento. Cada registo deve conservar o identificador do pedido, o assunto e o estado. Um telefone pode ser opcional. Se o identificador desaparecer, deixa de ser claro qual o pedido que estás a atualizar ou a consultar mais tarde.
Escreve uma pequena lista de saída antes de configurar o nó: pedido_id, assunto, telefone e estado. Para cada campo, indica a origem e se pode ficar vazio. O estado inicial pode resultar de uma regra tua, como “por analisar”. O identificador deve vir do pedido recebido, sem ser substituído pelo de um exemplo anterior.
Se ainda não tens o percurso definido, começa pelo guia para desenhar uma automação antes de abrir o n8n. As expressões ficam mais simples quando já sabes o que estás a transportar e para que será utilizado.
Observa a estrutura real da entrada
Abre os dados que chegam à etapa em que vais trabalhar e identifica a localização de cada valor. Um campo pode estar diretamente no registo ou dentro de um objeto. O nome que parece evidente na origem pode mudar após uma transformação. Usa a entrada observada para construir o caminho, em vez de o adivinhar.
Neste exercício editorial, considera um registo fictício com esta estrutura:
{"pedido_id":"PED-101","assunto":"Organizar pedidos","contacto":{"telefone":null},"quantidade":0,"confirmado":false}
O identificador está na raiz. O telefone está dentro de contacto. A quantidade é um número e confirmado é um valor booleano. Não se trata de dados de um cliente, nem de uma execução apresentada como real. É uma amostra para explicar o que deves procurar quando inspecionares a tua entrada.
Confere as maiúsculas, os espaços e os nomes completos. “pedido_id” e “id” não são automaticamente o mesmo campo. Se o teu webhook colocar o conteúdo dentro de body, o caminho será diferente do mostrado neste exemplo. A expressão tem de acompanhar a estrutura que existe no teu workflow.
Quando a estrutura ainda estiver confusa, o artigo sobre organizar dados em JSON antes de os enviar à IA ajuda a separar objetos, listas e informação em falta. Essa leitura facilita o trabalho de mapeamento, mesmo quando o workflow não inclui um modelo de IA.
Distingue um valor fixo de uma expressão
Um valor fixo permanece igual entre registos; uma expressão calcula ou procura um valor a partir do contexto disponível. Ambos podem ser úteis, mas respondem a necessidades diferentes. Usa um valor fixo quando existe uma regra constante e uma expressão quando o campo depende dos dados recebidos naquela etapa do workflow.
Para o estado inicial “por analisar”, um valor fixo pode fazer sentido. Para o identificador de cada pedido, escrever “PED-101” num campo fixo faria todos os registos partilharem esse valor. O primeiro teste poderia parecer correto, porque usaste precisamente o pedido com esse identificador. Um segundo exemplo revelaria o problema.
A documentação do n8n apresenta expressões entre chavetas duplas para definir parâmetros dinamicamente. No contexto do item de entrada, {{ $json.pedido_id }} consulta o campo pedido_id. Para o assunto do mesmo exemplo, a expressão é {{ $json.assunto }}. A pré-visualização ajuda a observar o valor calculado para os dados disponíveis.
Confirma que o campo está no modo adequado. Uma expressão colada como texto fixo pode seguir para o destino como caracteres literais. Depois, compara o resultado com a origem. O objetivo é perceber por que aparece aquele valor, e não apenas conseguir que o campo deixe de mostrar um erro.
Escolhe os campos que queres conservar
Ao transformar um registo, decide explicitamente quais os campos que devem continuar disponíveis. Acrescentar um campo não significa que todos os anteriores serão sempre mantidos em qualquer configuração. Confere a saída do nó e procura os identificadores obrigatórios. A lista de campos esperados funciona como critério para esta verificação concreta.
O nó Edit Fields permite definir novos valores e substituir valores existentes. Na documentação atual, as opções de saída controlam que dados de entrada são incluídos. A opção Keep Only Set Fields descarta os campos de entrada que não forem utilizados no conjunto definido. Confere os controlos disponíveis na tua versão.
Num exercício com Manual Mapping, podes definir os quatro campos necessários e inspecionar a saída. Se optares por conservar outros campos da entrada, confirma que são úteis ao passo seguinte. Se preferires uma saída reduzida, inclui deliberadamente pedido_id. O importante é que a decisão seja visível e que a saída corresponda ao que planeaste.
Preservar contexto não significa transportar todos os dados para todos os destinos. Uma folha de tarefas pode precisar do identificador e do assunto, mas não de informação adicional do contacto. Escolhe o necessário e conserva uma relação clara com a origem. Assim, reduzes a confusão sem perder a possibilidade de conferir o registo.
Trata a informação em falta sem a inventar
Quando um campo opcional está ausente, escolhe uma representação que preserve esse significado. Quando falta um campo obrigatório, define uma saída de erro ou revisão. Não uses um valor de exemplo para fazer o fluxo avançar. Uma automação que continua com a identidade errada pode ser mais difícil de corrigir do que uma falha explícita.
Para o telefone opcional do exemplo, uma expressão possível é {{ $json.contacto?.telefone ?? null }}. O acesso opcional evita tentar ler telefone num contacto nulo ou inexistente. O operador de alternativa conserva null quando o valor consultado é null ou undefined. Isto não valida o formato do telefone nem confirma que o contacto é legítimo.
No caso de pedido_id, a regra é diferente. Se o processo depende dele para identificar o pedido, não o substituas pelo primeiro identificador encontrado noutro nó. Encaminha a entrada incompleta para o tratamento definido. O critério pode ser simples: sem identidade válida, não criar nem atualizar o registo de destino.
Regista a diferença entre “não recebido” e “recebido mas inválido”, se ela for relevante para corrigir o processo. A primeira situação pode apontar para um campo opcional ou para uma origem incompleta. A segunda exige perceber por que o valor recebido não cumpre o contrato esperado.
Preserva zero, falso e o tipo dos valores
Nem todos os valores que parecem vazios significam ausência. Zero pode ser uma quantidade válida e falso pode representar uma resposta negativa. Se usares uma alternativa demasiado abrangente, podes substituir esses valores sem querer. Antes de converter ou preencher um campo, define o significado do valor original e o formato esperado no destino.
Em JavaScript, o operador ?? usa a alternativa apenas para null ou undefined. Por isso, {{ $json.quantidade ?? null }} conserva o número zero, e {{ $json.confirmado ?? null }} conserva false. Uma string vazia também é conservada; se a tua regra considerar esse texto inválido, precisas de uma validação própria.
Este cuidado evita confundir “nenhuma unidade” com “quantidade desconhecida”. Também evita transformar uma resposta negativa numa confirmação por defeito. A escolha do valor alternativo é uma decisão sobre o processo, não apenas uma forma de eliminar uma mensagem incómoda no editor.
Confere o tipo na saída e no destino. Um identificador com zeros iniciais pode precisar de continuar a ser texto. Uma data deve manter um formato compreendido pelo sistema que a recebe. Se encontrares uma conversão inesperada, localiza a etapa em que aconteceu antes de tentar compensá-la com outra transformação mais à frente.
Verifica a relação entre os registos
Quando um workflow processa vários pedidos, cada saída deve continuar associada à entrada correta. Essa relação merece atenção após etapas que dividem listas, combinam dados ou criam novos itens. Um campo pode ter um valor válido e continuar errado para aquele pedido. Confere a identidade juntamente com o conteúdo, nunca apenas o preenchimento.
No n8n, referências a itens de nós anteriores dependem da relação disponível entre os itens. A documentação explica que a utilização de .item pode encontrar problemas quando essa relação está em falta, é ambígua ou aponta para outro ramo. O erro deve levar-te a investigar a estrutura e a origem dos dados.
Trocar automaticamente .item por .first() pode esconder o problema: passas a escolher o primeiro item, mesmo que o pedido atual seja outro. Usa uma seleção por posição apenas quando essa posição for, de facto, a regra pretendida. Para pedidos independentes, a identidade costuma ser um critério mais útil para conferir a associação.
Pensa em duas reuniões com tarefas semelhantes. O assunto da tarefa pode coincidir, mas o identificador da reunião é diferente. Se separares uma lista em vários registos, cada tarefa deve conservar a referência necessária à reunião de origem. Essa informação permite detetar trocas que uma leitura superficial do texto não revelaria.
Testa com exemplos que possam revelar erros
Um único exemplo completo raramente testa as decisões mais importantes do mapeamento. Prepara entradas diferentes e escreve a saída esperada antes de executar. Inclui valores em falta e casos que possam ser confundidos entre si. Trabalha num percurso de teste sem envios ou alterações reais enquanto estás a confirmar a transformação dos dados.
| Caso | Entrada proposta | O que deves confirmar |
|---|---|---|
| Pedido completo | PED-101 com assunto e contacto | Campos corretos e identidade preservada |
| Segundo pedido | PED-102 com outro assunto | Nenhum valor copiado do primeiro pedido |
| Contacto ausente | Sem o objeto contacto | Tratamento previsto para o telefone opcional |
| Quantidade zero | quantidade igual a 0 | Zero preservado como número |
| Resposta negativa | confirmado igual a false | Falso preservado como booleano |
| Identificador ausente | Sem pedido_id | Tratamento de erro ou revisão, sem identidade inventada |
Compara a saída de cada caso campo a campo. Se o segundo pedido herdar o identificador do primeiro, procura um valor fixo ou uma seleção incorreta. Se o telefone desaparecer de forma inesperada, confere o caminho e as opções de saída. Altera uma hipótese de cada vez e repete os casos afetados.
Estes testes são uma proposta para o teu workflow. O comportamento dos operadores pode ser conferido isoladamente, mas a aprovação do percurso exige executar na tua configuração e verificar o destino de teste. Uma expressão correta não demonstra, sozinha, que todas as etapas seguintes utilizam o seu resultado corretamente.
Localiza a primeira etapa em que o dado muda
Quando um campo desaparece ou muda de valor, segue o percurso pela ordem da execução e procura a primeira diferença face ao esperado. Compara entrada, configuração e saída nessa etapa. Esta abordagem reduz tentativas dispersas e evita corrigir apenas o sintoma num nó posterior, deixando a causa original por resolver.
Começa pelo identificador do registo afetado. Confirma se chegou à primeira etapa, se foi renomeado, se ficou dentro de outro objeto ou se foi excluído da saída. Depois, verifica o campo de negócio que está incorreto. Guardar estas duas observações ajuda a perceber se o problema é de identidade, de estrutura ou de transformação.
Distingue a configuração atual dos dados de uma execução anterior. Um resultado antigo pode ter sido produzido antes da correção que estás a observar no editor. Anota a execução, a alteração feita e o novo teste. Não assumes que todas as execuções ficam disponíveis indefinidamente; trabalha com o histórico que a tua instalação conserva.
Se a falha estiver na obtenção dos dados, revê o guia para ligar uma API ao n8n com HTTP Request. Um caminho bem escrito não recupera um campo que a resposta da origem não contém. Primeiro confirma o contrato e a resposta; depois ajusta o mapeamento.
Usa a IA para explicar e rever a expressão
Podes pedir ajuda à IA para compreender uma expressão ou propor uma transformação, desde que forneças uma amostra sem dados sensíveis e a saída esperada. Explica os casos que têm de funcionar. Depois, revê a proposta e testa-a. A explicação pode ser útil, mas a verificação continua a depender do comportamento observado.
Um pedido concreto seria: “Tenho estes dois registos fictícios. Quero conservar pedido_id, usar null quando o telefone opcional não existir e preservar quantidade zero e confirmado false. Explica cada expressão e identifica os casos em que o processo deve parar.” Acrescenta a estrutura real, com os nomes necessários e valores substituídos por exemplos.
Se a resposta sugerir uma expressão muito longa, divide o problema em passos que consigas compreender. Uma transformação pequena e verificável facilita a manutenção. Também permite perceber se a IA acrescentou um valor por defeito que contradiz a tua regra de negócio.
Antes de terminar, deixa uma nota com os campos obrigatórios, as alternativas permitidas e os casos testados. A pessoa que retomar o workflow deve conseguir perceber por que conservaste um null ou rejeitaste um pedido. Essa clareza vale tanto na construção inicial como quando precisas de corrigir o processo meses depois.
Pratica automações no Laboratório da IA
No Laboratório da IA, podes trabalhar estes problemas com exemplos e ligar as ferramentas ao processo que queres melhorar. As aulas semanais e os Zooms de acompanhamento semanais ajudam a esclarecer dúvidas de construção e diagnóstico. Leva uma amostra fictícia, a saída esperada e a etapa onde o resultado diverge do que definiste.
Começa por um workflow pequeno que transforma dois pedidos sem contactar clientes nem escrever em sistemas de produção. Quando conseguires explicar a origem, a identidade e o tipo de cada campo, terás uma base mais clara para avançar.
Referências e verificação
A documentação seguinte foi consultada em 14 de outubro de 2026. Sustenta a sintaxe, os controlos do nó e o comportamento dos operadores mencionados. O pedido e a matriz de testes são exemplos editoriais. A verificação isolada das expressões não substitui um ensaio completo na versão e na configuração do teu workflow.
Aprende a construir isto no Lab.
Trabalha o processo com aulas, materiais e acompanhamento. Leva o que estás a construir e esclarece as dúvidas da tua implementação.
- Mapear campos a partir da estrutura real de entrada.
- Preservar identidade e tipos e testar valores em falta.
- Praticar automações nas aulas e Zooms semanais do Laboratório.
Aulas semanais para aprender e aplicar. Zooms de acompanhamento semanais para esclarecer dúvidas. Replay e materiais para retomar o trabalho ao teu ritmo.
Entrar no Laboratório da IA