Item linking no n8n: como ele decide qual item vai para qual saída
Dado certo no registro errado e sem mensagem de erro: o sintoma do item linking quebrado, por que o node Code causa isso e como evitar.
Resumo por IA
Resumo gerado por IA, revisado pela redação.
Item linking é o mecanismo que faz o n8n lembrar de qual item veio cada resultado. Cada item que sai de um node guarda uma ligação com o item que o originou nos nodes anteriores — e é isso que permite, lá na frente do fluxo, buscar um dado de três nodes atrás e receber o valor certo, e não o do primeiro registro da lista. Na maior parte do tempo isso simplesmente funciona e você nem percebe. Quando quebra, o sintoma é sempre o mesmo: dado trocado entre registros.
Adicione ao Google NotíciasO problema que o linking resolve
Imagine um fluxo que busca cinco pedidos, consulta o cliente de cada um e envia uma mensagem. No node final você precisa de duas informações que vieram de nodes diferentes: o número do pedido, do primeiro node, e o telefone, do segundo.
Sem um mecanismo de ligação, quando o node final perguntasse "qual era o número do pedido?", ele não teria como saber qual dos cinco pedidos corresponde ao item que está processando agora. O resultado seria a mensagem do cliente A saindo com o pedido do cliente B.
O item linking existe para isso: cada item carrega o rastro de qual item o gerou, node a node, formando uma cadeia que dá para percorrer de volta.
Quando você precisa saber disso
Sendo honesto: na maior parte dos fluxos, nunca. A documentação é explícita ao dizer que normalmente isso apenas funciona. Você precisa entender em detalhe apenas em duas situações:
Quando usa o node Code para comportamentos mais elaborados com dados de entrada e saída.
Quando constrói um node próprio, de estilo programático.
Fora desses casos, o conhecimento útil é reconhecer o sintoma quando ele aparece — e é o que vem a seguir.
Como reconhecer que o linking quebrou
O sinal é característico e vale memorizar: o fluxo roda sem erro, mas os dados saem trocados entre os registros.
Concretamente:
Todos os itens recebem o valor do primeiro registro, repetido.
Nome de um cliente aparece com o pedido de outro.
Uma expressão que busca dado de node anterior devolve sempre a mesma coisa, para qualquer item.
Repare que não há mensagem de erro. O fluxo termina em verde e o problema só aparece do lado do cliente, que recebeu a informação de outra pessoa. É por isso que vale conhecer o sintoma antes de precisar dele: sem saber que esse tipo de falha existe, a investigação demora horas.
Por que o node Code é o ponto de risco
Quando você monta itens novos dentro do node Code — combinando dados, filtrando, criando registros —, esses itens nascem sem histórico. Eles não vieram de nenhum item anterior; foram construídos ali.
O n8n, então, perde a informação de qual item original corresponde a qual item novo. Se mais adiante alguma expressão tentar buscar um dado de um node anterior, a cadeia está cortada e o resultado é imprevisível.
A documentação trata esse caso especificamente, com orientação sobre como preservar a ligação ao trabalhar com o Code — o conceito-chave é que, ao criar itens ali dentro, você precisa informar de qual item de entrada cada saída se originou, em vez de deixar que o n8n adivinhe.
As três formas de evitar o problema
1. Prefira os nodes de dados ao Code
Quando a transformação couber num node de configuração, use ele. Além de manter o linking intacto sozinho, fica mais legível para quem vier depois.
2. Traga o dado antes, não depois
Em vez de buscar um valor de três nodes atrás no final do fluxo, carregue esse campo junto desde o começo, deixando-o viajar com o item. Custa um campo a mais e elimina a dependência da cadeia.
3. Teste com mais de um item
Este é o conselho mais valioso do texto. Fluxos testados com um único registro nunca revelam problema de linking — com um item só, qualquer referência acerta por sorte. Teste sempre com pelo menos três registros diferentes e confira se cada resultado corresponde ao registro certo.
Resumindo: item linking é a memória de origem de cada item. Você raramente precisa mexer nele, mas precisa reconhecer o sintoma — dado certo no registro errado, sem mensagem de erro — e testar sempre com vários itens.
Esta aula faz parte do Curso de n8n do zero ao avançado, com todas as aulas em portugues.
Perguntas frequentes
O que é item linking no n8n?
É o mecanismo pelo qual cada item de saída guarda a ligação com o item que o gerou nos nodes anteriores. Essa cadeia é o que permite buscar, em qualquer ponto do fluxo, um dado de um node anterior e receber o valor correspondente ao registro que está sendo processado.
Por que meus dados saem trocados entre registros?
É o sintoma clássico de cadeia de ligação rompida, quase sempre depois de um node Code que criou itens novos sem informar de qual item de entrada cada um veio. O fluxo termina sem erro, mas as referências a nodes anteriores passam a apontar para o item errado.
Preciso entender item linking para usar o n8n?
Não para fluxos comuns, em que o comportamento funciona sozinho. Passa a ser necessário ao usar o node Code para manipulações mais elaboradas de entrada e saída, ou ao construir nodes próprios.
Como testar se o linking está correto?
Executando o fluxo com pelo menos três registros diferentes e conferindo se cada resultado corresponde ao registro certo. Testes com um único item nunca revelam esse tipo de problema, porque qualquer referência acerta por coincidência.
Como evitar quebrar o linking?
Preferindo nodes de configuração ao node Code quando a transformação couber neles, carregando os campos necessários desde o início do fluxo em vez de buscá-los lá na frente, e, quando o Code for inevitável, informando explicitamente a origem de cada item criado.
