Importer des produits maîtres

Un produit maître est le parent qui regroupe plusieurs variantes — par exemple, un maître “T-Shirt Premium” avec les variantes Small, Medium, Large. Importez toujours les produits maîtres avant leurs variantes et leurs prix, car ils constituent le parent auquel tout le reste fait référence.

Vous devez disposer du rôle Admin avec l’autorisation Données → Importer CSV. Consultez Gérer les rôles pour les détails sur les permissions.

Ouvrir l’importation

Ouvrir les Paramètres

Dans la barre latérale gauche, cliquez sur Paramètres.

Accéder à Importer/Exporter des données

Dans la section Données, cliquez sur Importer/Exporter.

Sélectionner Produits maîtres

Cochez la carte Produits maîtres en haut de la page. Les sections Importation et Exportation ci-dessous s’adaptent.

Cliquer sur Télécharger le fichier exemple

Obtenez le CSV d’exemple avec les bons en-têtes de colonnes.

Cliquer sur Importer

Déposez votre fichier préparé. L’assistant en 4 étapes s’exécute : Téléchargement → Correspondance → Confirmation → Résultat.

Référence des colonnes CSV

L’importation des produits maîtres utilise le même modèle que les Produits — la différence réside dans la façon dont vous remplissez les lignes. Pour les produits maîtres, chaque ligne crée un parent auquel les variantes feront référence. Vous laissez vides les champs spécifiques aux variantes.

Colonne	Requis	Type	Description
`product_id`	—	UUID	Laissez vide pour créer un nouveau maître. Définissez sur un UUID existant pour mettre à jour.
`product_name`	*	Texte	Nom d’affichage du produit maître affiché dans le catalogue et sur les devis.
`product_api_name`	—	Texte	Identifiant API stable. Fortement recommandé — les variantes référenceront le maître via ce nom.
`reference`	—	Texte	Référence interne affichée aux commerciaux.
`product_description`	—	Texte	Description longue affichée sur les devis et dans la Dealroom.
`primary_image_id`	—	UUID	UUID d’une image déjà téléchargée dans la bibliothèque multimédia Qwoty.
`settings[recurrence_type]`	*	Enum	`one_off` pour un achat unique, `recurring` pour les abonnements. Toutes les variantes de ce maître héritent de cette valeur.
`settings[is_active]`	—	Booléen	`true` (par défaut) pour rendre le maître visible dans les catalogues, `false` pour archiver.
`settings[product_type]`	—	Enum	`physical`, `service` ou `subscription`. Détermine le comportement des devis et les rapports.
`settings[unit_of_measure]`	—	Texte	Unité d’affichage (par exemple, `unit`, `kg`, `hour`).
`settings[language_code]`	—	Texte	Code de langue à deux lettres pour le contenu localisé (`en`, `fr`, `de`).
`settings[unit_per_pack]`	—	Nombre	Si le maître est vendu en packs, le nombre d’unités par pack.
`catalog_api_names`	—	Texte	Noms API de catalogues séparés par des virgules. Une valeur vide rattache le catalogue par défaut de l’espace de travail.
`category_api_names`	—	Texte	Noms API de catégories séparés par des virgules.
`inventory[sku]`	—	Texte	SKU au niveau du maître (les variantes le remplacent par le leur).
`identifiers[erp]`	—	Texte	Identifiant ERP externe.
`identifiers[crm]`	—	Texte	Identifiant CRM externe.
`identifiers[accounting]`	—	Texte	Identifiant comptable externe.
`accounting[ledger_account]`	—	Texte	Code de compte comptable utilisé pour les rapports de comptabilité.
`shipping[weight]`	—	Nombre	Poids net.
`shipping[weight_unit]`	—	Enum	`kg`, `g`, `lb`, `oz`.
`shipping[height]`	—	Nombre	Hauteur en `shipping[length_unit]`.
`shipping[length]`	—	Nombre	Longueur en `shipping[length_unit]`.
`shipping[width]`	—	Nombre	Largeur en `shipping[length_unit]`.
`shipping[length_unit]`	—	Enum	`cm`, `mm`, `m`, `in`.
`shipping[country_of_origin]`	—	Texte	Code pays ISO à 2 lettres (`FR`, `DE`, `CN`). Utilisé pour les documents douaniers et commerciaux.
`shipping[harmonized_system_code]`	—	Texte	Code du Système Harmonisé (SH) pour l’expédition internationale et les douanes.

Lors de l’importation d’un maître, vous laissez généralement vides les champs spécifiques aux variantes comme inventory[sku] si chaque variante possède son propre SKU. Utilisez la ligne maître pour définir les valeurs par défaut qui s’appliquent à toutes les variantes (type de récurrence, type de produit, dimensions d’expédition pour les produits physiques sans variation).

Scénarios courants

Créer des produits maîtres sans variantes

Pour les produits sans variantes — un maître à SKU unique auquel seront ultérieurement rattachées une ou plusieurs variantes :

product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],catalog_api_names
,Premium T-Shirt,premium_tshirt,one_off,physical,france
,Annual SaaS Plan,annual_saas_plan,recurring,subscription,saas_catalog
,Consulting Day,consulting_day,one_off,service,services

Après cette importation, vous pouvez ajouter des variantes à chaque maître via l’importation des Produits, en les référençant par product_api_name.

Créer des produits maîtres avec des données d’expédition complètes

Pour les biens physiques nécessitant des informations d’expédition détaillées :

product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],shipping[weight],shipping[weight_unit],shipping[height],shipping[length],shipping[width],shipping[length_unit],shipping[country_of_origin],shipping[harmonized_system_code]
,Premium T-Shirt,premium_tshirt,one_off,physical,0.2,kg,2,30,25,cm,FR,610910
,Coffee Mug,coffee_mug,one_off,physical,0.4,kg,12,9,9,cm,DE,691200

Mettre à jour des produits maîtres existants

Lorsque product_id est renseigné, la ligne met à jour plutôt que de créer :

product_id,product_description,settings[is_active]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,T-shirt premium en coton 100% biologique avec coutures renforcées.,true
9b7ccfa9-1234-5678-aabb-c0ffee123456,Arrêté — remplacé par SKU-MUG-V2.,false

Seules les colonnes que vous incluez sont mises à jour. Les autres champs restent inchangés.

Résolution des problèmes

Deux produits non liés ont été fusionnés dans le même maître

Ils partageaient le même product_name et aucun n’avait de product_api_name. Réimportez avec un product_api_name unique par maître.

settings[recurrence_type] a été rejeté

Utilisez exactement one_off ou recurring (minuscules, avec tiret bas). Erreurs courantes : monthly, yearly, subscription, one-off (avec tiret).

Ma valeur catalog_api_names n'est pas reconnue

Qwoty fait correspondre les noms API de catalogue exactement (sensible à la casse). Vérifiez le nom API dans Catalogue & Produits → Catalogues et réimportez. Pour plusieurs catalogues dans une même cellule, utilisez des virgules sans espaces et encadrez la cellule de guillemets doubles : "france,partner_pricing".

primary_image_id est rejeté comme 'Référence inconnue'

L’image doit exister dans la bibliothèque multimédia Qwoty avant l’importation. Téléchargez d’abord vos images, puis exportez la liste des médias pour récupérer leurs UUID.

settings[is_active] = TRUE a retourné une erreur

Les valeurs booléennes doivent être en minuscules : true ou false. Les valeurs TRUE ou FALSE en majuscules sont rejetées.

Étapes suivantes