Importer et exporter

De quoi s’agit-il ?

La fenêtre Importer / Exporter des ingrédients vous permet de charger votre propre catalogue d’ingrédients personnalisés depuis un fichier (par lot, sans les créer un par un) ou de le télécharger pour le conserver en dehors de l’application.

Chemin d’accès

Depuis le catalogue d’ingrédients, cliquez sur le bouton Importer / Exporter de l’en-tête. La fenêtre comporte deux onglets : Importer et Exporter.

Importer

Commencez avec le modèle

Si vous n’avez pas encore de fichier, cliquez sur Télécharger le modèle CSV (dans l’encadré « Vous ne savez pas par où commencer ? Téléchargez le modèle avec des exemples et modifiez-le. »). Le fichier modele-ingredients-areacacao.csv est téléchargé, avec l’en-tête correct et deux lignes d’exemple (Praliné noisette et Couverture noire 70 %) que vous pouvez modifier ou supprimer. Le nom du fichier et le texte des exemples suivent la langue de l’interface ; les noms de colonnes sont toujours les mêmes, en anglais.

Le modèle comprend ces 24 colonnes (toutes facultatives sauf name) :

name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

Comment préparer le CSV ?

La fenêtre comporte un menu dépliant Comment préparer le CSV ? avec les règles. En détail :

• Seul name est obligatoire. Laissez vides les colonnes que vous n’avez pas.
• Les valeurs nutritionnelles sont pour 100 g (comme dans la fiche).
• Séparateur décimal : le point ou la virgule sont acceptés (18.50 ou 18,50, format français compris). Si vous utilisez la virgule comme séparateur décimal, le point est interprété comme séparateur de milliers (1.234,56 se lit mille deux cent trente-quatre virgule cinquante-six).
• allergens : liste de codes séparés par ;. Les codes valides sont les 14 codes officiels de l’UE : gluten, crustaceans, eggs, fish, peanuts, soy, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs. Tout code hors de cette liste est ignoré. Voir Allergènes UE-14.
• allergens vide = sans allergènes. Si vous ne les connaissez pas encore, saisissez undeclared (la valeur sin declarar est aussi acceptée) : les allergènes de la fiche restent non déclarés, ce qui n’est pas la même chose que « sans allergènes ».
• alcohol : grammes d’éthanol pour 100 g (vins et liqueurs). Vide = pas de donnée.
• Les micronutriments (vitamines, minéraux, cholestérol, caféine) ne se chargent pas par CSV : ils se renseignent dans la fiche de l’ingrédient. (Si vous en avez besoin dans un fichier, utilisez le format JSON, qui les conserve.)

Charger les données

Vous avez trois façons de fournir le contenu :

• Glisser-déposer un fichier dans la zone « Glissez un fichier CSV ou JSON ici ».
• Cliquer sur Choisir un fichier et sélectionner un .csv ou un .json sur votre ordinateur.
• Déplier Ou coller du texte manuellement et coller directement le contenu.

L’application détecte automatiquement le format (si le texte commence par { ou [, elle le traite comme du JSON ; sinon, comme du CSV) et l’affiche dans le sélecteur Format détecté, que vous pouvez corriger à la main si nécessaire. Les sélecteurs Format détecté et Mode et les boutons apparaissent dès qu’un contenu est chargé.

Choisissez le mode

Le sélecteur Mode détermine comment l’import est appliqué. La correspondance avec vos ingrédients existants se fait par nom (sans distinction de majuscules/minuscules) :

Prévisualisez et confirmez

Ce qui est importé de chaque ligne

Ces champs sont reconnus : name (obligatoire), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (par défaut g), densityGPerMl, weightPerUnitG, les 12 valeurs nutritionnelles (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol), allergens et notes. Les en-têtes ne tiennent pas compte des majuscules et quelques alias sont acceptés (customCode/custom_code, baseUnit/base_unit/unit). Toute colonne absente de la liste est ignorée sans erreur.

Erreurs que vous verrez :

• Une ligne sans nom est ignorée et signalée par « Ligne N : Le nom est manquant ».
• Un fichier mal formé est rejeté en entier : « Le fichier CSV est vide ou ne contient aucune ligne de données », « JSON non valide : … » ou « JSON : tableau « ingredients » introuvable ».

Le serveur envoie ces messages dans la langue de l’interface. Dans « JSON non valide : … », le détail technique qui suit les deux-points provient tel quel de l’analyseur JSON, en général en anglais.

Exporter

Dans l’onglet Exporter (« Téléchargez votre catalogue personnalisé. Le format JSON conserve les structures complexes (macronutriments, allergènes) ; le CSV est idéal pour l’édition dans Excel/Sheets. »), vous disposez de deux options de téléchargement direct. Seuls vos ingrédients actifs sont exportés (ceux qui ont été supprimés ne sont pas inclus).

Exporter en JSON

« Format complet pour sauvegarde ou migration vers une autre instance. » Télécharge la fiche complète de chaque ingrédient telle qu’elle est enregistrée, y compris ce que le CSV ne représente pas : les micronutriments (qui se trouvent dans macros), les autres noms et les champs personnalisés. C’est le format recommandé pour la sauvegarde. La structure est la suivante :

{
  "version": 1,
  "exportedAt": "2026-06-01T…Z",
  "count": 12,
  "ingredients": [
    { "id": "ci_…", "name": "…", "macros": { "fat": 42, "vitaminE": 5 }, "allergens": ["nuts"], "altNames": [], "customFields": {} }
  ]
}

Chaque objet de ingredients est la fiche complète de l’ingrédient (abrégée ici).

Exporter en CSV

« Tableau simple à ouvrir dans Excel/Sheets/Numbers. » Télécharge un tableau à plat (fichier custom-ingredients-AAAA-MM-JJ.csv), idéal pour relire ou modifier les données dans un tableur. Le CSV contient les macronutriments mais pas les micronutriments (pour ceux-ci, utilisez le JSON).

Colonnes du CSV

Le menu dépliant Colonnes CSV de la fenêtre liste les 25 colonnes du fichier exporté, dans cet ordre :

id, name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

La colonne allergens est une liste séparée par des points-virgules (par exemple gluten;milk) ; elle est vide si la fiche n’a pas d’allergènes et contient undeclared s’ils ne sont pas déclarés. La seule différence avec le modèle d’import est la colonne id (présente à l’export, ignorée à l’import).

Notes et limites

• Aller-retour par nom. Exporter puis réimporter fonctionne : la correspondance se fait par nom, la colonne id du CSV exporté n’est donc pas nécessaire à la réimportation.
• CSV ou JSON. Utilisez le CSV pour une modification rapide dans un tableur (macronutriments, sans micronutriments) ; utilisez le JSON pour la sauvegarde : c’est le seul format qui contient les micronutriments. À la réimportation, le JSON conserve macronutriments et micronutriments, mais pas les autres noms ni les champs personnalisés.
• Taille. Il n’y a pas de plafond de lignes, mais la requête est limitée à ~5 Mo. Pour les très gros catalogues, répartissez le fichier sur plusieurs imports.
• Confidentialité. Tout porte sur le catalogue de votre compte ; ni l’import ni l’export ne touchent au catalogue public.

Étapes suivantes