03

Architecture n8n

Comprendre les items, les erreurs et les sous-workflows

Module 038 min de lectureMis à jour le 20 novembre 2026

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.

Le Piège Classique :
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.
  • $getPairedItem est 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.
Lecture de builder : n8n devient une plateforme d’agents en plus d’un orchestrateur. La valeur se déplace du branchement de nœuds vers la définition du cadre : outils autorisés, approbations, journal et politique de nœuds. Les politiques de types de nœuds (2.44) sont réservées à l’offre Enterprise, à prendre en compte avant de bâtir une flotte.

1. La Structure "Item"

Tout tourne autour du JSON. Un nœud reçoit un Tableau et renvoie un Tableau.

[ { "json": { "email": "alice@corp.com", "id": 1 }, "pairedItem": { "item": 0 } }, { "json": { "email": "bob@corp.com", "id": 2 }, "pairedItem": { "item": 1 } } ]

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.

Atelier : inspecter un tableau d’items

Collez un tableau JSON. Le premier objet peut être un item n8n ({"json": {...}, "pairedItem": {...}}) ou un objet simple. L’atelier montre les clés, les valeurs absentes et la présence de pairedItem.

Le tableau est traité localement dans votre navigateur. Aucune donnée n’est envoyée.

🛠 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

Merge Node

• 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.

Switch / If

Dirige le trafic. Le "Switch" est plus propre que des "If" en cascade.
Ex: Routez par "Type de Client" (VIP, Standard, Prospect).

Loop Over Items (ex-Split In Batches)

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."

Code Node

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.

Règle simple : si vous devez expliquer un nœud à voix haute pendant plus de trente secondes, il manque soit un commentaire, soit un découpage. Le workflow doit rester lisible six mois plus tard, pas seulement le jour de la démonstration.

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.
Version 0 € : remplacez l’API payante par le quota gratuit de Hunter.io (vérification d’emails, environ 25 par mois au moment de la rédaction) ou par les données déjà dans votre CRM. Au-delà, Apollo et consorts sont payants : chiffrez le coût par lead avant la prod. Starter importable : wf-lead-enrichment.json (Webhook → HTTP Request → IF → Set → Respond).
Astuce Pro : Nommez TOUJOURS vos nœuds (ex: "Get_User_Data" au lieu de "HTTP Request 1"). Votre "Future You" (dans 3 mois) vous remerciera quand il faudra déboguer $('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).

Non testés à l’import : schémas calqués sur des exports réels, mais validez dans votre version de n8n avant la prod.

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).

chaine_noeuds.txt
Form (n8n) -> NocoDB (lire Réservations) -> Code (chevauchement, motif m14)
  -> IF libre ? -> NocoDB (créer) -> SMTP (confirmation)
Pas à pas : 1. NocoDB : tables Salles et Réservations (salle, début, fin, email). 2. n8n : Form Trigger (salle, créneau, email). 3. Lire les réservations de la salle. 4. Nœud Code : motif chevauchement du module 14, puis IF. 5. Conflit : répondre "créneau pris" ; sinon créer la réservation. 6. SMTP : confirmation immédiate + rappel J-1 via Schedule.