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

> Importez des produits et des variantes de produits liés à des produits maîtres et des catalogues existants.

L'import Produits crée les articles vendables réels : des produits simples sans variantes, ou des variantes rattachées à un produit maître. Importez les produits maîtres **en premier** si vos produits y font référence.

<Note>
  Vous devez disposer du rôle **Admin** avec l'autorisation **Données → Importer CSV**.
</Note>

## Ouvrir l'import

<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">
    Cochez la carte **Produits** en haut de la page.
  </Step>

  <Step title="Cliquer sur Télécharger le fichier d'exemple">
    Obtenez le CSV d'exemple avec les bonnes colonnes.
  </Step>

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

## Référence des colonnes CSV

Le modèle Produits utilise les mêmes colonnes que les Produits maîtres. La différence réside dans ce que vous renseignez — pour les produits et les variantes, les lignes référencent un produit maître existant via `parent_product_api_name` ou sont des articles autonomes à variante unique.

| Colonne                            | Requis | Type    | Description                                                                                                                 |
| ---------------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `product_id`                       | —      | UUID    | Laissez vide pour **créer** un nouveau produit. Renseignez un UUID existant pour **mettre à jour**.                         |
| `product_name`                     | \*     | Texte   | Nom d'affichage du produit ou de la variante (par exemple, `T-Shirt Premium - Bleu / M`).                                   |
| `product_api_name`                 | —      | Texte   | Identifiant API stable pour ce produit ou cette variante spécifique.                                                        |
| `reference`                        | —      | Texte   | Référence interne affichée aux commerciaux.                                                                                 |
| `product_description`              | —      | Texte   | Description longue affichée sur les devis et dans le Dealroom.                                                              |
| `primary_image_id`                 | —      | UUID    | UUID d'une image déjà téléchargée dans la médiathèque Qwoty.                                                                |
| `settings[recurrence_type]`        | \*     | Enum    | `one_off` ou `recurring`. Doit correspondre au type de récurrence du produit maître si rattaché à un maître.                |
| `settings[is_active]`              | —      | Booléen | `true` (par défaut) ou `false`.                                                                                             |
| `settings[product_type]`           | —      | Enum    | `physical`, `service` ou `subscription`.                                                                                    |
| `settings[unit_of_measure]`        | —      | Texte   | Unité d'affichage (par exemple, `unit`, `kg`, `hour`).                                                                      |
| `settings[language_code]`          | —      | Texte   | Code de langue à deux lettres (`en`, `fr`, `de`).                                                                           |
| `settings[unit_per_pack]`          | —      | Nombre  | Nombre d'unités par pack, lorsque vendu en packs.                                                                           |
| `catalog_api_names`                | —      | Texte   | Noms d'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 d'API de catégories séparés par des virgules.                                                                          |
| `inventory[sku]`                   | —      | Texte   | SKU pour ce produit ou cette variante.                                                                                      |
| `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 pour les rapports financiers.                                                                      |
| `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`).                                                                               |
| `shipping[harmonized_system_code]` | —      | Texte   | Code du Système Harmonisé (SH) pour l'expédition internationale.                                                            |

<Warning>
  Lorsque `catalog_api_names` ou `category_api_names` contiennent plusieurs valeurs, la cellule doit être entourée de guillemets doubles et utiliser des **virgules** comme séparateur interne : `"france,partner_pricing"`. Sans les guillemets, la virgule à l'intérieur de la cellule casse la ligne CSV.
</Warning>

<Info>
  Les variantes rattachées à un produit maître héritent des valeurs `settings[recurrence_type]`, `settings[product_type]` et des paramètres d'expédition par défaut du maître. Vous pouvez tout de même les définir sur la ligne de la variante pour les remplacer — mais ils doivent être cohérents, sinon Qwoty rejette la ligne.
</Info>

## Scénarios courants

### Créer des produits simples à variante unique

Pour une liste de produits ponctuels sans variantes :

```csv theme={null}
product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],catalog_api_names,inventory[sku]
,Wireless Mouse,wireless_mouse,one_off,physical,france,SKU-001
,USB-C Cable,usb_c_cable,one_off,physical,france,SKU-002
,Laptop Stand,laptop_stand,one_off,physical,france,SKU-003
```

### Créer des variantes rattachées à des produits maîtres existants

Vous avez déjà importé un produit maître `Premium T-Shirt` avec `product_api_name = premium_tshirt`. Ajoutez maintenant trois variantes :

```csv theme={null}
product_id,product_name,settings[recurrence_type],inventory[sku],identifiers[erp]
,Premium T-Shirt - Blue / S,one_off,SKU-PT-BS,ERP-PT-BS
,Premium T-Shirt - Blue / M,one_off,SKU-PT-BM,ERP-PT-BM
,Premium T-Shirt - Blue / L,one_off,SKU-PT-BL,ERP-PT-BL
```

<Info>
  La façon dont les variantes se rattachent aux produits maîtres dépend de la configuration de votre espace de travail (généralement via `parent_product_api_name` ou `product_parent_id`). Consultez le fichier d'exemple téléchargé depuis l'écran d'import — il inclut les colonnes de relation spécifiques à votre espace de travail.
</Info>

### Mettre à jour des produits existants

Exportez vos produits actuels pour récupérer leurs UUID, puis réimportez-les avec les modifications :

```csv theme={null}
product_id,product_name,inventory[sku]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,Wireless Mouse Pro,SKU-001-PRO
9b7ccfa9-1234-5678-aabb-c0ffee123456,USB-C Cable v2,SKU-002-V2
```

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

### Mise à jour en masse des SKU dans les catalogues

Utile lors de la migration depuis un autre système :

```csv theme={null}
product_id,inventory[sku],identifiers[erp]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,NEW-SKU-001,ERP-NEW-001
9b7ccfa9-1234-5678-aabb-c0ffee123456,NEW-SKU-002,ERP-NEW-002
```

## Résolution des problèmes

<AccordionGroup>
  <Accordion title="Mon import a échoué en raison d'un recurrence_type invalide">
    Les seules valeurs acceptées pour `settings[recurrence_type]` sont `one_off` et `recurring` (en minuscules, avec underscore). Erreurs courantes : `monthly`, `yearly`, `subscription`, `one-off` (avec tiret).
  </Accordion>

  <Accordion title="La colonne catalog_api_names référence un catalogue introuvable">
    Qwoty fait correspondre les noms d'API de catalogues de manière exacte (sensible à la casse). Vérifiez les noms d'API de catalogues dans **Catalogue & Produits → Catalogues**. Pour plusieurs catalogues, utilisez des virgules dans la cellule sans espaces, et entourez la valeur de guillemets doubles : `"france,partner_pricing"`.
  </Accordion>

  <Accordion title="Les lignes primary_image_id échouent avec 'Référence inconnue'">
    L'UUID dans `primary_image_id` ne correspond à aucune image de votre médiathèque. Téléchargez d'abord vos images, exportez la liste des médias pour obtenir leurs UUID, puis mettez à jour votre CSV.
  </Accordion>

  <Accordion title="Un produit a été créé mais n'apparaît pas dans le catalogue">
    Vérifiez que `catalog_api_names` est renseigné. Si vide, le produit est rattaché uniquement au catalogue par défaut de l'espace de travail (qui peut être masqué pour vos commerciaux).
  </Accordion>

  <Accordion title="Ma mise à jour par product_id a remplacé des champs que je n'avais pas inclus">
    Les mises à jour ne modifient que les colonnes présentes dans le CSV. Si un champ semble vide après l'import, vérifiez que vous n'avez pas laissé l'en-tête de colonne dans le fichier avec des valeurs toutes vides — cela écrase le champ.
  </Accordion>

  <Accordion title="Mon champ booléen a renvoyé une erreur">
    Utilisez `true` ou `false` en minuscules. Les valeurs `TRUE` ou `FALSE` en majuscules, ou `1` / `0`, sont rejetées.
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Importer des prix" icon="tag" href="/user-guide/data-migration/how-tos/import-prices">
    Maintenant que les produits existent, associez-leur des prix.
  </Card>

  <Card title="Importer des produits maîtres" icon="layer-group" href="/user-guide/data-migration/how-tos/import-master-products">
    Si vous avez sauté cette étape, importez d'abord les produits maîtres.
  </Card>

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

  <Card title="Catalogues" icon="box" href="/user-guide/catalog/introduction">
    Gérez l'emplacement de vos produits.
  </Card>
</CardGroup>