Créer un produit
/v1/products
Crée un produit, avec ses variantes s'il en a, et renvoie le produit complet tel que le donne GET /v1/products/{id}. Un seul produit par appel : pour en créer plusieurs, faites un appel par produit.
Avant de créer, vérifiez que le produit n'existe pas déjà avec GET /v1/products/lookup (par code-barres, référence fournisseur ou désignation). L'API ne refuse pas deux produits de même nom ou de même référence.
Seul designation est obligatoire. Sans variantes_product, le produit est créé sans variante et ses codes (bc_ext, sku) se donnent à la racine. Avec variantes_product, chaque variante porte ses propres codes et ses écarts de prix. Le code-barres interne ean_int n'est jamais envoyé : Wanapos le génère pour le produit et pour chaque variante.
Le fournisseur, la collection, la catégorie et les valeurs de liste personnalisée se donnent par leur nom ou par leur identifiant, jamais les deux. Par son nom, un classement inconnu est créé au passage : la réponse liste ce qui a été créé dans meta.created_listings. Un nom est rapproché sans tenir compte des majuscules, des accents ni des espaces autour (nike retrouve Nike). Attention aux fautes de frappe : Nikee créerait un second fournisseur. Par son identifiant, un classement inconnu est refusé. La catégorie se donne par son chemin complet, du niveau le plus général au plus précis.
Un code-barres externe (bc_ext) déjà porté par une variante en service d'un autre produit est refusé : l'erreur duplicate_barcode donne l'identifiant du produit qui le porte. Si deux produits partagent réellement ce code, renvoyez avec ?allow_duplicate_bc_ext=true.
Le produit est créé sans stock : le stock ne s'écrit pas par l'API. Il n'est envoyé vers aucune boutique en ligne reliée au compte. Son image, son écart de prix par magasin et ses produits liés se règlent dans l'application.
Cet appel compte comme une écriture. Utilisez ?dry_run=true pour tout vérifier sans rien enregistrer, et l'en-tête Idempotency-Key pour qu'un envoi répété après une coupure ne crée pas le produit deux fois.
Paramètres
dry_run |
Facultatif | true pour tout vérifier sans rien enregistrer : la réponse est celle que vous auriez obtenue, avec meta.dry_run à true. L'identifiant renvoyé n'est alors pas réservé. |
allow_duplicate_bc_ext |
Facultatif | true pour enregistrer même si un autre produit porte déjà un des codes-barres externes envoyés. À n'utiliser qu'après avoir vérifié qu'il s'agit bien de deux produits différents. |
Idempotency-Key |
Facultatif | Identifiant unique de votre choix (8 à 100 caractères). Si vous renvoyez la même requête avec le même identifiant, elle n'est pas exécutée deux fois : vous recevez la réponse d'origine. Recommandé pour toute création. |
Corps JSON à envoyer
| Champ | Type | Description |
|---|---|---|
designation |
texte | Nom du produit. Obligatoire, 50 caractères au maximum. |
description |
texte | Description. 1 500 caractères au maximum. |
notes |
texte | Notes internes. 500 caractères au maximum. |
ref_four |
texte | Référence du produit chez le fournisseur. 50 caractères au maximum. |
ref_interne |
texte | Référence interne. 50 caractères au maximum. |
gestion_stock |
booléen |
true pour suivre le stock de ce produit. Si absent : le réglage par défaut du commerçant. |
pa_ht |
nombre | Prix d'achat hors taxes. 0 si absent. |
pv_ttc |
nombre | Prix de vente de base, toutes taxes comprises. 0 si absent. |
eco_ttc |
nombre | Éco-participation, toutes taxes comprises, incluse dans le prix de vente. 0 si absente. |
tva_taux |
nombre | Taux de TVA du produit, en pourcentage (exemple : 20, 10, 5.5). Le taux doit exister dans Wanapos. Si absent : le taux de chaque magasin s'applique. |
fournisseur |
texte |
Fournisseur, par son nom (3 à 50 caractères). Si aucun ne porte ce nom (sans tenir compte des majuscules, des accents ni des espaces autour), il est créé. Ne pas envoyer avec id_fournisseur. |
id_fournisseur |
entier |
Fournisseur, par son identifiant. Il doit exister. Ne pas envoyer avec fournisseur. |
collec |
texte |
Collection, par son nom (3 à 50 caractères). Si aucune ne porte ce nom (sans tenir compte des majuscules, des accents ni des espaces autour), elle est créée. Ne pas envoyer avec id_collec. |
id_collec |
entier |
Collection, par son identifiant. Elle doit exister. Ne pas envoyer avec collec. |
categories |
liste de texte |
Catégorie du produit, donnée par son chemin complet, du niveau le plus général au plus précis (exemple : ["Vêtements", "Hauts"]). Un à cinq noms de 2 à 50 caractères. Les niveaux qui n'existent pas sont créés. Ne pas envoyer avec id_categorie. |
id_categorie |
entier |
Catégorie la plus précise du produit, par son identifiant. Elle doit exister ; ses catégories parentes sont retrouvées seules. Ne pas envoyer avec categories. |
libre_1 |
texte | Champ personnalisé texte n° 1. 50 caractères au maximum. |
libre_2 |
texte | Champ personnalisé texte n° 2. 50 caractères au maximum. |
libre_3 |
texte | Champ personnalisé texte n° 3. 50 caractères au maximum. |
custom_list_1 |
texte |
Champ personnalisé liste n° 1 : la valeur choisie, par son nom (2 à 50 caractères). Si la liste n° 1 ne contient pas cette valeur, elle y est ajoutée. Ne pas envoyer avec id_custom_list_1. |
custom_list_2 |
texte |
Champ personnalisé liste n° 2 : la valeur choisie, par son nom (2 à 50 caractères). Si la liste n° 2 ne contient pas cette valeur, elle y est ajoutée. Ne pas envoyer avec id_custom_list_2. |
custom_list_3 |
texte |
Champ personnalisé liste n° 3 : la valeur choisie, par son nom (2 à 50 caractères). Si la liste n° 3 ne contient pas cette valeur, elle y est ajoutée. Ne pas envoyer avec id_custom_list_3. |
id_custom_list_1 |
entier | Champ personnalisé liste n° 1 : la valeur choisie, par son identifiant. Elle doit exister dans cette liste. |
id_custom_list_2 |
entier | Champ personnalisé liste n° 2 : la valeur choisie, par son identifiant. Elle doit exister dans cette liste. |
id_custom_list_3 |
entier | Champ personnalisé liste n° 3 : la valeur choisie, par son identifiant. Elle doit exister dans cette liste. |
custom_io_1 |
booléen |
Champ personnalisé oui/non n° 1. false si absent. |
custom_io_2 |
booléen |
Champ personnalisé oui/non n° 2. false si absent. |
custom_io_3 |
booléen |
Champ personnalisé oui/non n° 3. false si absent. |
custom_date_1 |
texte | Champ personnalisé date n° 1, au format AAAA-MM-JJ. |
custom_date_2 |
texte | Champ personnalisé date n° 2, au format AAAA-MM-JJ. |
custom_date_3 |
texte | Champ personnalisé date n° 3, au format AAAA-MM-JJ. |
bc_ext |
texte |
Code-barres externe (celui du fabricant) d'un produit SANS variante. 32 caractères au maximum. Refusé si variantes_product est envoyé : le code se donne alors sur chaque variante. |
sku |
texte |
Référence SKU d'un produit SANS variante. 32 caractères au maximum. Refusé si variantes_product est envoyé. |
variantes_product |
liste | Variantes du produit (tailles, couleurs…), dans l'ordre d'affichage voulu. 1 à 100 variantes. Si ce champ est absent, le produit est créé sans variante. Chaque nom doit être différent. |
variantes_product[].name |
texte |
Nom de la variante (exemple : M, Bleu / 42). Obligatoire, 30 caractères au maximum. |
variantes_product[].bc_ext |
texte | Code-barres externe de la variante. 32 caractères au maximum. |
variantes_product[].sku |
texte | Référence SKU de la variante. 32 caractères au maximum. |
variantes_product[].impact_pv |
nombre |
Écart de prix de vente par rapport au pv_ttc du produit (exemple : 3 pour une variante vendue 3 de plus). 0 si absent. Peut être négatif. |
variantes_product[].impact_pa |
nombre |
Écart de prix d'achat par rapport au pa_ht du produit. 0 si absent. Peut être négatif. |
Exemple d'appel
curl -X POST "https://api.wanapos.com/v1/products" \
-H "Authorization: Bearer VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{"designation":"Tee-shirt col rond","description":"Coton bio, coupe droite.","ref_four":"TS-8744","pa_ht":12.5,"pv_ttc":29.9,"fournisseur":"Atelier Textile","collec":"Été 2026","categories":["Vêtements","Hauts"],"variantes_product":[{"name":"M","sku":"TS-M"},{"name":"XL","sku":"TS-XL","impact_pv":3}]}'
Réponse en cas de succès (statut 201)
Le produit créé, complet.
| Champ | Type | Description |
|---|---|---|
data |
objet | Un produit du catalogue, avec ses variantes, ses codes et ses prix. Le stock n'en fait pas partie. Voir tous les champs |
meta |
objet | |
meta.request_id |
texte | Identifiant de l'appel. |
meta.dry_run |
booléen |
Présent et à true pour un essai à blanc : rien n'a été enregistré. |
meta.created_listings |
liste | Fournisseur, collection, catégories et valeurs de liste créés au passage parce que leur nom était inconnu. Liste vide si tout existait déjà. |
meta.created_listings[].type |
texte | Nature de ce qui a été créé. |
meta.created_listings[].id |
entier | Son identifiant. |
meta.created_listings[].name |
texte | Son nom. |
{
"data": {
"id": 312,
"designation": "Tee-shirt col rond",
"description": "Coton bio, coupe droite.",
"notes": "",
"ref_four": "TS-8744",
"ref_interne": "",
"image_url": "",
"gestion_stock": true,
"variantes": true,
"favorite": false,
"archived": false,
"pa_ht": 12.5,
"pv_ttc": 29.9,
"eco_ttc": 0,
"fournisseur": {
"id": 4,
"name": "Atelier Textile"
},
"collec": {
"id": 2,
"name": "Été 2026"
},
"categories": [
{
"niveau": 1,
"id": 7,
"name": "Vêtements"
},
{
"niveau": 2,
"id": 12,
"name": "Hauts"
}
],
"libre_1": "",
"libre_2": "",
"libre_3": "",
"id_custom_list_1": 0,
"id_custom_list_2": 0,
"id_custom_list_3": 0,
"custom_io_1": false,
"custom_io_2": false,
"custom_io_3": false,
"custom_date_1": "",
"custom_date_2": "",
"custom_date_3": "",
"magasins": [
{
"id_shop": 1,
"impact_pv": 0,
"tva_taux": 20
},
{
"id_shop": 2,
"impact_pv": 2,
"tva_taux": 20
}
],
"variantes_product": [
{
"id": 1048,
"is_product": false,
"name": "M",
"position": 1,
"bc_ext": "",
"ean_int": "2161018416004",
"sku": "TS-M",
"impact_pa": 0,
"pa_ht": 12.5,
"impact_pv": 0,
"prix": [
{
"id_shop": 1,
"pv_ttc": 29.9
},
{
"id_shop": 2,
"pv_ttc": 31.9
}
],
"actif": true,
"date_creation": "2026-03-14T10:22:00+01:00",
"date_update": "2026-03-14T10:22:00+01:00"
},
{
"id": 1049,
"is_product": false,
"name": "XL",
"position": 2,
"bc_ext": "",
"ean_int": "2184253688944",
"sku": "TS-XL",
"impact_pa": 0,
"pa_ht": 12.5,
"impact_pv": 3,
"prix": [
{
"id_shop": 1,
"pv_ttc": 32.9
},
{
"id_shop": 2,
"pv_ttc": 34.9
}
],
"actif": true,
"date_creation": "2026-03-14T10:22:00+01:00",
"date_update": "2026-03-14T10:22:00+01:00"
}
],
"variantes_inactives": [],
"champs_personnalises": [
{
"cle": "libre_1",
"libelle": "Customisé 1",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "libre_2",
"libelle": "Customisé 2",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "libre_3",
"libelle": "Customisé 3",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "id_custom_list_1",
"libelle": "Customisé 1",
"type": "liste",
"affiche": false,
"valeur": ""
},
{
"cle": "id_custom_list_2",
"libelle": "Customisé 2",
"type": "liste",
"affiche": false,
"valeur": ""
},
{
"cle": "id_custom_list_3",
"libelle": "Customisé 3",
"type": "liste",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_io_1",
"libelle": "Customisé 1",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_io_2",
"libelle": "Customisé 2",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_io_3",
"libelle": "Customisé 3",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_date_1",
"libelle": "Customisé 1",
"type": "date",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_date_2",
"libelle": "Customisé 2",
"type": "date",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_date_3",
"libelle": "Customisé 3",
"type": "date",
"affiche": false,
"valeur": ""
}
],
"date_creation": "2026-03-14T10:22:00+01:00",
"date_update": "2026-03-14T10:22:00+01:00"
},
"meta": {
"request_id": "3f9a1c0b7d2e4a61",
"created_listings": [
{
"type": "categorie",
"id": 12,
"name": "Hauts"
}
]
}
}
Erreurs possibles
-
401
Clé absente, inconnue ou révoquée. Codes :
missing_key,invalid_key. -
403
Appel refusé pour ce compte ou cette clé. Codes :
api_not_activated,account_not_eligible,access_blocked,missing_scope. -
409
Une variante en service d'un autre produit porte déjà ce code-barres externe, ou le même code est donné à deux variantes de l'envoi. Code :
duplicate_barcode. Le message etdetailsdonnent les identifiants des produits concernés. Rien n'a été enregistré. -
422
Données envoyées invalides. Code :
validation_failed. Le champdetailsliste chaque erreur. -
429
Quota dépassé. Codes :
rate_limited,daily_quota_exceeded,too_many_failed_attempts. L'en-têteRetry-Afterindique combien de secondes attendre. -
503
Une autre écriture est en cours sur ce compte. Code :
account_busy. Renvoyer la même requête après le délai de l'en-têteRetry-After.
Une question ? contact@wanapos.com
