Produits

Créer un produit

POST /v1/products
vpn_key Permission write_products Compte comme une écriture

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 et details donnent les identifiants des produits concernés. Rien n'a été enregistré.
  • 422 Données envoyées invalides. Code : validation_failed. Le champ details liste chaque erreur.
  • 429 Quota dépassé. Codes : rate_limited, daily_quota_exceeded, too_many_failed_attempts. L'en-tête Retry-After indique 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ête Retry-After.

Voir toutes les erreurs

Une question ? contact@wanapos.com