n8n : boucler sur une liste sans créer de doublons
Dans n8n, la première question n’est pas “comment faire une boucle ?”, mais “ai-je vraiment besoin d’une boucle ?”. La documentation rappelle que n8n gère souvent le traitement répétitif automatiquement. Si un nœud reçoit dix items, il peut les traiter un par un sans que vous dessiniez une boucle manuelle.
1. Comprendre items et tableaux
Un item n8n est une unité de travail. Si votre HTTP Request reçoit une réponse contenant un tableau dans un seul item, vous n’avez pas encore dix items. Vous avez un item avec un tableau dedans. Utilisez alors Split Out ou un nœud équivalent pour transformer chaque élément du tableau en item séparé.
Exemple : une API renvoie {"leads":[{"id":1},{"id":2}]}. Après Split Out sur leads, vous obtenez deux items. Ensuite, les nœuds suivants peuvent traiter chaque lead.
2. Quand utiliser Loop Over Items
Utilisez Loop Over Items quand vous devez contrôler un batch, attendre entre deux appels ou faire une action séquentielle. Pour respecter une API fragile, mettez un batch de 1, puis ajoutez un Wait après l’appel API.
- Entrée : liste d’items déjà séparés.
- Loop Over Items : batch size
1. - HTTP Request : appel externe.
- Wait : pause de quelques secondes si nécessaire.
- Retour : reconnecter la fin de traitement vers l’entrée de Loop Over Items.
3. Branches de sortie
Loop Over Items a une logique de branche : une sortie traite le lot courant, une autre sort quand tous les items sont terminés. Le câblage est important. Si vous envoyez la branche finale vers l’appel API, vous ne traitez rien. Si vous oubliez de revenir vers la boucle après l’action, vous ne passez qu’un lot.
4. Éviter les doublons
Dans une boucle qui crée des tickets, posts ou emails, stockez une clé de traitement par item. Exemple : lead_id + campagne. Avant de créer, vérifiez si la clé existe. Pour un système concurrent, utilisez une contrainte unique côté base plutôt qu’une simple vérification visuelle.
5. Déboguer
Testez avec trois items seulement : un normal, un incomplet, un qui déclenche une erreur. Regardez le nombre d’items à chaque nœud. Si le compteur reste à 1 alors que vous attendiez 50, le problème vient probablement d’un tableau non éclaté. Si le workflow ne termine pas, vérifiez le retour vers la boucle et les conditions d’arrêt.
Limiter les appels externes
Si la boucle appelle une API payante ou limitée, ajoutez un compteur. Par exemple, stockez processed_count, failed_count et last_processed_id. À la fin, envoyez un résumé plutôt qu’une alerte par item. Cela évite de transformer une reprise normale en bruit opérationnel.
Cas à éviter
N’utilisez pas Loop Over Items pour compenser une mauvaise structure de données. Si le problème est un tableau imbriqué, corrigez d’abord la forme. Si le problème est une limite API, alors la boucle avec batch 1 et Wait devient justifiée.
Exemple de reprise
Imaginez 200 leads à enrichir. Le workflow sépare les leads en items, traite un lead par batch, appelle l’API, attend deux secondes, puis écrit le statut done avec l’identifiant du lead. Si l’item 87 échoue, vous gardez 86 succès confirmés et une erreur isolée. À la relance, filtrez les leads déjà marqués done et reprenez seulement les autres.
Un câblage explicite et une fin vérifiable
Reliez la sortie loop à HTTP Request, puis Wait, puis à l’entrée de Loop Over Items. Reliez done au bilan final. Gardez Reset désactivé pour une liste initiale fixe ; le réactiver sans condition de sortie peut réinitialiser le lot à chaque passage.
Une pause après chaque appel limite le rythme, mais un batch de un n’empêche pas plusieurs exécutions du workflow de tourner ensemble. Le bilan doit compter les entrées, les réussites et les éléments placés en erreur. Si un nœud ne renvoie aucun item, vérifiez que le chemin de retour peut encore être exécuté, sans fabriquer une réussite métier.