Architecture n8n
Comprendre les items, les erreurs et les sous-workflows
n8n devient plus simple quand on cesse de le regarder comme une collection de nœuds. Un workflow transporte des items, chaque nœud les transforme, et les expressions servent à retrouver une donnée précise dans ce flux.
Ce module part de cette mécanique. Nous allons suivre un item de l’entrée à la sortie, regarder ce qui se passe quand une branche échoue, et voir quand il faut écrire du code plutôt que d’empiler des nœuds. Les captures d’écran viendront plus tard : d’abord le modèle mental.
n8n n’est pas "juste" un Zapier moins cher. C’est un environnement de développement visuel. Si vous ne comprenez pas le passage des données (Items), vous serez bloqué au premier
IF.
n8n 3 et les agents natifs
Relevé du 10 novembre 2026 : la version stable est 2.47.3, la bêta 2.48.0. n8n 3.0 est en accès anticipé, avec une 3.2.0 en préversion. Deux changements de fond à retenir avant de planifier une montée de version.
La rupture 3.0
- L’auto-hébergement passe par Docker : plus de paquet npm exécutable.
- Les nœuds hérités disparaissent (Function, Item Lists, Cron, Interval, Read PDF, HTML Extract). Function devient Code.
$getPairedItemest retiré au profit de$('Nœud').item.- La rotation des clés de chiffrement est active par défaut, le Slack Trigger exige désormais un signing secret.
- Le rapport de migration (Settings puis Migration Report) liste les workflows à reprendre avant la bascule.
Les agents intégrés
- Onglet Agents (2.40, en preview) : un modèle, des instructions, des outils.
- Un agent appelle des nœuds, des serveurs MCP et des workflows entiers comme outils.
- Skills, sous-agents, fichiers de connaissance, mémoire et session par conversation.
- Un tour d’agent compte une exécution, les appels d’outils ne sont pas refacturés séparément.
- Les outils sensibles peuvent exiger une approbation humaine avant exécution.
1. La Structure "Item"
Tout tourne autour du JSON. Un nœud reçoit un Tableau et renvoie un Tableau.
2. L’Expression Language
Pour rendre les nœuds dynamiques, on utilise des expressions JavaScript (doubles accolades).
- {{ $json.email }}
- Accède à la propriété "email" de l’item courant.
- {{ $now.plus({ days: 1 }) }}
- Ajoute 1 jour à la date courante (librairie Luxon intégrée).
- {{ $('NomDuNoeud').first().json.id }}
- Va chercher une donnée dans un nœud précédent (remplacez NomDuNoeud par son vrai nom).
Suivons une commande simple. Le Webhook reçoit un item avec un identifiant et un montant. Le nœud
Set ajoute un champ statut. Le nœud IF sépare les commandes supérieures à 100 euros.
Le nœud HTTP appelle la comptabilité, puis Respond renvoie une réponse. À chaque étape, le nœud
reçoit un tableau et renvoie un tableau : il peut le filtrer, le trier, le dupliquer ou le vider.
Un filtre qui ne laisse rien passer ne produit pas une erreur, il produit zéro item. C’est une
distinction importante quand on cherche pourquoi la suite du workflow ne s’exécute pas.
{{ $json.email }} lit le champ de l’item courant. {{ $('Nom du nœud').item.json.email }}
lit un item précis d’un nœud précédent. pairedItem conserve le lien entre une sortie et
l’item d’entrée qui l’a produite. Sans ce lien, un nœud qui fusionne ou transforme des données ne
peut plus dire à quelle ligne d’origine appartient le résultat.
🛠 Debugging & Optimisation
🔍 Lire les Logs
Dans l’historique d’exécution :
- Input : Ce qui est rentré dans le nœud.
- Output : Ce qui en est sorti.
- Si Output est vide, le nœud a filtré toutes les données.
📌 Pin Data
Ne rejouez pas tout le workflow à chaque test API !
Cliquez sur l’épingle d’un nœud pour figer ses données de sortie. Le nœud suivant utilisera ces données "mockées" sans rappeler l’API précédente.
Quand un workflow « ne fait rien », trois causes reviennent. Un filtre en amont a renvoyé zéro item.
Un nœud a échoué et la branche d’erreur n’est pas branchée. Ou une expression pointe vers un champ
qui n’existe pas, et le nœud reçoit undefined. Dans les trois cas, le réflexe utile est
de cliquer sur le dernier nœud vert, de regarder son output, puis de remonter d’un nœud à la fois.
Le journal d’exécution raconte l’histoire ; le canvas ne montre que le chemin prévu.
🧩 Les Nœuds Indispensables
• Append : Met les tableaux bout à bout.
• Wait (Mode "Pass-through") : Attend que la branche A soit finie avant de
lancer la B. Vital pour séquencer les actions.
Dirige le trafic. Le "Switch" est plus propre que des "If" en cascade.
Ex: Routez par "Type de Client" (VIP, Standard, Prospect).
Pour ne pas faire exploser la RAM ou les limites API. Le nœud boucle sur chaque lot puis continue via sa sortie "done".
"Traite ces 1000 emails par paquets de 10."
L’échappatoire. Quand le No-Code est trop lourd, 5 lignes de JS résolvent le problème. Manipulation complexe d’Arrays ou Regex.
Nœud natif ou nœud Code ? La question n’est pas idéologique. Un nœud natif est plus lisible pour la personne qui reprend le workflow, et souvent plus simple à tester. Un nœud Code devient utile quand la transformation est difficile à exprimer visuellement, quand il faut appeler une bibliothèque, ou quand dix nœuds font le travail de cinq lignes. Dans les deux cas, le critère est le même : est-ce qu’une autre personne peut comprendre et modifier sans vous appeler ?
Les sous-workflows servent à découper une logique réutilisée, à isoler une partie qui doit être testée seule, ou à contenir une erreur. Ils ont un coût : il faut documenter leurs entrées et sorties, versionner les deux workflows, et se souvenir qu’une modification dans le sous-workflow affecte tous ses appelants. Un sous-workflow mal nommé devient une boîte noire de plus.
Cas Pratique : Lead Enrichment Machine
1. Webhook : Reçoit l'email depuis Typeform.
⬇️
2. API d'enrichissement (Apollo...) : "Qui est ce prospect ?" (Job, Taille boîte). Clearbit : offre gratuite arrêtée en 2025, prévoyez une alternative payante.
⬇️
3. IF : Est-ce un CEO de +50 employés ?
├── OUI :
│ ├── AI Agent : Rédige une intro personnalisée LinkedIn.
│ ├── HubSpot : Crée le deal "Hot Lead".
│ └── Slack : Notifie l'équipe Sales 🔥.
└── NON :
└── Mailchimp : Ajoute à la newsletter classique.
$('HTTP Request
43').first().
Workflows prêts à importer (JSON)
Quatre starters à importer dans n8n (menu → Import from File), puis adaptez URL et clés. Reconnectez vos credentials : ils ne sont jamais inclus dans un export partagé.
1. Stripe vers Supabase : wf-stripe-supabase.json (Webhook → Set → HTTP Request).
2. Pagination API : wf-api-pagination.json (Schedule → HTTP Request → Code → Set).
3. Retry sur 429 : wf-retry-429.json (Webhook → HTTP Request avec réessais → Respond).
4. Lead Enrichment : wf-lead-enrichment.json (Webhook → HTTP Request → IF → Set → Respond).
TP : Réservation de salles (100 % libre)
Le cas d’école des conflits de créneaux, sans rien payer : NocoDB pour les tables, n8n pour la logique, Resend gratuit pour les emails (voir module 5).
Form (n8n) -> NocoDB (lire Réservations) -> Code (chevauchement, motif m14) -> IF libre ? -> NocoDB (créer) -> SMTP (confirmation)