Node Convert to File n8n : transformer vos items JSON en fichiers (guide)

Un workflow n8n peut interroger une base, filtrer, enrichir et scorer des milliers de lignes sans jamais quitter le monde du JSON. Puis vient le dernier mètre : envoyer un rapport en pièce jointe, déposer un export sur un bucket, répondre à un webhook avec un document téléchargeable. Le JSON ne suffit plus — il faut un vrai fichier, avec un nom, une extension et un type MIME. C'est le rôle du node Convert to File (n8n-nodes-base.convertToFile). Ce guide détaille ses dix opérations, les options qui comptent, son node miroir Extract from File, et les erreurs qui font échouer un workflow parfait juste avant l'arrivée.

Le modèle de données : json d'un côté, binary de l'autre

Chaque item n8n est un objet à deux clés possibles. La clé json porte les données structurées que manipulent la plupart des nodes ; la clé binary porte les fichiers, sous forme d'une ou plusieurs binary properties nommées — data par défaut, mais rien n'oblige à s'y tenir. Chaque binary property expose des champs documentés : data (le contenu, encodé en base64 en interne), mimeType, fileName, fileExtension, fileSize, fileType et id.

{
  "json": { "client": "Dupont", "montant": 1250 },
  "binary": {
    "data": {
      "fileName": "rapport-2026-08.csv",
      "mimeType": "text/csv",
      "fileExtension": "csv",
      "fileSize": "18 kB"
    }
  }
}

La quasi-totalité des problèmes de fichiers dans n8n se résument à une binary property mal nommée, un mimeType absent ou un fileName sans extension. Convert to File est l'outil qui remplit ces champs.

Les dix opérations du node Convert to File

Les formats tabulaires : CSV, XLSX, ODS, XLS, HTML, RTF

Six opérations transforment la liste d'items en tableau : Convert to CSV, Convert to XLSX, Convert to XLS, Convert to ODS, Convert to HTML (qui produit un tableau HTML) et Convert to RTF. Toutes partagent le paramètre obligatoire Put Output File in Field, qui indique dans quelle binary property écrire le résultat — data par défaut — et les options File Name et Header Row (désactivé par défaut) : sans ce dernier, votre CSV part sans ligne d'en-têtes. Les opérations tableur ajoutent Sheet Name ; XLSX et ODS proposent en plus Compression.

Un point à connaître : Convert to CSV n'expose pas d'option de délimiteur, le fichier produit utilise la virgule. Si votre destinataire exige un point-virgule — le cas fréquent d'un Excel en français —, construisez la chaîne avec un node Code puis passez par Convert to Text File, ou livrez un XLSX. Cette question du dialecte CSV n'a rien d'anecdotique : dans « Wrangling messy CSV files by detecting row and type patterns », publié en 2019 dans Data Mining and Knowledge Discovery, Gerrit J. J. van den Burg, Alfredo Nazábal et Charles Sutton montrent que la détection automatique du délimiteur, du guillemet et du caractère d'échappement échoue régulièrement sur des fichiers réels, et proposent une méthode qui améliore la précision de près de 22 % sur les CSV « sales » (voir sur Google Scholar). Un CSV n'est jamais aussi universel qu'il en a l'air, et livrer un XLSX supprime toute cette classe de bugs.

Convert to JSON : le paramètre Mode change tout

L'opération Convert to JSON se distingue des autres : au lieu de Put Output File in Field, elle expose un paramètre Mode à deux valeurs :

• All Items to One File — un seul fichier .json contenant le tableau complet des items ;
• Each Item to Separate File — un fichier par item, donc autant d'items en sortie.

Les options sont File Name, Format (qui indente le JSON, désactivé par défaut) et Encoding (utf8 par défaut). Le mode par item sert à archiver chaque enregistrement séparément ; il devient un piège quand on cherchait un export unique et qu'on récupère 4 000 fichiers à uploader un par un.

Convert to Text File et Convert to ICS

Convert to Text File prend un paramètre Text Input Field : le champ JSON dont le contenu devient le fichier. C'est l'opération pour tout ce que vous avez composé vous-même — Markdown généré par un LLM, XML assemblé en amont, CSV à délimiteur exotique. Options : File Name et Encoding.

Convert to ICS génère un fichier iCalendar à partir de Event Title et Start, complétés par End (qui reprend la date de début si on l'omet) et All Day. Les options couvrent un vrai événement : Attendees, Description, Location, Organizer, Recurrence Rule, Busy Status, Calendar Name, UID et Use Workflow Timezone. Joint à une confirmation de rendez-vous, un .ics s'ajoute en un clic dans Outlook ou Google Agenda.

Move Base64 String to File : l'opération qui sauve les intégrations

Beaucoup d'API ne renvoient pas un fichier mais une chaîne base64 dans un champ JSON — un PDF de facture, une signature électronique, une image générée. Move Base64 String to File prend un paramètre Base64 Input Field (le chemin du champ, en dot notation) et deux options : File Name et MIME Type. Ne négligez pas ce dernier : sans lui, le fichier circule sans type déclaré et le comportement en aval devient imprévisible — pièce jointe affichée en application/octet-stream, mauvais Content-Type servi par un stockage objet, navigateur qui télécharge au lieu d'afficher.

// Nettoyer un data URI avant Move Base64 String to File
const raw = $json.document.content;
return [{ json: { b64: raw.replace(/^data:[^;]+;base64,/, '') } }];

Extract from File : le node miroir

Le node Extract from File fait le chemin inverse : il prend une binary property (paramètre Input Binary Field, data par défaut) et en sort du JSON. Ses opérations couvrent Extract From CSV, XLSX, XLS, ODS, JSON, HTML, ICS, PDF, RTF, Text File, plus Move File to Base64 String. Plusieurs exposent un Destination Output Field pour choisir où atterrit le résultat.

Extract et Convert forment un aller-retour complet, détaillé dans notre guide dédié à l'extraction et à la génération de fichiers Excel et CSV : lire un XLSX déposé sur Drive, transformer les lignes, réécrire un XLSX propre. Ne les confondez ni l'un ni l'autre avec le node Read/Write Files from Disk, seul des trois à toucher au système de fichiers de l'instance.

Aggregate en amont, la boucle en piège

Les opérations tabulaires regroupent nativement tous les items entrants dans un fichier unique. Mais dès qu'il faut remodeler la structure avant l'export — ne garder que certains champs, aplatir un tableau imbriqué, regrouper par client — le node Aggregate devient l'étape préalable naturelle, comme l'explique notre guide sur les nodes Split Out et Aggregate. Le piège symétrique est plus insidieux : placer le Convert to File à l'intérieur d'une boucle Loop Over Items. Le node s'exécute une fois par batch et produit autant de fichiers partiels, sans lever la moindre erreur — dix emails partent avec dix CSV incomplets.

Cinq cas d'usage

• Rapport hebdomadaire en pièce jointe : Convert to CSV, Header Row activé, File Name daté, puis un envoi via le node SMTP pointant sur data ;
• Export XLSX déposé sur un stockage : Convert to XLSX avec Sheet Name explicite, puis un upload vers Google Drive ou un archivage sur S3 ;
• Trace d'audit JSON : Convert to JSON en mode All Items to One File, option Format activée, déposé sur un SFTP en écriture seule. Le format n'est pas neutre pour ce type d'archive : dès 2009, Nurzhan Nurseitov, Michael Paulson, Randall Reynolds et Clemente Izurieta mesuraient dans « Comparison of JSON and XML Data Interchange Formats: A Case Study », présenté à la conférence CAINE, que JSON sérialisait et transmettait les mêmes objets un ordre de grandeur plus vite que XML — une étude déjà ancienne, mais dont l'écart de performance n'a jamais été démenti (voir sur Google Scholar) ;
• Confirmation de rendez-vous : Convert to ICS avec Attendees et Location, joint à l'email ;
• PDF fournisseur en base64 : Move Base64 String to File avec application/pdf en MIME Type, en amont d'un pipeline de génération de devis et factures PDF.

Les pièges classiques

• Confondre Convert to File et Read/Write Files from Disk : le premier ne crée aucun fichier sur le serveur. Inutile de chercher le CSV dans /tmp — il vit uniquement dans l'item ;
• Le MIME type absent : après un Move Base64 String to File sans option MIME Type, la pièce jointe arrive en application/octet-stream, certains filtres antispam la bloquent et le destinataire doit la renommer à la main ;
• Le nom sans extension : rapport au lieu de rapport.csv. Windows ne sait pas quoi en faire et plusieurs API de stockage refusent l'objet ;
• L'écrasement de la binary property data : deux Convert to File successifs écrivant tous deux dans data ne produisent qu'un fichier, le second. Changez Put Output File in Field (facture, annexe) — c'est aussi la condition pour zipper les deux d'un coup avec le node Compression ;
• L'UTF-8 et Excel : un CSV UTF-8 double-cliqué sous Windows affiche des accents cassés. XLSX règle la question ;
• La mémoire sur gros volumes : chaque fichier généré occupe de la RAM pendant toute l'exécution. Sur des exports lourds, basculez N8N_DEFAULT_BINARY_DATA_MODE sur filesystem (gestion des fichiers volumineux) ;
• Répondre à un webhook avec un fichier : le node Respond to Webhook doit être réglé sur une réponse binaire et pointer la bonne binary property, sinon le client reçoit du JSON.

En résumé

Convert to File est la charnière entre le JSON de n8n et tout ce qui attend un vrai fichier. Trois réglages font l'essentiel : Put Output File in Field, File Name (avec l'extension) et, pour les formats tabulaires, Header Row. Ajoutez MIME Type pour Move Base64 String to File et Mode pour Convert to JSON. Le reste — Extract from File pour le retour, Aggregate pour le regroupement, le mode filesystem pour le volume — se déduit du besoin.

Pour aller plus loin

Générer le bon fichier est rarement une fin en soi : c'est la dernière étape d'une chaîne de traitement. Le Pack Conformité & Audit (149 €) montre comment cet export devient une pièce justificative — journal JSON horodaté, rapport CSV archivé, trace déposée sur un stockage externe. Le Pack Inbox IA (79 €) illustre le chemin inverse : extraire les données d'une pièce jointe entrante, les traiter, puis renvoyer un fichier propre.