Item linking na prática
Antes de começar
Buscar o valor de um node anterior que corresponde ao item atual, sem misturar registros.
- Ter lido o guia de expressões.
Cada item que um node entrega guarda uma ligação com o item que o originou. O n8n usa essa ligação para responder a pergunta: de qual registro do node anterior veio este item?
Na maioria dos workflows a ligação funciona sem configuração. A atenção é necessária quando você usa o Code node com lógica própria ou busca campos de um node que não é o imediatamente anterior.
As três formas de buscar o item ligado
| Forma | O que devolve |
|---|---|
$('Nome do node').item |
O item daquele node ligado ao item atual |
$('Nome do node').itemMatching(indice) |
O item ligado ao item de entrada na posição indicada |
$('Nome do node').pairedItem(indice) |
O item pareado com a posição indicada |
Em expressões, .item resolve quase todos os casos:
{{ $('Buscar cliente').item.json.email }}No Code node, itemMatching() é a forma indicada pela documentação para buscar itens de nodes anteriores.
O que muda no n8n 3.0
O helper $getPairedItem sai na versão 3.0. Expressões que ainda o usam falham na execução do node. Troque pelas formas da tabela acima antes de atualizar.
Erros de item linking
Quando a ligação se perde, o n8n mostra um erro informando que não conseguiu encontrar o item correspondente. A causa mais comum é um Code node que cria itens novos sem preservar a ligação. A documentação tem uma página só sobre como preservar o linking no Code node.
Confira o resultado
Com dois itens, cada saída mostra o valor do node anterior que pertence ao mesmo registro.
Fontes e conferência
Conteúdo conferido na documentação oficial do n8n em 28 de outubro de 2026.