> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Importer des produits maîtres

> Créez des produits maîtres qui regroupent plusieurs variantes. Importez-les toujours en premier.

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.

<Note>
  Vous devez disposer du rôle **Admin** avec l'autorisation **Données → Importer CSV**. Consultez [Gérer les rôles](/user-guide/settings/users/manage-roles) pour les détails sur les permissions.
</Note>

## Ouvrir l'importation

<Steps>
  <Step title="Ouvrir les Paramètres">
    Dans la barre latérale gauche, cliquez sur **Paramètres**.
  </Step>

  <Step title="Accéder à Importer/Exporter des données">
    Dans la section **Données**, cliquez sur **Importer/Exporter**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Cliquer sur Télécharger le fichier exemple">
    Obtenez le CSV d'exemple avec les bons en-têtes de colonnes.
  </Step>

  <Step title="Cliquer sur Importer">
    Déposez votre fichier préparé. L'assistant en 4 étapes s'exécute : **Téléchargement → Correspondance → Confirmation → Résultat**.
  </Step>
</Steps>

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

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

## 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 :

```csv theme={null}
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](/user-guide/data-migration/how-tos/import-products), 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 :

```csv theme={null}
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 :

```csv theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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"`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Importer des produits" icon="box" href="/user-guide/data-migration/how-tos/import-products">
    Maintenant que les maîtres existent, importez les variantes qui les référencent.
  </Card>

  <Card title="Importer des prix" icon="tag" href="/user-guide/data-migration/how-tos/import-prices">
    Une fois les produits créés, associez-leur des prix.
  </Card>

  <Card title="Préparer votre CSV" icon="file-spreadsheet" href="/user-guide/data-migration/how-tos/prepare-csv-files">
    Règles de mise en forme universelles.
  </Card>

  <Card title="Variantes et options" icon="sitemap" href="/user-guide/catalog/reference/variants-and-options">
    Référence conceptuelle sur la structure maître/variante.
  </Card>
</CardGroup>