# API Wanapos (version v1)

Adresse de base : `https://api.wanapos.com`

API réservée aux clients Wanapos, pour lire et gérer les données de leur compte depuis leurs propres outils ou depuis une IA.

## Authentification
Chaque appel porte une clé d'API dans l'en-tête `Authorization: Bearer VOTRE_CLE`. Une clé se crée dans les paramètres du compte Wanapos, par le titulaire du compte. Elle commence par `wps_` et n'est affichée qu'une seule fois. Ne placez jamais une clé dans une URL : l'appel est refusé.

## Permissions
Chaque clé porte une liste de permissions (par exemple `read_customers`). Seules les permissions listées dans cette documentation existent : chacune correspond à au moins une adresse disponible. Une donnée sans permission listée (le stock, par exemple) n'est pas encore accessible par l'API. Les ventes ne se lisent pour l'instant qu'à travers les achats d'un client. Un appel qui exige une permission absente de la clé renvoie l'erreur `missing_scope`, qui nomme la permission manquante. `GET /v1/me` liste les permissions de la clé utilisée.

## Quotas
Les quotas sont comptés par compte : 60 appels par minute, 5 000 lectures et 1 000 écritures par jour (remise à zéro à minuit, heure de Paris). Chaque réponse porte les en-têtes `RateLimit-Limit`, `RateLimit-Remaining` et `RateLimit-Reset` (secondes avant remise à zéro). Un dépassement renvoie le statut 429 avec l'en-tête `Retry-After` : attendez ce nombre de secondes avant de reprendre.

## Format des réponses
Les réponses sont en JSON, encodé en UTF-8, de même que le corps des appels qui en envoient un (avec l'en-tête `Content-Type: application/json`). Deux exceptions, qui décrivent l'API elle-même : `GET /v1/documentation.md` renvoie du texte (Markdown), et `GET /v1/openapi.json` renvoie du JSON sans l'enveloppe `data`.

Un succès renvoie `{"data": …, "meta": {"request_id": "…"}}` : `data` porte le résultat (un objet ou une liste), `meta` les informations sur la réponse.

Une erreur renvoie toujours la forme suivante, avec ces six champs :

```json
{
  "error": {
    "code": "missing_scope",
    "message": "Cette clé n'a pas la permission « export_customers » (« Exporter tout le fichier clients »).",
    "hint": "Le titulaire du compte peut ajouter cette permission à la clé dans les paramètres de son compte Wanapos, ou créer une nouvelle clé qui la porte. Les permissions de la clé actuelle sont listées par GET /v1/me.",
    "field": "export_customers",
    "details": [],
    "request_id": "3f9a1c0b7d2e4a61"
  }
}
```

`code` est un texte stable, à tester dans un programme. `message` dit ce qui ne va pas et `hint` comment corriger, tous deux en français. `field` nomme le paramètre, le champ ou la permission en cause (chaîne vide sinon). `details` est une liste, vide le plus souvent : quand plusieurs champs d'un envoi sont refusés, elle porte un objet par champ, de la forme `{"field": "…", "message": "…"}`.

Aucune valeur n'est jamais `null` : une information absente vaut une chaîne vide, 0, false ou une liste vide. Les dates sont au format ISO 8601. Les champs des données métier (clients, produits…) portent les noms utilisés dans Wanapos, en français, identiques à ceux des événements sortants : un objet reçu par un événement et le même objet lu par l'API ont la même forme.

## Écritures
Seules les adresses dont la documentation dit qu'elles comptent comme une écriture modifient des données (aujourd'hui : la création et la modification de client, l'ajustement des points de fidélité, la création de produit). Toutes les autres lisent, sans rien modifier. Une écriture est enregistrée en entier ou pas du tout : en cas d'erreur, rien n'est modifié. Les appels qui modifient des données acceptent deux protections. Le paramètre `?dry_run=true` valide tout sans rien enregistrer. L'en-tête `Idempotency-Key` (un identifiant unique de votre choix) garantit qu'une requête renvoyée après une coupure n'est pas exécutée deux fois.

## Permissions existantes

| Permission | Ce qu'elle autorise |
|---|---|
| `read_users` | Lire les utilisateurs du compte (nom et profil) |
| `read_customers` | Lire un client (par identifiant ou adresse mail) |
| `export_customers` | Exporter tout le fichier clients |
| `write_customers` | Créer et modifier des clients |
| `write_loyalty` | Ajuster les points de fidélité |
| `read_sales` | Lire les ventes |
| `read_products` | Lire les produits, fournisseurs, collections et catégories |
| `write_products` | Créer des produits ; créer et modifier fournisseurs, collections et catégories |

## Adresses disponibles

### GET /v1/me

**Compte, magasins, permissions et quotas de la clé utilisée**

Premier appel à faire. Indique à quel compte la clé est rattachée, la liste de ses magasins (leurs identifiants servent dans les autres appels), les permissions de la clé, l'état des quotas et les plafonds à respecter.

Aucune permission particulière n'est requise : toute clé valide peut appeler cette adresse. L'appel compte dans le quota de lecture.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Informations du compte et de la clé.

| Champ | Type | Description |
|---|---|---|
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |
| `data` | objet |  |
| `data.account` | objet | Le compte Wanapos auquel la clé est rattachée. |
| `data.account.id` | entier | Identifiant du compte. |
| `data.account.name` | texte | Nom du compte, tel que le commerçant l'a saisi. |
| `data.account.currency` | texte | Devise du compte, code ISO 4217 (exemple : EUR). |
| `data.account.timezone` | texte | Fuseau horaire utilisé pour les dates et pour la remise à zéro des quotas. |
| `data.shops` | liste | Magasins du compte, hors magasins archivés. |
| `data.shops[].id` | entier | Identifiant du magasin, à utiliser dans les autres appels. |
| `data.shops[].name` | texte | Nom du magasin. |
| `data.shops[].active` | booléen | Le magasin est actif. |
| `data.api_key` | objet | La clé utilisée pour cet appel. |
| `data.api_key.name` | texte | Nom donné à la clé par le titulaire du compte. |
| `data.api_key.hint` | texte | Début et fin de la clé, pour la reconnaître. Ne permet pas de la reconstituer. |
| `data.api_key.scopes` | liste de texte | Permissions portées par la clé. |
| `data.api_key.created_at` | texte | Date de création de la clé (ISO 8601). |
| `data.quotas` | objet | État des quotas du compte, cet appel compris. |
| `data.quotas.per_minute` | objet | État d'un quota. |
| `data.quotas.per_minute.limit` | entier | Nombre d'appels autorisés sur la période. |
| `data.quotas.per_minute.remaining` | entier | Nombre d'appels encore disponibles sur la période en cours. |
| `data.quotas.per_minute.reset_at` | texte | Date et heure de remise à zéro du compteur (ISO 8601). |
| `data.quotas.reads_per_day` | objet | État d'un quota. |
| `data.quotas.reads_per_day.limit` | entier | Nombre d'appels autorisés sur la période. |
| `data.quotas.reads_per_day.remaining` | entier | Nombre d'appels encore disponibles sur la période en cours. |
| `data.quotas.reads_per_day.reset_at` | texte | Date et heure de remise à zéro du compteur (ISO 8601). |
| `data.quotas.writes_per_day` | objet | État d'un quota. |
| `data.quotas.writes_per_day.limit` | entier | Nombre d'appels autorisés sur la période. |
| `data.quotas.writes_per_day.remaining` | entier | Nombre d'appels encore disponibles sur la période en cours. |
| `data.quotas.writes_per_day.reset_at` | texte | Date et heure de remise à zéro du compteur (ISO 8601). |
| `data.limits` | objet | Plafonds à respecter dans les appels. |
| `data.limits.max_page_size` | entier | Nombre maximal de résultats par page (paramètre `limit`). |
| `data.limits.default_page_size` | entier | Nombre de résultats par page si `limit` n'est pas précisé. |
| `data.limits.max_items_per_write` | entier | Nombre maximal d'éléments dans un appel de création. |
| `data.limits.max_body_bytes` | entier | Taille maximale du contenu envoyé, en octets. |
| `data.api` | objet |  |
| `data.api.version` | texte | Version de l'API. |
| `data.api.documentation_url` | texte | Adresse de la documentation. |

Exemple de réponse :

```json
{
    "data": {
        "account": {
            "id": 1451,
            "name": "Ma boutique",
            "currency": "EUR",
            "timezone": "Europe/Paris"
        },
        "shops": [
            {
                "id": 1,
                "name": "Magasin principal",
                "active": true
            }
        ],
        "api_key": {
            "name": "Mon assistant IA",
            "hint": "wps_Ab3d…x9Kq",
            "scopes": [
                "read_customers"
            ],
            "created_at": "2026-11-10T14:30:00+01:00"
        },
        "quotas": {
            "per_minute": {
                "limit": 60,
                "remaining": 59,
                "reset_at": "2026-11-10T14:31:00+01:00"
            },
            "reads_per_day": {
                "limit": 5000,
                "remaining": 4999,
                "reset_at": "2026-11-11T00:00:00+01:00"
            },
            "writes_per_day": {
                "limit": 1000,
                "remaining": 1000,
                "reset_at": "2026-11-11T00:00:00+01:00"
            }
        },
        "limits": {
            "max_page_size": 100,
            "default_page_size": 50,
            "max_items_per_write": 50,
            "max_body_bytes": 1048576
        },
        "api": {
            "version": "v1",
            "documentation_url": "https://wanapos.com/api"
        }
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/me" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 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.

### GET /v1/customers

**Rechercher des clients par adresse mail**

Renvoie les clients du compte qui portent exactement cette adresse mail, sans tenir compte des majuscules ni des espaces autour.

La réponse est toujours une liste : dans Wanapos, une adresse mail n'est pas unique, plusieurs fiches clients peuvent la porter. Une liste vide signifie qu'aucun client ne correspond, ce n'est pas une erreur. Si plusieurs clients reviennent, ne choisissez pas au hasard : départagez-les avec leurs autres champs, ou demandez à l'utilisateur.

La liste est limitée à 50 clients. Si `meta.truncated` vaut `true`, plus de 50 fiches portent cette adresse mail (cas très rare) et la liste est incomplète : il n'existe pas de page suivante pour cette recherche. Pour obtenir toutes les fiches, parcourez le fichier avec `GET /v1/customers/export` et gardez celles dont le champ `email` correspond.

Les clients supprimés dans l'application ne sont jamais renvoyés. Le paramètre `email` est obligatoire. Pour parcourir tout le fichier clients, utilisez `GET /v1/customers/export`.

- Clé d'API : requise. Permission : `read_customers` (Lire un client (par identifiant ou adresse mail)).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `email` | URL (?nom=valeur) | oui | Adresse mail complète à rechercher (50 caractères au maximum). Pensez à l'encoder dans l'URL. |

Réponse en cas de succès (statut 200) : Liste des clients portant cette adresse mail.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Clients correspondants, du plus ancien au plus récent. Liste vide si aucun. |
| `data[].id` | entier | Identifiant du client. |
| `data[].civilite` | texte | Civilité en clair (exemple : `Mme`). Chaîne vide si non renseignée. |
| `data[].nom` | texte | Nom. |
| `data[].prenom` | texte | Prénom. |
| `data[].nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. |
| `data[].email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. |
| `data[].tel` | texte | Téléphone fixe. |
| `data[].mobile` | texte | Téléphone mobile. |
| `data[].bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). |
| `data[].remise_pc` | entier | Remise permanente accordée au client, en pourcentage. |
| `data[].notes` | texte | Notes libres saisies par le commerçant. |
| `data[].libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. |
| `data[].libre_2` | texte | Champ personnalisé texte n° 2. |
| `data[].libre_3` | texte | Champ personnalisé texte n° 3. |
| `data[].custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data[].custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data[].custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data[].custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. |
| `data[].custom_date_2` | texte | Champ personnalisé date n° 2. |
| `data[].custom_date_3` | texte | Champ personnalisé date n° 3. |
| `data[].news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. |
| `data[].news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. |
| `data[].fidelite_active` | booléen | Le client participe au programme de fidélité. |
| `data[].actif` | booléen | Toujours `true` : un client supprimé n'est jamais renvoyé par l'API. |
| `data[].id_shop_origin` | entier | Identifiant du magasin dans lequel le client a été créé (voir `shops` dans `GET /v1/me`). 0 si aucun. |
| `data[].date_creation` | texte | Date de création de la fiche (ISO 8601). |
| `data[].date_update` | texte | Date de dernière modification de la fiche (ISO 8601). |
| `data[].adresse` | objet | Adresse postale du client. |
| `data[].adresse.ligne1` | texte | Adresse. |
| `data[].adresse.ligne2` | texte | Complément d'adresse. |
| `data[].adresse.cp` | texte | Code postal. |
| `data[].adresse.ville` | texte | Ville. |
| `data[].adresse.id_pays` | entier | Identifiant interne du pays. 0 si non renseigné. |
| `data[].adresse.pays_code` | texte | Code du pays sur deux lettres, ISO 3166-1 (exemple : `FR`). Chaîne vide si non renseigné. |
| `data[].adresse.pays` | texte | Nom du pays. |
| `data[].adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data[].adresse.archived` | booléen | L'adresse est archivée. |
| `data[].fidelite` | objet | Fidélité et cumuls d'achats du client. Des zéros si le client n'a encore rien acheté. |
| `data[].fidelite.points_actuels` | entier | Points disponibles aujourd'hui. |
| `data[].fidelite.points_cumules` | entier | Total des points gagnés depuis l'origine. |
| `data[].fidelite.nb_fois_pts_utilises` | entier | Nombre de fois où des points ont été utilisés. |
| `data[].fidelite.last_pts_acquis` | entier | Points gagnés lors du dernier achat. |
| `data[].fidelite.total_ca` | nombre | Montant total des achats du client, dans la devise du compte. |
| `data[].fidelite.total_qt` | entier | Nombre total d'articles achetés. |
| `data[].fidelite.total_pa` | entier | Nombre total de passages en caisse. |
| `data[].champs_personnalises` | liste | Les neuf champs personnalisés du client, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. |
| `data[].champs_personnalises[].cle` | texte | Nom du champ dans l'objet client (exemple : `libre_1`). |
| `data[].champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data[].champs_personnalises[].type` | texte | Nature du champ. |
| `data[].champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data[].champs_personnalises[].valeur` |  | Valeur du champ : texte, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre de clients renvoyés. |
| `meta.truncated` | booléen | `true` si la liste a été coupée à 50 clients : elle est alors incomplète, voir la description de l'adresse. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 1842,
            "civilite": "Mme",
            "nom": "Martin",
            "prenom": "Claire",
            "nom_2": "",
            "email": "claire.martin@exemple.com",
            "tel": "",
            "mobile": "0600000000",
            "bc_ext": "",
            "remise_pc": 0,
            "notes": "",
            "libre_1": "",
            "libre_2": "",
            "libre_3": "",
            "custom_io_1": false,
            "custom_io_2": false,
            "custom_io_3": false,
            "custom_date_1": "",
            "custom_date_2": "",
            "custom_date_3": "",
            "news_sms": false,
            "news_email": true,
            "fidelite_active": true,
            "actif": true,
            "id_shop_origin": 1,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00",
            "adresse": {
                "ligne1": "12 rue des Lilas",
                "ligne2": "",
                "cp": "69003",
                "ville": "Lyon",
                "id_pays": 63,
                "pays_code": "FR",
                "pays": "France",
                "tva_intra": "",
                "archived": false
            },
            "fidelite": {
                "points_actuels": 120,
                "points_cumules": 340,
                "nb_fois_pts_utilises": 2,
                "last_pts_acquis": 15,
                "total_ca": 412.5,
                "total_qt": 17,
                "total_pa": 9
            },
            "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": "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": ""
                }
            ]
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "truncated": false
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customers?email=claire.martin%40exemple.com" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/customers

**Créer un client**

Crée un client et renvoie sa fiche complète. L'identifiant du nouveau client est dans `data.id` : conservez-le, c'est lui qui permet de relire ou de modifier ce client ensuite. Aucun champ n'est obligatoire à lui seul, mais il faut renseigner au moins un de ces champs : `nom`, `prenom`, `nom_2`, `email`, `mobile`, `tel`. Les champs absents prennent leur valeur par défaut.

Si un client actif porte déjà l'adresse mail envoyée, la création est refusée avec l'erreur `duplicate_email`, qui donne les identifiants des clients existants. Ne contournez pas ce refus par réflexe : dans la plupart des cas, il faut modifier le client existant avec `PATCH /v1/customers/{id}`. Si ce sont bien deux personnes différentes qui partagent une adresse mail, renvoyez la requête avec `?allow_duplicate_email=true`. Il n'existe pas d'appel « créer ou mettre à jour » : une adresse mail n'étant pas unique dans Wanapos, l'API ne choisit jamais à votre place quelle fiche modifier.

Les accords de communication `news_sms` et `news_email` valent `false` s'ils ne sont pas envoyés : n'envoyez `true` que si la personne a réellement donné son accord pour recevoir des SMS ou des mails. `fidelite_active` vaut `true` s'il n'est pas envoyé. La fidélité (points, cumuls), les dates et l'identifiant ne s'écrivent pas par cette adresse : les points s'ajustent par `POST /v1/customers/{id}/loyalty-points`.

Pour ne jamais créer deux fois le même client après une coupure réseau, envoyez un en-tête `Idempotency-Key`. Pour vérifier une requête sans rien enregistrer, ajoutez `?dry_run=true`.

- Clé d'API : requise. Permission : `write_customers` (Créer et modifier des clients).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `dry_run` | URL (?nom=valeur) | non | `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_email` | URL (?nom=valeur) | non | `true` pour enregistrer même si un autre client actif porte déjà cette adresse mail. À n'utiliser qu'après avoir vérifié qu'il s'agit bien de deux personnes différentes. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `civilite` | texte | Civilité, parmi les valeurs exactes : chaîne vide, `M.`, `Mme`, `Mlle`, `Sct`. À la création, si elle est absente : la civilité par défaut réglée par le commerçant. |
| `nom` | texte | Nom. 40 caractères au maximum. |
| `prenom` | texte | Prénom. 40 caractères au maximum. |
| `nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. 40 caractères au maximum. |
| `email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. 50 caractères au maximum. |
| `tel` | texte | Téléphone fixe. 17 caractères au maximum. |
| `mobile` | texte | Téléphone mobile. 17 caractères au maximum. |
| `bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). 32 caractères au maximum. |
| `remise_pc` | entier | Remise permanente accordée au client, en pourcentage. Entier de 0 à 100. |
| `notes` | texte | Notes libres saisies par le commerçant. 5 000 caractères au maximum. |
| `libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. 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_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `custom_date_2` | texte | Champ personnalisé date n° 2. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `custom_date_3` | texte | Champ personnalisé date n° 3. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. `false` à la création si absent : n'envoyez `true` que si la personne a donné son accord. |
| `news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. `false` à la création si absent : n'envoyez `true` que si la personne a donné son accord. |
| `fidelite_active` | booléen | Le client participe au programme de fidélité. `true` à la création si absent. |
| `id_shop_origin` | entier | Identifiant du magasin d'origine du client, parmi ceux listés par `GET /v1/me`. À la création, si absent : le premier magasin du compte. |
| `adresse` | objet | Adresse postale. Seuls les champs envoyés sont enregistrés ou modifiés. |
| `adresse.ligne1` | texte | Adresse. 50 caractères au maximum. |
| `adresse.ligne2` | texte | Complément d'adresse. 50 caractères au maximum. |
| `adresse.cp` | texte | Code postal. 9 caractères au maximum. |
| `adresse.ville` | texte | Ville. 30 caractères au maximum. |
| `adresse.pays_code` | texte | Code du pays à deux lettres (`FR`, `BE`, `CH`…). À la création, si absent : le pays du magasin d'origine. |
| `adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. 32 caractères au maximum. |

Réponse en cas de succès (statut 201) : Le client créé, avec sa fiche complète.

| Champ | Type | Description |
|---|---|---|
| `data` | objet | Un client du compte. Les noms de champs sont ceux des événements sortants `client_create` et `client_update`. |
| `data.id` | entier | Identifiant du client. |
| `data.civilite` | texte | Civilité en clair (exemple : `Mme`). Chaîne vide si non renseignée. |
| `data.nom` | texte | Nom. |
| `data.prenom` | texte | Prénom. |
| `data.nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. |
| `data.email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. |
| `data.tel` | texte | Téléphone fixe. |
| `data.mobile` | texte | Téléphone mobile. |
| `data.bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). |
| `data.remise_pc` | entier | Remise permanente accordée au client, en pourcentage. |
| `data.notes` | texte | Notes libres saisies par le commerçant. |
| `data.libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. |
| `data.libre_2` | texte | Champ personnalisé texte n° 2. |
| `data.libre_3` | texte | Champ personnalisé texte n° 3. |
| `data.custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data.custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data.custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data.custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. |
| `data.custom_date_2` | texte | Champ personnalisé date n° 2. |
| `data.custom_date_3` | texte | Champ personnalisé date n° 3. |
| `data.news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. |
| `data.news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. |
| `data.fidelite_active` | booléen | Le client participe au programme de fidélité. |
| `data.actif` | booléen | Toujours `true` : un client supprimé n'est jamais renvoyé par l'API. |
| `data.id_shop_origin` | entier | Identifiant du magasin dans lequel le client a été créé (voir `shops` dans `GET /v1/me`). 0 si aucun. |
| `data.date_creation` | texte | Date de création de la fiche (ISO 8601). |
| `data.date_update` | texte | Date de dernière modification de la fiche (ISO 8601). |
| `data.adresse` | objet | Adresse postale du client. |
| `data.adresse.ligne1` | texte | Adresse. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant interne du pays. 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays sur deux lettres, ISO 3166-1 (exemple : `FR`). Chaîne vide si non renseigné. |
| `data.adresse.pays` | texte | Nom du pays. |
| `data.adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.adresse.archived` | booléen | L'adresse est archivée. |
| `data.fidelite` | objet | Fidélité et cumuls d'achats du client. Des zéros si le client n'a encore rien acheté. |
| `data.fidelite.points_actuels` | entier | Points disponibles aujourd'hui. |
| `data.fidelite.points_cumules` | entier | Total des points gagnés depuis l'origine. |
| `data.fidelite.nb_fois_pts_utilises` | entier | Nombre de fois où des points ont été utilisés. |
| `data.fidelite.last_pts_acquis` | entier | Points gagnés lors du dernier achat. |
| `data.fidelite.total_ca` | nombre | Montant total des achats du client, dans la devise du compte. |
| `data.fidelite.total_qt` | entier | Nombre total d'articles achetés. |
| `data.fidelite.total_pa` | entier | Nombre total de passages en caisse. |
| `data.champs_personnalises` | liste | Les neuf champs personnalisés du client, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. |
| `data.champs_personnalises[].cle` | texte | Nom du champ dans l'objet client (exemple : `libre_1`). |
| `data.champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data.champs_personnalises[].type` | texte | Nature du champ. |
| `data.champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data.champs_personnalises[].valeur` |  | Valeur du champ : texte, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 1842,
        "civilite": "Mme",
        "nom": "Martin",
        "prenom": "Claire",
        "nom_2": "",
        "email": "claire.martin@exemple.com",
        "tel": "",
        "mobile": "0600000000",
        "bc_ext": "",
        "remise_pc": 0,
        "notes": "",
        "libre_1": "",
        "libre_2": "",
        "libre_3": "",
        "custom_io_1": false,
        "custom_io_2": false,
        "custom_io_3": false,
        "custom_date_1": "",
        "custom_date_2": "",
        "custom_date_3": "",
        "news_sms": false,
        "news_email": true,
        "fidelite_active": true,
        "actif": true,
        "id_shop_origin": 1,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "12 rue des Lilas",
            "ligne2": "",
            "cp": "69003",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France",
            "tva_intra": "",
            "archived": false
        },
        "fidelite": {
            "points_actuels": 120,
            "points_cumules": 340,
            "nb_fois_pts_utilises": 2,
            "last_pts_acquis": 15,
            "total_ca": 412.5,
            "total_qt": 17,
            "total_pa": 9
        },
        "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": "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": ""
            }
        ]
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/customers" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"email":"claire.martin@exemple.com","nom":"Martin","prenom":"Claire","civilite":"Mme","mobile":"0600000000","news_email":true,"adresse":{"ligne1":"12 rue des Lilas","cp":"69003","ville":"Lyon","pays_code":"FR"}}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 409 : Un client actif porte déjà cette adresse mail. Code : `duplicate_email`. Le message et `details` donnent les identifiants des clients existants. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/customers/{id}

**Lire un client par son identifiant**

Renvoie la fiche complète d'un client : identité, coordonnées, adresse, consentements, fidélité et champs personnalisés.

Un client supprimé dans l'application est introuvable : l'appel répond 404, comme si le client n'avait jamais existé.

- Clé d'API : requise. Permission : `read_customers` (Lire un client (par identifiant ou adresse mail)).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du client (champ `id`). |

Réponse en cas de succès (statut 200) : La fiche du client.

| Champ | Type | Description |
|---|---|---|
| `data` | objet | Un client du compte. Les noms de champs sont ceux des événements sortants `client_create` et `client_update`. |
| `data.id` | entier | Identifiant du client. |
| `data.civilite` | texte | Civilité en clair (exemple : `Mme`). Chaîne vide si non renseignée. |
| `data.nom` | texte | Nom. |
| `data.prenom` | texte | Prénom. |
| `data.nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. |
| `data.email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. |
| `data.tel` | texte | Téléphone fixe. |
| `data.mobile` | texte | Téléphone mobile. |
| `data.bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). |
| `data.remise_pc` | entier | Remise permanente accordée au client, en pourcentage. |
| `data.notes` | texte | Notes libres saisies par le commerçant. |
| `data.libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. |
| `data.libre_2` | texte | Champ personnalisé texte n° 2. |
| `data.libre_3` | texte | Champ personnalisé texte n° 3. |
| `data.custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data.custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data.custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data.custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. |
| `data.custom_date_2` | texte | Champ personnalisé date n° 2. |
| `data.custom_date_3` | texte | Champ personnalisé date n° 3. |
| `data.news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. |
| `data.news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. |
| `data.fidelite_active` | booléen | Le client participe au programme de fidélité. |
| `data.actif` | booléen | Toujours `true` : un client supprimé n'est jamais renvoyé par l'API. |
| `data.id_shop_origin` | entier | Identifiant du magasin dans lequel le client a été créé (voir `shops` dans `GET /v1/me`). 0 si aucun. |
| `data.date_creation` | texte | Date de création de la fiche (ISO 8601). |
| `data.date_update` | texte | Date de dernière modification de la fiche (ISO 8601). |
| `data.adresse` | objet | Adresse postale du client. |
| `data.adresse.ligne1` | texte | Adresse. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant interne du pays. 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays sur deux lettres, ISO 3166-1 (exemple : `FR`). Chaîne vide si non renseigné. |
| `data.adresse.pays` | texte | Nom du pays. |
| `data.adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.adresse.archived` | booléen | L'adresse est archivée. |
| `data.fidelite` | objet | Fidélité et cumuls d'achats du client. Des zéros si le client n'a encore rien acheté. |
| `data.fidelite.points_actuels` | entier | Points disponibles aujourd'hui. |
| `data.fidelite.points_cumules` | entier | Total des points gagnés depuis l'origine. |
| `data.fidelite.nb_fois_pts_utilises` | entier | Nombre de fois où des points ont été utilisés. |
| `data.fidelite.last_pts_acquis` | entier | Points gagnés lors du dernier achat. |
| `data.fidelite.total_ca` | nombre | Montant total des achats du client, dans la devise du compte. |
| `data.fidelite.total_qt` | entier | Nombre total d'articles achetés. |
| `data.fidelite.total_pa` | entier | Nombre total de passages en caisse. |
| `data.champs_personnalises` | liste | Les neuf champs personnalisés du client, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. |
| `data.champs_personnalises[].cle` | texte | Nom du champ dans l'objet client (exemple : `libre_1`). |
| `data.champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data.champs_personnalises[].type` | texte | Nature du champ. |
| `data.champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data.champs_personnalises[].valeur` |  | Valeur du champ : texte, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 1842,
        "civilite": "Mme",
        "nom": "Martin",
        "prenom": "Claire",
        "nom_2": "",
        "email": "claire.martin@exemple.com",
        "tel": "",
        "mobile": "0600000000",
        "bc_ext": "",
        "remise_pc": 0,
        "notes": "",
        "libre_1": "",
        "libre_2": "",
        "libre_3": "",
        "custom_io_1": false,
        "custom_io_2": false,
        "custom_io_3": false,
        "custom_date_1": "",
        "custom_date_2": "",
        "custom_date_3": "",
        "news_sms": false,
        "news_email": true,
        "fidelite_active": true,
        "actif": true,
        "id_shop_origin": 1,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "12 rue des Lilas",
            "ligne2": "",
            "cp": "69003",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France",
            "tva_intra": "",
            "archived": false
        },
        "fidelite": {
            "points_actuels": 120,
            "points_cumules": 340,
            "nb_fois_pts_utilises": 2,
            "last_pts_acquis": 15,
            "total_ca": 412.5,
            "total_qt": 17,
            "total_pa": 9
        },
        "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": "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": ""
            }
        ]
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customers/1842" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### PATCH /v1/customers/{id}

**Modifier un client**

Modifie un client et renvoie sa fiche complète après modification.

La modification est partielle : seuls les champs envoyés changent, tous les autres sont conservés tels quels. N'envoyez donc que ce que vous voulez modifier, pas la fiche entière. Pour vider un champ texte, envoyez-le avec une chaîne vide. La même règle vaut à l'intérieur de `adresse` : envoyer seulement `adresse.ville` ne touche pas au code postal.

Il faut l'identifiant exact du client : pour le trouver à partir d'une adresse mail, utilisez d'abord `GET /v1/customers?email=…`. Un client supprimé dans l'application est introuvable (404), il ne peut pas être modifié ni réactivé.

Remplacer l'adresse mail par une adresse déjà portée par un autre client actif est refusé avec l'erreur `duplicate_email`, sauf avec `?allow_duplicate_email=true`. La fidélité (points, cumuls), les dates et l'identifiant ne s'écrivent pas par cette adresse : les points s'ajustent par `POST /v1/customers/{id}/loyalty-points`. Pour vérifier une requête sans rien enregistrer, ajoutez `?dry_run=true`.

- Clé d'API : requise. Permission : `write_customers` (Créer et modifier des clients).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du client (champ `id`). |
| `dry_run` | URL (?nom=valeur) | non | `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_email` | URL (?nom=valeur) | non | `true` pour enregistrer même si un autre client actif porte déjà cette adresse mail. À n'utiliser qu'après avoir vérifié qu'il s'agit bien de deux personnes différentes. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `civilite` | texte | Civilité, parmi les valeurs exactes : chaîne vide, `M.`, `Mme`, `Mlle`, `Sct`. À la création, si elle est absente : la civilité par défaut réglée par le commerçant. |
| `nom` | texte | Nom. 40 caractères au maximum. |
| `prenom` | texte | Prénom. 40 caractères au maximum. |
| `nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. 40 caractères au maximum. |
| `email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. 50 caractères au maximum. |
| `tel` | texte | Téléphone fixe. 17 caractères au maximum. |
| `mobile` | texte | Téléphone mobile. 17 caractères au maximum. |
| `bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). 32 caractères au maximum. |
| `remise_pc` | entier | Remise permanente accordée au client, en pourcentage. Entier de 0 à 100. |
| `notes` | texte | Notes libres saisies par le commerçant. 5 000 caractères au maximum. |
| `libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. 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_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `custom_date_2` | texte | Champ personnalisé date n° 2. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `custom_date_3` | texte | Champ personnalisé date n° 3. Format `AAAA-MM-JJ`. Chaîne vide pour effacer la date. |
| `news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. `false` à la création si absent : n'envoyez `true` que si la personne a donné son accord. |
| `news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. `false` à la création si absent : n'envoyez `true` que si la personne a donné son accord. |
| `fidelite_active` | booléen | Le client participe au programme de fidélité. `true` à la création si absent. |
| `id_shop_origin` | entier | Identifiant du magasin d'origine du client, parmi ceux listés par `GET /v1/me`. À la création, si absent : le premier magasin du compte. |
| `adresse` | objet | Adresse postale. Seuls les champs envoyés sont enregistrés ou modifiés. |
| `adresse.ligne1` | texte | Adresse. 50 caractères au maximum. |
| `adresse.ligne2` | texte | Complément d'adresse. 50 caractères au maximum. |
| `adresse.cp` | texte | Code postal. 9 caractères au maximum. |
| `adresse.ville` | texte | Ville. 30 caractères au maximum. |
| `adresse.pays_code` | texte | Code du pays à deux lettres (`FR`, `BE`, `CH`…). À la création, si absent : le pays du magasin d'origine. |
| `adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. 32 caractères au maximum. |

Réponse en cas de succès (statut 200) : Le client après modification, avec sa fiche complète.

| Champ | Type | Description |
|---|---|---|
| `data` | objet | Un client du compte. Les noms de champs sont ceux des événements sortants `client_create` et `client_update`. |
| `data.id` | entier | Identifiant du client. |
| `data.civilite` | texte | Civilité en clair (exemple : `Mme`). Chaîne vide si non renseignée. |
| `data.nom` | texte | Nom. |
| `data.prenom` | texte | Prénom. |
| `data.nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. |
| `data.email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. |
| `data.tel` | texte | Téléphone fixe. |
| `data.mobile` | texte | Téléphone mobile. |
| `data.bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). |
| `data.remise_pc` | entier | Remise permanente accordée au client, en pourcentage. |
| `data.notes` | texte | Notes libres saisies par le commerçant. |
| `data.libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. |
| `data.libre_2` | texte | Champ personnalisé texte n° 2. |
| `data.libre_3` | texte | Champ personnalisé texte n° 3. |
| `data.custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data.custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data.custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data.custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. |
| `data.custom_date_2` | texte | Champ personnalisé date n° 2. |
| `data.custom_date_3` | texte | Champ personnalisé date n° 3. |
| `data.news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. |
| `data.news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. |
| `data.fidelite_active` | booléen | Le client participe au programme de fidélité. |
| `data.actif` | booléen | Toujours `true` : un client supprimé n'est jamais renvoyé par l'API. |
| `data.id_shop_origin` | entier | Identifiant du magasin dans lequel le client a été créé (voir `shops` dans `GET /v1/me`). 0 si aucun. |
| `data.date_creation` | texte | Date de création de la fiche (ISO 8601). |
| `data.date_update` | texte | Date de dernière modification de la fiche (ISO 8601). |
| `data.adresse` | objet | Adresse postale du client. |
| `data.adresse.ligne1` | texte | Adresse. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant interne du pays. 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays sur deux lettres, ISO 3166-1 (exemple : `FR`). Chaîne vide si non renseigné. |
| `data.adresse.pays` | texte | Nom du pays. |
| `data.adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.adresse.archived` | booléen | L'adresse est archivée. |
| `data.fidelite` | objet | Fidélité et cumuls d'achats du client. Des zéros si le client n'a encore rien acheté. |
| `data.fidelite.points_actuels` | entier | Points disponibles aujourd'hui. |
| `data.fidelite.points_cumules` | entier | Total des points gagnés depuis l'origine. |
| `data.fidelite.nb_fois_pts_utilises` | entier | Nombre de fois où des points ont été utilisés. |
| `data.fidelite.last_pts_acquis` | entier | Points gagnés lors du dernier achat. |
| `data.fidelite.total_ca` | nombre | Montant total des achats du client, dans la devise du compte. |
| `data.fidelite.total_qt` | entier | Nombre total d'articles achetés. |
| `data.fidelite.total_pa` | entier | Nombre total de passages en caisse. |
| `data.champs_personnalises` | liste | Les neuf champs personnalisés du client, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. |
| `data.champs_personnalises[].cle` | texte | Nom du champ dans l'objet client (exemple : `libre_1`). |
| `data.champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data.champs_personnalises[].type` | texte | Nature du champ. |
| `data.champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data.champs_personnalises[].valeur` |  | Valeur du champ : texte, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 1842,
        "civilite": "Mme",
        "nom": "Martin",
        "prenom": "Claire",
        "nom_2": "",
        "email": "claire.martin@exemple.com",
        "tel": "",
        "mobile": "0600000000",
        "bc_ext": "",
        "remise_pc": 0,
        "notes": "",
        "libre_1": "",
        "libre_2": "",
        "libre_3": "",
        "custom_io_1": false,
        "custom_io_2": false,
        "custom_io_3": false,
        "custom_date_1": "",
        "custom_date_2": "",
        "custom_date_3": "",
        "news_sms": false,
        "news_email": true,
        "fidelite_active": true,
        "actif": true,
        "id_shop_origin": 1,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "12 rue des Lilas",
            "ligne2": "",
            "cp": "69003",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France",
            "tva_intra": "",
            "archived": false
        },
        "fidelite": {
            "points_actuels": 120,
            "points_cumules": 340,
            "nb_fois_pts_utilises": 2,
            "last_pts_acquis": 15,
            "total_ca": 412.5,
            "total_qt": 17,
            "total_pa": 9
        },
        "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": "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": ""
            }
        ]
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/customers/1842" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"mobile":"0611223344","news_sms":true,"adresse":{"ville":"Villeurbanne","cp":"69100"}}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : Un client actif porte déjà cette adresse mail. Code : `duplicate_email`. Le message et `details` donnent les identifiants des clients existants. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/customers/{id}/purchases

**Lire les achats d'un client**

Renvoie ce qu'un client a acheté : une ligne par article, de la plus récente à la plus ancienne. Cette adresse demande la permission `read_sales`, distincte de `read_customers` : lire les coordonnées d'un client ne donne pas accès à ses achats.

Chaque ligne est un article d'un ticket. Les articles d'un même passage en caisse portent le même `id_ticket` et le même `num_ticket` : regroupez-les par `id_ticket` pour reconstituer un ticket. Un retour apparaît comme une ligne avec une quantité `qt` et un montant `val` négatifs. Les ventes annulées n'apparaissent pas. Une carte cadeau apparaît sans détail (`type` vaut `carte_kdo`).

Les montants sont dans la devise du compte. `val` est le montant TTC réellement payé pour la ligne, remise déduite : c'est lui qu'il faut additionner pour obtenir un total.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez avec `after` égal à `meta.next_after`. Sans `since` ni `until`, tout l'historique du client est parcouru. Une liste vide signifie que le client n'a rien acheté sur la période, ce n'est pas une erreur. Un client supprimé ou inconnu renvoie 404.

Les ventes ne se modifient pas par l'API : elles sont en lecture seule.

- Clé d'API : requise. Permission : `read_sales` (Lire les ventes).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du client (champ `id`). |
| `limit` | URL (?nom=valeur) | non | Nombre de lignes par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `since` | URL (?nom=valeur) | non | Ne renvoie que les ventes à partir de cette date, incluse. Format `2026-01-01`. |
| `until` | URL (?nom=valeur) | non | Ne renvoie que les ventes jusqu'à cette date, incluse. Format `2026-12-31`. |

Réponse en cas de succès (statut 200) : Une page des achats du client.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Lignes d'articles achetés, de la plus récente à la plus ancienne. Liste vide si le client n'a rien acheté sur la période. |
| `data[].id` | entier | Identifiant de la ligne de vente. |
| `data[].date` | texte | Date de la vente, au format `AAAA-MM-JJ`. |
| `data[].date_creation` | texte | Date et heure d'enregistrement de la vente. |
| `data[].id_ticket` | entier | Identifiant du ticket auquel appartient la ligne. Toutes les lignes d'un même passage en caisse portent le même. |
| `data[].num_ticket` | entier | Numéro du ticket, tel qu'il est imprimé. 0 s'il est inconnu. |
| `data[].id_shop` | entier | Identifiant du magasin où la vente a eu lieu (voir `GET /v1/me`). |
| `data[].id_point_caisse` | entier | Identifiant du point de caisse. |
| `data[].type` | texte | Nature de la ligne : `product` pour un article, `carte_kdo` pour une carte cadeau. |
| `data[].id_product` | entier | Identifiant du produit. 0 pour une carte cadeau. |
| `data[].id_variante_product` | entier | Identifiant de la variante vendue. 0 pour une carte cadeau. |
| `data[].designation` | texte | Désignation de l'article au moment de la vente. « Carte cadeau » pour une carte cadeau, sans autre détail. |
| `data[].variante` | texte | Nom de la variante (taille, couleur…). Chaîne vide si le produit n'a pas de variante. |
| `data[].qt` | entier | Quantité. Négative pour un retour. |
| `data[].pv_initial` | nombre | Prix de vente unitaire TTC avant remise. |
| `data[].remise_pc` | nombre | Remise appliquée, en pourcentage. |
| `data[].remise_mt` | nombre | Montant de la remise, TTC. |
| `data[].val` | nombre | Montant TTC de la ligne, remise déduite. Négatif pour un retour. |
| `data[].val_ht` | nombre | Montant hors taxes de la ligne. |
| `data[].tva_mt` | nombre | Montant de TVA de la ligne. |
| `data[].id_promotion` | entier | Identifiant de la promotion appliquée. 0 si aucune. |
| `data[].promotion` | texte | Nom de la promotion appliquée. Chaîne vide si aucune, ou si la promotion n'existe plus. |
| `data[].remarque` | texte | Remarque saisie sur la ligne. Chaîne vide si aucune. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre de lignes dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 58214,
            "date": "2026-10-02",
            "date_creation": "2026-10-02T16:05:12+02:00",
            "id_ticket": 9041,
            "num_ticket": 3187,
            "id_shop": 1,
            "id_point_caisse": 1,
            "type": "product",
            "id_product": 412,
            "id_variante_product": 1630,
            "designation": "Pull col rond",
            "variante": "M / Bleu",
            "qt": 1,
            "pv_initial": 59.9,
            "remise_pc": 10,
            "remise_mt": 5.99,
            "val": 53.91,
            "val_ht": 44.93,
            "tva_mt": 8.98,
            "id_promotion": 0,
            "promotion": "",
            "remarque": ""
        },
        {
            "id": 58213,
            "date": "2026-10-02",
            "date_creation": "2026-10-02T16:05:12+02:00",
            "id_ticket": 9041,
            "num_ticket": 3187,
            "id_shop": 1,
            "id_point_caisse": 1,
            "type": "product",
            "id_product": 77,
            "id_variante_product": 205,
            "designation": "Écharpe laine",
            "variante": "",
            "qt": 1,
            "pv_initial": 24,
            "remise_pc": 0,
            "remise_mt": 0,
            "val": 24,
            "val_ht": 20,
            "tva_mt": 4,
            "id_promotion": 0,
            "promotion": "",
            "remarque": ""
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 2,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customers/1842/purchases" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/customers/export

**Parcourir tout le fichier clients**

Renvoie les clients du compte page par page, par identifiant croissant, avec la même fiche complète que la lecture d'un client. Cette adresse demande la permission `export_customers`, distincte de `read_customers` : une clé de simple lecture ne peut pas parcourir tout le fichier.

Le parcours se fait par curseur. Appelez d'abord sans `after`. Tant que `meta.has_more` vaut `true`, rappelez avec `after` égal à `meta.next_after`. Quand `has_more` vaut `false`, le parcours est terminé. Ne construisez pas le curseur vous-même et n'utilisez pas de numéro de page.

Pour tenir un autre outil à jour sans tout relire, passez `updated_since` : seules les fiches créées ou modifiées depuis cette date reviennent. Notez l'heure de début de votre parcours et réutilisez-la comme `updated_since` la fois suivante. Un changement de points de fidélité seul ne compte pas comme une modification de la fiche. Les clients supprimés dans l'application ne sont jamais renvoyés ici : `GET /v1/customers/deleted` donne leurs identifiants.

- Clé d'API : requise. Permission : `export_customers` (Exporter tout le fichier clients).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `updated_since` | URL (?nom=valeur) | non | Ne renvoie que les fiches créées ou modifiées depuis cette date. Formats acceptés : `2026-11-01` (minuit, heure de Paris) ou `2026-11-01T08:30:00+01:00`. Sans fuseau, l'heure est celle de Paris. Pensez à encoder le `+` dans l'URL (`%2B`). |

Réponse en cas de succès (statut 200) : Une page du fichier clients.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Clients de la page, par identifiant croissant. Liste vide si aucun. |
| `data[].id` | entier | Identifiant du client. |
| `data[].civilite` | texte | Civilité en clair (exemple : `Mme`). Chaîne vide si non renseignée. |
| `data[].nom` | texte | Nom. |
| `data[].prenom` | texte | Prénom. |
| `data[].nom_2` | texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. |
| `data[].email` | texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. |
| `data[].tel` | texte | Téléphone fixe. |
| `data[].mobile` | texte | Téléphone mobile. |
| `data[].bc_ext` | texte | Code-barres associé au client (carte de fidélité par exemple). |
| `data[].remise_pc` | entier | Remise permanente accordée au client, en pourcentage. |
| `data[].notes` | texte | Notes libres saisies par le commerçant. |
| `data[].libre_1` | texte | Champ personnalisé texte n° 1. Son libellé est dans `champs_personnalises`. |
| `data[].libre_2` | texte | Champ personnalisé texte n° 2. |
| `data[].libre_3` | texte | Champ personnalisé texte n° 3. |
| `data[].custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data[].custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data[].custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data[].custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. |
| `data[].custom_date_2` | texte | Champ personnalisé date n° 2. |
| `data[].custom_date_3` | texte | Champ personnalisé date n° 3. |
| `data[].news_sms` | booléen | Le client accepte de recevoir des SMS. À respecter avant tout envoi. |
| `data[].news_email` | booléen | Le client accepte de recevoir des mails. À respecter avant tout envoi. |
| `data[].fidelite_active` | booléen | Le client participe au programme de fidélité. |
| `data[].actif` | booléen | Toujours `true` : un client supprimé n'est jamais renvoyé par l'API. |
| `data[].id_shop_origin` | entier | Identifiant du magasin dans lequel le client a été créé (voir `shops` dans `GET /v1/me`). 0 si aucun. |
| `data[].date_creation` | texte | Date de création de la fiche (ISO 8601). |
| `data[].date_update` | texte | Date de dernière modification de la fiche (ISO 8601). |
| `data[].adresse` | objet | Adresse postale du client. |
| `data[].adresse.ligne1` | texte | Adresse. |
| `data[].adresse.ligne2` | texte | Complément d'adresse. |
| `data[].adresse.cp` | texte | Code postal. |
| `data[].adresse.ville` | texte | Ville. |
| `data[].adresse.id_pays` | entier | Identifiant interne du pays. 0 si non renseigné. |
| `data[].adresse.pays_code` | texte | Code du pays sur deux lettres, ISO 3166-1 (exemple : `FR`). Chaîne vide si non renseigné. |
| `data[].adresse.pays` | texte | Nom du pays. |
| `data[].adresse.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data[].adresse.archived` | booléen | L'adresse est archivée. |
| `data[].fidelite` | objet | Fidélité et cumuls d'achats du client. Des zéros si le client n'a encore rien acheté. |
| `data[].fidelite.points_actuels` | entier | Points disponibles aujourd'hui. |
| `data[].fidelite.points_cumules` | entier | Total des points gagnés depuis l'origine. |
| `data[].fidelite.nb_fois_pts_utilises` | entier | Nombre de fois où des points ont été utilisés. |
| `data[].fidelite.last_pts_acquis` | entier | Points gagnés lors du dernier achat. |
| `data[].fidelite.total_ca` | nombre | Montant total des achats du client, dans la devise du compte. |
| `data[].fidelite.total_qt` | entier | Nombre total d'articles achetés. |
| `data[].fidelite.total_pa` | entier | Nombre total de passages en caisse. |
| `data[].champs_personnalises` | liste | Les neuf champs personnalisés du client, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. |
| `data[].champs_personnalises[].cle` | texte | Nom du champ dans l'objet client (exemple : `libre_1`). |
| `data[].champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data[].champs_personnalises[].type` | texte | Nature du champ. |
| `data[].champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data[].champs_personnalises[].valeur` |  | Valeur du champ : texte, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 1842,
            "civilite": "Mme",
            "nom": "Martin",
            "prenom": "Claire",
            "nom_2": "",
            "email": "claire.martin@exemple.com",
            "tel": "",
            "mobile": "0600000000",
            "bc_ext": "",
            "remise_pc": 0,
            "notes": "",
            "libre_1": "",
            "libre_2": "",
            "libre_3": "",
            "custom_io_1": false,
            "custom_io_2": false,
            "custom_io_3": false,
            "custom_date_1": "",
            "custom_date_2": "",
            "custom_date_3": "",
            "news_sms": false,
            "news_email": true,
            "fidelite_active": true,
            "actif": true,
            "id_shop_origin": 1,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00",
            "adresse": {
                "ligne1": "12 rue des Lilas",
                "ligne2": "",
                "cp": "69003",
                "ville": "Lyon",
                "id_pays": 63,
                "pays_code": "FR",
                "pays": "France",
                "tva_intra": "",
                "archived": false
            },
            "fidelite": {
                "points_actuels": 120,
                "points_cumules": 340,
                "nb_fois_pts_utilises": 2,
                "last_pts_acquis": 15,
                "total_ca": 412.5,
                "total_qt": 17,
                "total_pa": 9
            },
            "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": "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": ""
                }
            ]
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customers/export" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/customers/deleted

**Lister les clients supprimés**

Renvoie les clients supprimés du compte : leur identifiant et la date de leur suppression, rien d'autre. Leurs coordonnées ne sont plus accessibles par l'API.

Cette adresse sert à tenir un autre outil à jour : après avoir relu les fiches modifiées avec `GET /v1/customers/export`, retirez de votre côté les identifiants renvoyés ici. Passez `since` pour ne recevoir que les suppressions depuis votre dernier passage.

Même parcours par curseur que l'export : tant que `meta.has_more` vaut `true`, rappelez avec `after` égal à `meta.next_after`. Permission `export_customers`.

- Clé d'API : requise. Permission : `export_customers` (Exporter tout le fichier clients).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `since` | URL (?nom=valeur) | non | Ne renvoie que les clients supprimés depuis cette date. Formats acceptés : `2026-11-01` (minuit, heure de Paris) ou `2026-11-01T08:30:00+01:00`. Sans fuseau, l'heure est celle de Paris. Pensez à encoder le `+` dans l'URL (`%2B`). |

Réponse en cas de succès (statut 200) : Une page des clients supprimés.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Clients supprimés, par identifiant croissant. Liste vide si aucun. |
| `data[].id` | entier | Identifiant du client supprimé. |
| `data[].date_suppression` | texte | Date et heure de la suppression. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 1790,
            "date_suppression": "2026-11-03T18:12:45+01:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customers/deleted" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/loyalty-program

**Lire le programme de fidélité du compte**

Renvoie les réglages du programme de fidélité : comment un point se gagne, combien il en faut pour déclencher la récompense, et ce qu'elle apporte. Toute clé valide peut l'appeler.

Appelez cette adresse avant de raisonner sur des points : un point n'a pas la même valeur d'un compte à l'autre. Selon `type`, un point correspond à une unité de monnaie dépensée (`ca`), à un article acheté (`qt`) ou à un passage en caisse (`pa`). Un client atteint la récompense quand son solde (`fidelite.points_actuels` dans sa fiche) est supérieur ou égal à `points_trigger`.

Si `actif` vaut `false`, le programme est désactivé : les ventes ne rapportent pas de points, mais les soldes existants sont conservés.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Le programme de fidélité du compte.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.actif` | booléen | `true` si le programme de fidélité est activé sur le compte. S'il vaut `false`, les ventes ne rapportent aucun point. |
| `data.type` | texte | Comment un point se gagne : `ca` (un point par unité de monnaie dépensée), `qt` (un point par article acheté) ou `pa` (un point par passage en caisse). |
| `data.points_trigger` | entier | Nombre de points à atteindre pour déclencher la récompense. |
| `data.reward_type` | texte | Récompense accordée quand le seuil est atteint : `pourcentage` (une remise en pourcentage sur un ticket) ou `disabled` (aucune récompense automatique). |
| `data.remise_pc_val` | entier | Pourcentage de la remise accordée, quand `reward_type` vaut `pourcentage`. |
| `data.include_reward_ticket` | booléen | `true` si le ticket qui utilise la récompense rapporte lui aussi des points. |
| `data.promo_compte` | booléen | `true` si les articles en promotion ou en solde rapportent des points. |
| `data.date_update` | texte | Date du dernier réglage du programme. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "actif": true,
        "type": "ca",
        "points_trigger": 500,
        "reward_type": "pourcentage",
        "remise_pc_val": 10,
        "include_reward_ticket": false,
        "promo_compte": false,
        "date_update": "2026-04-02T09:15:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/loyalty-program" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 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.

### POST /v1/customers/{id}/loyalty-points

**Ajouter ou retirer des points de fidélité à un client**

Ajoute ou retire des points au solde de fidélité d'un client, et renvoie le solde avant et après. Cette adresse demande la permission `write_loyalty`, distincte de `write_customers`.

`points` est un ajustement, pas un solde : envoyez `50` pour ajouter 50 points, `-20` pour en retirer 20. Vous n'avez pas à lire le solde avant, ni à calculer le nouveau. Un appel ne peut pas dépasser 1000 points, en plus comme en moins. Le solde ne peut pas devenir négatif ni dépasser 1 000 000 : un ajustement qui le ferait sortir de ces bornes est refusé avec l'erreur `points_out_of_range`, qui donne le solde actuel. Il n'est jamais arrondi à votre place.

L'en-tête `Idempotency-Key` est obligatoire sur cette adresse. Comme l'ajustement s'ajoute au solde, une requête renvoyée après une coupure réseau sans cet identifiant ajouterait les points deux fois. Utilisez un identifiant nouveau pour chaque ajustement voulu, et le même identifiant si vous renvoyez la même requête.

`motif` est obligatoire : dites en quelques mots pourquoi ces points sont ajoutés ou retirés (parrainage, geste commercial, correction). Le titulaire du compte le lit dans son journal des modifications.

Seul le solde actuel change. Les points cumulés depuis l'origine, le nombre d'utilisations et les totaux d'achats reflètent l'activité réelle du client et ne se modifient pas. Les points que valent vos ajustements dépendent du programme du compte : voir `GET /v1/loyalty-program`. L'ajustement est accepté même si le programme est désactivé. Pour vérifier une requête sans rien modifier, ajoutez `?dry_run=true`.

- Clé d'API : requise. Permission : `write_loyalty` (Ajuster les points de fidélité).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du client (champ `id`). |
| `Idempotency-Key` | en-tête | oui | Obligatoire. Identifiant unique de votre choix (8 à 100 caractères), nouveau pour chaque ajustement. |
| `dry_run` | URL (?nom=valeur) | non | `true` pour tout vérifier sans rien modifier : la réponse est celle que vous auriez obtenue, avec `meta.dry_run` à `true`. |

Corps JSON à envoyer :

| Champ | Type | Description |
|---|---|---|
| `points` | entier | Nombre de points à ajouter (positif) ou à retirer (négatif). Jamais 0. De -1000 à 1000 par appel. |
| `motif` | texte | Raison de l'ajustement, en quelques mots. Obligatoire, 100 caractères au maximum. Elle est inscrite dans le journal des modifications que le titulaire du compte consulte. |

Réponse en cas de succès (statut 200) : L'ajustement est enregistré.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id_client` | entier | Identifiant du client. |
| `data.ajustement` | entier | Nombre de points ajoutés (positif) ou retirés (négatif). |
| `data.points_avant` | entier | Solde de points avant l'ajustement. |
| `data.points_actuels` | entier | Solde de points après l'ajustement. |
| `data.motif` | texte | Raison donnée pour l'ajustement. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id_client": 1842,
        "ajustement": 50,
        "points_avant": 120,
        "points_actuels": 170,
        "motif": "Parrainage"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/customers/1842/loyalty-points" -H "Authorization: Bearer VOTRE_CLE" -H "Idempotency-Key: parrainage-1842-2026-11-11" -H "Content-Type: application/json" -d '{"points":50,"motif":"Parrainage"}'
```

Erreurs possibles :

- Statut 400 : L'en-tête `Idempotency-Key` est absent ou mal formé. Codes : `idempotency_key_required`, `idempotency_key_invalid`, `invalid_json`.
- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : L'ajustement ferait passer le solde sous 0 ou au-dessus de 1 000 000. Code : `points_out_of_range`. Le message donne le solde actuel. Rien n'a été modifié.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.

### GET /v1/products

**Parcourir tout le catalogue**

Renvoie les produits du compte page par page, par identifiant croissant, chacun avec ses variantes, ses codes et ses prix.

Cette adresse sert à lire tout le catalogue, par exemple pour tenir à jour une boutique en ligne ou un tableau de bord. Ce n'est pas une recherche : elle ne filtre ni par nom, ni par code, ni par fournisseur. Si vous connaissez l'identifiant d'un produit, appelez `GET /v1/products/{id}` ; si vous avez un code, une référence ou sa désignation exacte, appelez `GET /v1/products/lookup`.

Le parcours se fait par curseur. Appelez d'abord sans `after`. Tant que `meta.has_more` vaut `true`, rappelez avec `after` égal à `meta.next_after`. Quand `has_more` vaut `false`, le parcours est terminé. Ne construisez pas le curseur vous-même et n'utilisez pas de numéro de page.

Les produits archivés ne sont pas renvoyés, sauf avec `archived=true`. Un produit supprimé dans l'application est définitivement effacé : il disparaît simplement du parcours, sans liste des suppressions. Il n'existe pas de filtre « modifiés depuis » : pour vous synchroniser, relisez le catalogue en entier et comparez.

Le stock ne fait pas partie du produit. Les codes (`bc_ext`, `ean_int`, `sku`) sont portés par les variantes : un produit sans variante en a une seule, la variante « produit seul ». Le prix payé en caisse se lit dans `variantes_product[].prix`, par magasin et hors promotion ; `pv_ttc` n'est que le prix de base. Cette permission donne aussi accès aux prix d'achat.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre de produits par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les produits dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `archived` | URL (?nom=valeur) | non | `true` pour inclure aussi les produits archivés. `false` par défaut : seuls les produits non archivés sont renvoyés. |

Réponse en cas de succès (statut 200) : Une page du catalogue.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Produits de la page, par identifiant croissant. Liste vide si aucun. |
| `data[].id` | entier | Identifiant du produit. C'est le `id_product` des lignes de vente. |
| `data[].designation` | texte | Nom du produit (50 caractères au plus). |
| `data[].description` | texte | Description du produit. |
| `data[].notes` | texte | Notes internes du commerçant. |
| `data[].ref_four` | texte | Référence du produit chez le fournisseur. |
| `data[].ref_interne` | texte | Référence interne du commerçant. |
| `data[].image_url` | texte | Adresse de l'image du produit (fichier JPEG), lisible sans clé. Chaîne vide si le produit n'a pas d'image. L'adresse ne change pas quand le commerçant remplace l'image. |
| `data[].gestion_stock` | booléen | `true` si le stock de ce produit est suivi. |
| `data[].variantes` | booléen | `true` si le produit se décline en variantes (tailles, couleurs…). `false` : il n'a que sa variante « produit seul ». |
| `data[].favorite` | booléen | `true` si le commerçant l'a placé dans ses favoris de caisse. |
| `data[].archived` | booléen | `true` si le produit est archivé : il n'est plus proposé à la vente, mais il reste lisible. |
| `data[].pa_ht` | nombre | Prix d'achat hors taxes du produit. Chaque variante peut s'en écarter (`impact_pa`). |
| `data[].pv_ttc` | nombre | Prix de vente de base, toutes taxes comprises. Ce n'est pas forcément le prix payé en caisse : chaque variante et chaque magasin peuvent s'en écarter. Le prix réellement appliqué se lit dans `variantes_product[].prix`. |
| `data[].eco_ttc` | nombre | Montant de l'éco-participation, toutes taxes comprises, inclus dans le prix de vente. 0 s'il n'y en a pas. |
| `data[].fournisseur` | objet | Fournisseur du produit. |
| `data[].fournisseur.id` | entier | Identifiant du fournisseur. 0 si le produit n'en a pas. |
| `data[].fournisseur.name` | texte | Nom du fournisseur. Chaîne vide si le produit n'en a pas. |
| `data[].collec` | objet | Collection du produit. |
| `data[].collec.id` | entier | Identifiant de la collection. 0 si le produit n'en a pas. |
| `data[].collec.name` | texte | Nom de la collection. Chaîne vide si le produit n'en a pas. |
| `data[].categories` | liste | Catégories du produit, du niveau le plus général au plus précis (cinq niveaux au plus). Liste vide si le produit n'est pas classé. |
| `data[].categories[].niveau` | entier | Niveau de la catégorie, de 1 (le plus général) à 5. |
| `data[].categories[].id` | entier | Identifiant de la catégorie. |
| `data[].categories[].name` | texte | Nom de la catégorie. |
| `data[].libre_1` | texte | Champ personnalisé texte n° 1. |
| `data[].libre_2` | texte | Champ personnalisé texte n° 2. |
| `data[].libre_3` | texte | Champ personnalisé texte n° 3. |
| `data[].id_custom_list_1` | entier | Champ personnalisé liste n° 1 : identifiant de la valeur choisie, 0 si aucune. La valeur en clair est dans `champs_personnalises`. |
| `data[].id_custom_list_2` | entier | Champ personnalisé liste n° 2 : identifiant de la valeur choisie, 0 si aucune. |
| `data[].id_custom_list_3` | entier | Champ personnalisé liste n° 3 : identifiant de la valeur choisie, 0 si aucune. |
| `data[].custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data[].custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data[].custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data[].custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].custom_date_2` | texte | Champ personnalisé date n° 2 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].custom_date_3` | texte | Champ personnalisé date n° 3 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].magasins` | liste | Ce que chaque magasin du compte change à ce produit : son écart de prix et son taux de TVA. Une entrée par magasin non archivé, dans l'ordre de `GET /v1/me`. |
| `data[].magasins[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].magasins[].impact_pv` | nombre | Écart de prix de vente appliqué à ce produit dans ce magasin. 0 le plus souvent. |
| `data[].magasins[].tva_taux` | nombre | Taux de TVA du produit dans ce magasin, en pourcentage (exemple : 20, 5.5). |
| `data[].variantes_product` | liste | Variantes en service. Toujours au moins une : pour un produit sans variante, c'est sa variante « produit seul ». Les codes (`bc_ext`, `ean_int`, `sku`) et les prix par magasin sont ici, jamais sur le produit. |
| `data[].variantes_product[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data[].variantes_product[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data[].variantes_product[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data[].variantes_product[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data[].variantes_product[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data[].variantes_product[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data[].variantes_product[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data[].variantes_product[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data[].variantes_product[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data[].variantes_product[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data[].variantes_product[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data[].variantes_product[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].variantes_product[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data[].variantes_product[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data[].variantes_product[].date_creation` | texte | Date de création, ISO 8601. |
| `data[].variantes_product[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data[].variantes_inactives` | liste | Variantes désactivées : le commerçant les a retirées, Wanapos les conserve parce qu'elles ont déjà été vendues. Elles ne sont plus proposées à la vente et n'ont plus de stock. Liste vide le plus souvent. Utile pour retrouver le nom d'une variante citée dans une ancienne vente. |
| `data[].variantes_inactives[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data[].variantes_inactives[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data[].variantes_inactives[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data[].variantes_inactives[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data[].variantes_inactives[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data[].variantes_inactives[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data[].variantes_inactives[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data[].variantes_inactives[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data[].variantes_inactives[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data[].variantes_inactives[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data[].variantes_inactives[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data[].variantes_inactives[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].variantes_inactives[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data[].variantes_inactives[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data[].variantes_inactives[].date_creation` | texte | Date de création, ISO 8601. |
| `data[].variantes_inactives[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data[].champs_personnalises` | liste | Les douze champs personnalisés du produit, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `id_custom_list_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. Pour une liste, `valeur` est la valeur choisie en clair. |
| `data[].champs_personnalises[].cle` | texte | Nom du champ dans l'objet produit (exemple : `libre_1`). |
| `data[].champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data[].champs_personnalises[].type` | texte | Nature du champ. |
| `data[].champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data[].champs_personnalises[].valeur` |  | Valeur du champ : texte, valeur de liste en clair, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `data[].date_creation` | texte | Date de création du produit, ISO 8601. |
| `data[].date_update` | texte | Date de dernière modification de la fiche du produit, ISO 8601. Elle ne suit pas les changements de variantes ni de prix : ne vous en servez pas pour détecter ce qui a changé. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 312,
            "designation": "Tee-shirt col rond",
            "description": "Coton bio, coupe droite.",
            "notes": "",
            "ref_four": "TS-8744",
            "ref_interne": "",
            "image_url": "https://api.wanapos.com/web/data_user/0001842/images/product/wanapos_312.jpg",
            "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-09-02T09:40:00+02: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-09-02T09:40:00+02: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-09-02T09:40:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/products" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/products

**Créer un produit**

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.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `dry_run` | URL (?nom=valeur) | non | `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` | URL (?nom=valeur) | non | `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` | en-tête | non | 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. |

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. |
| `data.id` | entier | Identifiant du produit. C'est le `id_product` des lignes de vente. |
| `data.designation` | texte | Nom du produit (50 caractères au plus). |
| `data.description` | texte | Description du produit. |
| `data.notes` | texte | Notes internes du commerçant. |
| `data.ref_four` | texte | Référence du produit chez le fournisseur. |
| `data.ref_interne` | texte | Référence interne du commerçant. |
| `data.image_url` | texte | Adresse de l'image du produit (fichier JPEG), lisible sans clé. Chaîne vide si le produit n'a pas d'image. L'adresse ne change pas quand le commerçant remplace l'image. |
| `data.gestion_stock` | booléen | `true` si le stock de ce produit est suivi. |
| `data.variantes` | booléen | `true` si le produit se décline en variantes (tailles, couleurs…). `false` : il n'a que sa variante « produit seul ». |
| `data.favorite` | booléen | `true` si le commerçant l'a placé dans ses favoris de caisse. |
| `data.archived` | booléen | `true` si le produit est archivé : il n'est plus proposé à la vente, mais il reste lisible. |
| `data.pa_ht` | nombre | Prix d'achat hors taxes du produit. Chaque variante peut s'en écarter (`impact_pa`). |
| `data.pv_ttc` | nombre | Prix de vente de base, toutes taxes comprises. Ce n'est pas forcément le prix payé en caisse : chaque variante et chaque magasin peuvent s'en écarter. Le prix réellement appliqué se lit dans `variantes_product[].prix`. |
| `data.eco_ttc` | nombre | Montant de l'éco-participation, toutes taxes comprises, inclus dans le prix de vente. 0 s'il n'y en a pas. |
| `data.fournisseur` | objet | Fournisseur du produit. |
| `data.fournisseur.id` | entier | Identifiant du fournisseur. 0 si le produit n'en a pas. |
| `data.fournisseur.name` | texte | Nom du fournisseur. Chaîne vide si le produit n'en a pas. |
| `data.collec` | objet | Collection du produit. |
| `data.collec.id` | entier | Identifiant de la collection. 0 si le produit n'en a pas. |
| `data.collec.name` | texte | Nom de la collection. Chaîne vide si le produit n'en a pas. |
| `data.categories` | liste | Catégories du produit, du niveau le plus général au plus précis (cinq niveaux au plus). Liste vide si le produit n'est pas classé. |
| `data.categories[].niveau` | entier | Niveau de la catégorie, de 1 (le plus général) à 5. |
| `data.categories[].id` | entier | Identifiant de la catégorie. |
| `data.categories[].name` | texte | Nom de la catégorie. |
| `data.libre_1` | texte | Champ personnalisé texte n° 1. |
| `data.libre_2` | texte | Champ personnalisé texte n° 2. |
| `data.libre_3` | texte | Champ personnalisé texte n° 3. |
| `data.id_custom_list_1` | entier | Champ personnalisé liste n° 1 : identifiant de la valeur choisie, 0 si aucune. La valeur en clair est dans `champs_personnalises`. |
| `data.id_custom_list_2` | entier | Champ personnalisé liste n° 2 : identifiant de la valeur choisie, 0 si aucune. |
| `data.id_custom_list_3` | entier | Champ personnalisé liste n° 3 : identifiant de la valeur choisie, 0 si aucune. |
| `data.custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data.custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data.custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data.custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.custom_date_2` | texte | Champ personnalisé date n° 2 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.custom_date_3` | texte | Champ personnalisé date n° 3 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.magasins` | liste | Ce que chaque magasin du compte change à ce produit : son écart de prix et son taux de TVA. Une entrée par magasin non archivé, dans l'ordre de `GET /v1/me`. |
| `data.magasins[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.magasins[].impact_pv` | nombre | Écart de prix de vente appliqué à ce produit dans ce magasin. 0 le plus souvent. |
| `data.magasins[].tva_taux` | nombre | Taux de TVA du produit dans ce magasin, en pourcentage (exemple : 20, 5.5). |
| `data.variantes_product` | liste | Variantes en service. Toujours au moins une : pour un produit sans variante, c'est sa variante « produit seul ». Les codes (`bc_ext`, `ean_int`, `sku`) et les prix par magasin sont ici, jamais sur le produit. |
| `data.variantes_product[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data.variantes_product[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data.variantes_product[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data.variantes_product[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data.variantes_product[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data.variantes_product[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data.variantes_product[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data.variantes_product[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data.variantes_product[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data.variantes_product[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data.variantes_product[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data.variantes_product[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.variantes_product[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data.variantes_product[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data.variantes_product[].date_creation` | texte | Date de création, ISO 8601. |
| `data.variantes_product[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data.variantes_inactives` | liste | Variantes désactivées : le commerçant les a retirées, Wanapos les conserve parce qu'elles ont déjà été vendues. Elles ne sont plus proposées à la vente et n'ont plus de stock. Liste vide le plus souvent. Utile pour retrouver le nom d'une variante citée dans une ancienne vente. |
| `data.variantes_inactives[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data.variantes_inactives[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data.variantes_inactives[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data.variantes_inactives[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data.variantes_inactives[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data.variantes_inactives[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data.variantes_inactives[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data.variantes_inactives[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data.variantes_inactives[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data.variantes_inactives[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data.variantes_inactives[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data.variantes_inactives[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.variantes_inactives[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data.variantes_inactives[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data.variantes_inactives[].date_creation` | texte | Date de création, ISO 8601. |
| `data.variantes_inactives[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data.champs_personnalises` | liste | Les douze champs personnalisés du produit, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `id_custom_list_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. Pour une liste, `valeur` est la valeur choisie en clair. |
| `data.champs_personnalises[].cle` | texte | Nom du champ dans l'objet produit (exemple : `libre_1`). |
| `data.champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data.champs_personnalises[].type` | texte | Nature du champ. |
| `data.champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data.champs_personnalises[].valeur` |  | Valeur du champ : texte, valeur de liste en clair, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `data.date_creation` | texte | Date de création du produit, ISO 8601. |
| `data.date_update` | texte | Date de dernière modification de la fiche du produit, ISO 8601. Elle ne suit pas les changements de variantes ni de prix : ne vous en servez pas pour détecter ce qui a changé. |
| `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. |

Exemple de réponse :

```json
{
    "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"
            }
        ]
    }
}
```

Exemple d'appel :

```bash
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}]}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 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é.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/products/lookup

**Identifier un produit par un code, une référence ou sa désignation**

Renvoie les produits dont un identifiant vaut exactement la valeur donnée, sans tenir compte des majuscules, des accents ni des espaces autour. Deux usages : retrouver le produit d'un code ou d'une référence que vous avez en main (un code-barres scanné, une ligne de bon de commande), et vérifier qu'un produit existe déjà avant d'en créer un.

Donnez un critère, et un seul, par appel : `designation`, `ref_four`, `ref_interne`, `bc_ext`, `ean_int`, `sku` ou `code`. Si vous avez un code sans savoir de quel type il est, utilisez `code` : il est comparé aux trois codes des variantes (`bc_ext`, `ean_int`, `sku`). Pour essayer plusieurs critères, faites un appel par critère.

Ce n'est pas une recherche par mots : la valeur doit correspondre en entier. `tee` ne trouve pas `Tee-shirt col rond`. Ce n'est pas non plus le parcours du catalogue : pour tout lire, utilisez `GET /v1/products`.

La réponse est toujours une liste : dans Wanapos, ni une désignation, ni une référence, ni même un code ne sont forcément uniques. Une liste vide signifie qu'aucun produit ne correspond, ce n'est pas une erreur. Si plusieurs produits reviennent, ne choisissez pas au hasard : départagez-les avec leurs autres champs, ou demandez à l'utilisateur.

Les codes sont portés par les variantes : l'appel renvoie le produit entier, et la variante concernée est celle de `variantes_product` dont `bc_ext`, `ean_int` ou `sku` correspond. Seules les variantes en service comptent : le code d'une variante désactivée ne fait ressortir aucun produit.

Les produits archivés sont renvoyés aussi (`archived` vaut `true`) : avant de créer un produit, regardez ce champ.

La liste est limitée à 50 produits. Si `meta.truncated` vaut `true`, plus de 50 produits correspondent et la liste est incomplète : il n'existe pas de page suivante. Parcourez alors le catalogue avec `GET /v1/products` et gardez les produits qui correspondent.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `code` | URL (?nom=valeur) | non | Un code dont vous ne connaissez pas le type : comparé à `bc_ext`, `ean_int` et `sku` des variantes en service (32 caractères au plus). |
| `bc_ext` | URL (?nom=valeur) | non | Code-barres externe d'une variante, celui du fabricant (32 caractères au plus). |
| `ean_int` | URL (?nom=valeur) | non | Code-barres interne d'une variante, généré par Wanapos (13 caractères au plus). |
| `sku` | URL (?nom=valeur) | non | Référence d'une variante, SKU (32 caractères au plus). |
| `ref_four` | URL (?nom=valeur) | non | Référence du produit chez le fournisseur (50 caractères au plus). |
| `ref_interne` | URL (?nom=valeur) | non | Référence interne du produit (50 caractères au plus). |
| `designation` | URL (?nom=valeur) | non | Nom complet du produit (50 caractères au plus). Pensez à l'encoder dans l'URL. |

Réponse en cas de succès (statut 200) : Les produits correspondants.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Produits correspondants, par identifiant croissant. Liste vide si aucun. |
| `data[].id` | entier | Identifiant du produit. C'est le `id_product` des lignes de vente. |
| `data[].designation` | texte | Nom du produit (50 caractères au plus). |
| `data[].description` | texte | Description du produit. |
| `data[].notes` | texte | Notes internes du commerçant. |
| `data[].ref_four` | texte | Référence du produit chez le fournisseur. |
| `data[].ref_interne` | texte | Référence interne du commerçant. |
| `data[].image_url` | texte | Adresse de l'image du produit (fichier JPEG), lisible sans clé. Chaîne vide si le produit n'a pas d'image. L'adresse ne change pas quand le commerçant remplace l'image. |
| `data[].gestion_stock` | booléen | `true` si le stock de ce produit est suivi. |
| `data[].variantes` | booléen | `true` si le produit se décline en variantes (tailles, couleurs…). `false` : il n'a que sa variante « produit seul ». |
| `data[].favorite` | booléen | `true` si le commerçant l'a placé dans ses favoris de caisse. |
| `data[].archived` | booléen | `true` si le produit est archivé : il n'est plus proposé à la vente, mais il reste lisible. |
| `data[].pa_ht` | nombre | Prix d'achat hors taxes du produit. Chaque variante peut s'en écarter (`impact_pa`). |
| `data[].pv_ttc` | nombre | Prix de vente de base, toutes taxes comprises. Ce n'est pas forcément le prix payé en caisse : chaque variante et chaque magasin peuvent s'en écarter. Le prix réellement appliqué se lit dans `variantes_product[].prix`. |
| `data[].eco_ttc` | nombre | Montant de l'éco-participation, toutes taxes comprises, inclus dans le prix de vente. 0 s'il n'y en a pas. |
| `data[].fournisseur` | objet | Fournisseur du produit. |
| `data[].fournisseur.id` | entier | Identifiant du fournisseur. 0 si le produit n'en a pas. |
| `data[].fournisseur.name` | texte | Nom du fournisseur. Chaîne vide si le produit n'en a pas. |
| `data[].collec` | objet | Collection du produit. |
| `data[].collec.id` | entier | Identifiant de la collection. 0 si le produit n'en a pas. |
| `data[].collec.name` | texte | Nom de la collection. Chaîne vide si le produit n'en a pas. |
| `data[].categories` | liste | Catégories du produit, du niveau le plus général au plus précis (cinq niveaux au plus). Liste vide si le produit n'est pas classé. |
| `data[].categories[].niveau` | entier | Niveau de la catégorie, de 1 (le plus général) à 5. |
| `data[].categories[].id` | entier | Identifiant de la catégorie. |
| `data[].categories[].name` | texte | Nom de la catégorie. |
| `data[].libre_1` | texte | Champ personnalisé texte n° 1. |
| `data[].libre_2` | texte | Champ personnalisé texte n° 2. |
| `data[].libre_3` | texte | Champ personnalisé texte n° 3. |
| `data[].id_custom_list_1` | entier | Champ personnalisé liste n° 1 : identifiant de la valeur choisie, 0 si aucune. La valeur en clair est dans `champs_personnalises`. |
| `data[].id_custom_list_2` | entier | Champ personnalisé liste n° 2 : identifiant de la valeur choisie, 0 si aucune. |
| `data[].id_custom_list_3` | entier | Champ personnalisé liste n° 3 : identifiant de la valeur choisie, 0 si aucune. |
| `data[].custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data[].custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data[].custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data[].custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].custom_date_2` | texte | Champ personnalisé date n° 2 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].custom_date_3` | texte | Champ personnalisé date n° 3 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data[].magasins` | liste | Ce que chaque magasin du compte change à ce produit : son écart de prix et son taux de TVA. Une entrée par magasin non archivé, dans l'ordre de `GET /v1/me`. |
| `data[].magasins[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].magasins[].impact_pv` | nombre | Écart de prix de vente appliqué à ce produit dans ce magasin. 0 le plus souvent. |
| `data[].magasins[].tva_taux` | nombre | Taux de TVA du produit dans ce magasin, en pourcentage (exemple : 20, 5.5). |
| `data[].variantes_product` | liste | Variantes en service. Toujours au moins une : pour un produit sans variante, c'est sa variante « produit seul ». Les codes (`bc_ext`, `ean_int`, `sku`) et les prix par magasin sont ici, jamais sur le produit. |
| `data[].variantes_product[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data[].variantes_product[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data[].variantes_product[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data[].variantes_product[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data[].variantes_product[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data[].variantes_product[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data[].variantes_product[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data[].variantes_product[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data[].variantes_product[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data[].variantes_product[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data[].variantes_product[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data[].variantes_product[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].variantes_product[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data[].variantes_product[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data[].variantes_product[].date_creation` | texte | Date de création, ISO 8601. |
| `data[].variantes_product[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data[].variantes_inactives` | liste | Variantes désactivées : le commerçant les a retirées, Wanapos les conserve parce qu'elles ont déjà été vendues. Elles ne sont plus proposées à la vente et n'ont plus de stock. Liste vide le plus souvent. Utile pour retrouver le nom d'une variante citée dans une ancienne vente. |
| `data[].variantes_inactives[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data[].variantes_inactives[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data[].variantes_inactives[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data[].variantes_inactives[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data[].variantes_inactives[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data[].variantes_inactives[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data[].variantes_inactives[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data[].variantes_inactives[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data[].variantes_inactives[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data[].variantes_inactives[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data[].variantes_inactives[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data[].variantes_inactives[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data[].variantes_inactives[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data[].variantes_inactives[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data[].variantes_inactives[].date_creation` | texte | Date de création, ISO 8601. |
| `data[].variantes_inactives[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data[].champs_personnalises` | liste | Les douze champs personnalisés du produit, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `id_custom_list_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. Pour une liste, `valeur` est la valeur choisie en clair. |
| `data[].champs_personnalises[].cle` | texte | Nom du champ dans l'objet produit (exemple : `libre_1`). |
| `data[].champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data[].champs_personnalises[].type` | texte | Nature du champ. |
| `data[].champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data[].champs_personnalises[].valeur` |  | Valeur du champ : texte, valeur de liste en clair, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `data[].date_creation` | texte | Date de création du produit, ISO 8601. |
| `data[].date_update` | texte | Date de dernière modification de la fiche du produit, ISO 8601. Elle ne suit pas les changements de variantes ni de prix : ne vous en servez pas pour détecter ce qui a changé. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre de produits renvoyés. |
| `meta.truncated` | booléen | `true` si plus de 50 produits correspondent : la liste est alors incomplète, voir la description de l'adresse. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 312,
            "designation": "Tee-shirt col rond",
            "description": "Coton bio, coupe droite.",
            "notes": "",
            "ref_four": "TS-8744",
            "ref_interne": "",
            "image_url": "https://api.wanapos.com/web/data_user/0001842/images/product/wanapos_312.jpg",
            "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-09-02T09:40:00+02: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-09-02T09:40:00+02: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-09-02T09:40:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "truncated": false
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/products/lookup?code=3760000000022" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/products/{id}

**Lire un produit par son identifiant**

Renvoie un produit complet : identité, classement, prix, variantes et champs personnalisés. L'identifiant est le champ `id` d'un produit, ou le `id_product` d'une ligne de vente.

Un produit archivé reste lisible ici (`archived` vaut `true`). Un produit supprimé dans l'application est définitivement effacé : l'appel répond 404.

Le stock ne fait pas partie du produit. Les codes (`bc_ext`, `ean_int`, `sku`) sont portés par les variantes : un produit sans variante en a une seule, la variante « produit seul ». Le prix payé en caisse se lit dans `variantes_product[].prix`, par magasin et hors promotion ; `pv_ttc` n'est que le prix de base. Cette permission donne aussi accès aux prix d'achat.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du produit (champ `id`). |

Réponse en cas de succès (statut 200) : Le produit.

| Champ | Type | Description |
|---|---|---|
| `data` | objet | Un produit du catalogue, avec ses variantes, ses codes et ses prix. Le stock n'en fait pas partie. |
| `data.id` | entier | Identifiant du produit. C'est le `id_product` des lignes de vente. |
| `data.designation` | texte | Nom du produit (50 caractères au plus). |
| `data.description` | texte | Description du produit. |
| `data.notes` | texte | Notes internes du commerçant. |
| `data.ref_four` | texte | Référence du produit chez le fournisseur. |
| `data.ref_interne` | texte | Référence interne du commerçant. |
| `data.image_url` | texte | Adresse de l'image du produit (fichier JPEG), lisible sans clé. Chaîne vide si le produit n'a pas d'image. L'adresse ne change pas quand le commerçant remplace l'image. |
| `data.gestion_stock` | booléen | `true` si le stock de ce produit est suivi. |
| `data.variantes` | booléen | `true` si le produit se décline en variantes (tailles, couleurs…). `false` : il n'a que sa variante « produit seul ». |
| `data.favorite` | booléen | `true` si le commerçant l'a placé dans ses favoris de caisse. |
| `data.archived` | booléen | `true` si le produit est archivé : il n'est plus proposé à la vente, mais il reste lisible. |
| `data.pa_ht` | nombre | Prix d'achat hors taxes du produit. Chaque variante peut s'en écarter (`impact_pa`). |
| `data.pv_ttc` | nombre | Prix de vente de base, toutes taxes comprises. Ce n'est pas forcément le prix payé en caisse : chaque variante et chaque magasin peuvent s'en écarter. Le prix réellement appliqué se lit dans `variantes_product[].prix`. |
| `data.eco_ttc` | nombre | Montant de l'éco-participation, toutes taxes comprises, inclus dans le prix de vente. 0 s'il n'y en a pas. |
| `data.fournisseur` | objet | Fournisseur du produit. |
| `data.fournisseur.id` | entier | Identifiant du fournisseur. 0 si le produit n'en a pas. |
| `data.fournisseur.name` | texte | Nom du fournisseur. Chaîne vide si le produit n'en a pas. |
| `data.collec` | objet | Collection du produit. |
| `data.collec.id` | entier | Identifiant de la collection. 0 si le produit n'en a pas. |
| `data.collec.name` | texte | Nom de la collection. Chaîne vide si le produit n'en a pas. |
| `data.categories` | liste | Catégories du produit, du niveau le plus général au plus précis (cinq niveaux au plus). Liste vide si le produit n'est pas classé. |
| `data.categories[].niveau` | entier | Niveau de la catégorie, de 1 (le plus général) à 5. |
| `data.categories[].id` | entier | Identifiant de la catégorie. |
| `data.categories[].name` | texte | Nom de la catégorie. |
| `data.libre_1` | texte | Champ personnalisé texte n° 1. |
| `data.libre_2` | texte | Champ personnalisé texte n° 2. |
| `data.libre_3` | texte | Champ personnalisé texte n° 3. |
| `data.id_custom_list_1` | entier | Champ personnalisé liste n° 1 : identifiant de la valeur choisie, 0 si aucune. La valeur en clair est dans `champs_personnalises`. |
| `data.id_custom_list_2` | entier | Champ personnalisé liste n° 2 : identifiant de la valeur choisie, 0 si aucune. |
| `data.id_custom_list_3` | entier | Champ personnalisé liste n° 3 : identifiant de la valeur choisie, 0 si aucune. |
| `data.custom_io_1` | booléen | Champ personnalisé oui/non n° 1. |
| `data.custom_io_2` | booléen | Champ personnalisé oui/non n° 2. |
| `data.custom_io_3` | booléen | Champ personnalisé oui/non n° 3. |
| `data.custom_date_1` | texte | Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.custom_date_2` | texte | Champ personnalisé date n° 2 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.custom_date_3` | texte | Champ personnalisé date n° 3 (AAAA-MM-JJ). Chaîne vide si non renseigné. |
| `data.magasins` | liste | Ce que chaque magasin du compte change à ce produit : son écart de prix et son taux de TVA. Une entrée par magasin non archivé, dans l'ordre de `GET /v1/me`. |
| `data.magasins[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.magasins[].impact_pv` | nombre | Écart de prix de vente appliqué à ce produit dans ce magasin. 0 le plus souvent. |
| `data.magasins[].tva_taux` | nombre | Taux de TVA du produit dans ce magasin, en pourcentage (exemple : 20, 5.5). |
| `data.variantes_product` | liste | Variantes en service. Toujours au moins une : pour un produit sans variante, c'est sa variante « produit seul ». Les codes (`bc_ext`, `ean_int`, `sku`) et les prix par magasin sont ici, jamais sur le produit. |
| `data.variantes_product[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data.variantes_product[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data.variantes_product[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data.variantes_product[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data.variantes_product[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data.variantes_product[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data.variantes_product[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data.variantes_product[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data.variantes_product[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data.variantes_product[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data.variantes_product[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data.variantes_product[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.variantes_product[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data.variantes_product[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data.variantes_product[].date_creation` | texte | Date de création, ISO 8601. |
| `data.variantes_product[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data.variantes_inactives` | liste | Variantes désactivées : le commerçant les a retirées, Wanapos les conserve parce qu'elles ont déjà été vendues. Elles ne sont plus proposées à la vente et n'ont plus de stock. Liste vide le plus souvent. Utile pour retrouver le nom d'une variante citée dans une ancienne vente. |
| `data.variantes_inactives[].id` | entier | Identifiant de la variante. C'est le `id_variante_product` des lignes de vente. |
| `data.variantes_inactives[].is_product` | booléen | `true` pour la variante « produit seul » d'un produit sans variante. |
| `data.variantes_inactives[].name` | texte | Nom de la variante (exemple : `M`, `Bleu / 42`). Chaîne vide pour la variante « produit seul ». |
| `data.variantes_inactives[].position` | entier | Rang d'affichage choisi par le commerçant. |
| `data.variantes_inactives[].bc_ext` | texte | Code-barres externe, celui du fabricant (32 caractères au plus). Chaîne vide si non renseigné. |
| `data.variantes_inactives[].ean_int` | texte | Code-barres interne, généré par Wanapos (13 chiffres). Chaîne vide si non renseigné. |
| `data.variantes_inactives[].sku` | texte | Référence de la variante (SKU, 32 caractères au plus). Chaîne vide si non renseignée. |
| `data.variantes_inactives[].impact_pa` | nombre | Écart de prix d'achat de cette variante par rapport au `pa_ht` du produit. 0 le plus souvent. |
| `data.variantes_inactives[].pa_ht` | nombre | Prix d'achat hors taxes de cette variante : `pa_ht` du produit plus `impact_pa`. |
| `data.variantes_inactives[].impact_pv` | nombre | Écart de prix de vente de cette variante par rapport au `pv_ttc` du produit (exemple : 3 pour une taille vendue 3 de plus). |
| `data.variantes_inactives[].prix` | liste | Prix de vente de cette variante dans chaque magasin du compte, déjà calculé : `pv_ttc` du produit, plus `impact_pv` de la variante, plus `impact_pv` du magasin. Hors promotion. Une entrée par magasin, dans l'ordre de `magasins`. |
| `data.variantes_inactives[].prix[].id_shop` | entier | Identifiant du magasin (voir `GET /v1/me`). |
| `data.variantes_inactives[].prix[].pv_ttc` | nombre | Prix de vente toutes taxes comprises dans ce magasin, hors promotion. |
| `data.variantes_inactives[].actif` | booléen | `true` pour une variante en service, `false` pour une variante désactivée. |
| `data.variantes_inactives[].date_creation` | texte | Date de création, ISO 8601. |
| `data.variantes_inactives[].date_update` | texte | Date de dernière modification de la variante, ISO 8601. Chaîne vide si inconnue. |
| `data.champs_personnalises` | liste | Les douze champs personnalisés du produit, avec le libellé que le commerçant leur a donné. Mêmes valeurs que `libre_N`, `id_custom_list_N`, `custom_io_N` et `custom_date_N`, présentées de façon lisible. Pour une liste, `valeur` est la valeur choisie en clair. |
| `data.champs_personnalises[].cle` | texte | Nom du champ dans l'objet produit (exemple : `libre_1`). |
| `data.champs_personnalises[].libelle` | texte | Libellé choisi par le commerçant. |
| `data.champs_personnalises[].type` | texte | Nature du champ. |
| `data.champs_personnalises[].affiche` | booléen | Le commerçant affiche ce champ dans son application. |
| `data.champs_personnalises[].valeur` |  | Valeur du champ : texte, valeur de liste en clair, booléen ou date (AAAA-MM-JJ) selon `type`. |
| `data.date_creation` | texte | Date de création du produit, ISO 8601. |
| `data.date_update` | texte | Date de dernière modification de la fiche du produit, ISO 8601. Elle ne suit pas les changements de variantes ni de prix : ne vous en servez pas pour détecter ce qui a changé. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 312,
        "designation": "Tee-shirt col rond",
        "description": "Coton bio, coupe droite.",
        "notes": "",
        "ref_four": "TS-8744",
        "ref_interne": "",
        "image_url": "https://api.wanapos.com/web/data_user/0001842/images/product/wanapos_312.jpg",
        "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-09-02T09:40:00+02: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-09-02T09:40:00+02: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-09-02T09:40:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/products/312" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/suppliers

**Lister les fournisseurs**

Renvoie les fournisseurs du compte, avec leurs coordonnées et leur adresse, par identifiant croissant. C'est ici que se traduit le `fournisseur.id` d'un produit.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez l'adresse avec `after` égal à `meta.next_after`. Les éléments archivés ne sont renvoyés qu'avec `archived=true`.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `archived` | URL (?nom=valeur) | non | `true` pour inclure aussi les éléments archivés. `false` par défaut : seuls les éléments en service sont renvoyés. |

Réponse en cas de succès (statut 200) : Une page de fournisseurs.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Une page, par identifiant croissant. Liste vide s'il n'y a rien. |
| `data[].id` | entier | Identifiant du fournisseur. C'est la valeur de `fournisseur.id` dans un produit. |
| `data[].name` | texte | Nom du fournisseur. |
| `data[].commercial1` | texte | Nom du premier contact commercial. |
| `data[].commercial2` | texte | Nom du second contact commercial. |
| `data[].tel` | texte | Téléphone. |
| `data[].mobile` | texte | Mobile. |
| `data[].email` | texte | Adresse mail. |
| `data[].tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data[].notes` | texte | Notes libres du commerçant. |
| `data[].archived` | booléen | `true` si le fournisseur est archivé : il n'est plus proposé dans l'application, mais les produits qui le portent le gardent. |
| `data[].date_creation` | texte | Date de création. |
| `data[].date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `data[].adresse` | objet | Adresse du fournisseur. |
| `data[].adresse.ligne1` | texte | Adresse, première ligne. |
| `data[].adresse.ligne2` | texte | Complément d'adresse. |
| `data[].adresse.cp` | texte | Code postal. |
| `data[].adresse.ville` | texte | Ville. |
| `data[].adresse.id_pays` | entier | Identifiant du pays (voir `GET /v1/countries`). 0 si non renseigné. |
| `data[].adresse.pays_code` | texte | Code du pays à deux lettres. |
| `data[].adresse.pays` | texte | Nom du pays en français. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 7,
            "name": "Maison Verdier",
            "commercial1": "Julie Arnaud",
            "commercial2": "",
            "tel": "0472000000",
            "mobile": "",
            "email": "contact@maison-verdier.example",
            "tva_intra": "",
            "notes": "",
            "archived": false,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00",
            "adresse": {
                "ligne1": "4 quai des Tanneurs",
                "ligne2": "",
                "cp": "69009",
                "ville": "Lyon",
                "id_pays": 63,
                "pays_code": "FR",
                "pays": "France"
            }
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/suppliers" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/suppliers

**Créer un fournisseur**

Crée un fournisseur et renvoie sa fiche. Seul `name` est obligatoire.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

Pour rattacher ensuite un produit à ce fournisseur, donnez son identifiant ou son nom à la création du produit.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom du fournisseur. De 3 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `commercial1` | texte | Premier contact commercial. 100 caractères au maximum. |
| `commercial2` | texte | Second contact commercial. 100 caractères au maximum. |
| `tel` | texte | Téléphone. 17 caractères au maximum. |
| `mobile` | texte | Mobile. 17 caractères au maximum. |
| `email` | texte | Adresse mail. 50 caractères au maximum. |
| `tva_intra` | texte | Numéro de TVA intracommunautaire. 32 caractères au maximum. |
| `notes` | texte | Notes libres. 5 000 caractères au maximum. |
| `adresse` | objet | Adresse du fournisseur. Seuls les champs envoyés changent. |
| `adresse.ligne1` | texte | Adresse, première ligne. 50 caractères au maximum. |
| `adresse.ligne2` | texte | Complément d'adresse. 50 caractères au maximum. |
| `adresse.cp` | texte | Code postal. 9 caractères au maximum. |
| `adresse.ville` | texte | Ville. 30 caractères au maximum. |
| `adresse.pays_code` | texte | Code du pays à deux lettres (voir `GET /v1/countries`). À la création, s'il est absent : le pays du magasin principal. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 201) : Le fournisseur créé.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant du fournisseur. C'est la valeur de `fournisseur.id` dans un produit. |
| `data.name` | texte | Nom du fournisseur. |
| `data.commercial1` | texte | Nom du premier contact commercial. |
| `data.commercial2` | texte | Nom du second contact commercial. |
| `data.tel` | texte | Téléphone. |
| `data.mobile` | texte | Mobile. |
| `data.email` | texte | Adresse mail. |
| `data.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.notes` | texte | Notes libres du commerçant. |
| `data.archived` | booléen | `true` si le fournisseur est archivé : il n'est plus proposé dans l'application, mais les produits qui le portent le gardent. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `data.adresse` | objet | Adresse du fournisseur. |
| `data.adresse.ligne1` | texte | Adresse, première ligne. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant du pays (voir `GET /v1/countries`). 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays à deux lettres. |
| `data.adresse.pays` | texte | Nom du pays en français. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 7,
        "name": "Maison Verdier",
        "commercial1": "Julie Arnaud",
        "commercial2": "",
        "tel": "0472000000",
        "mobile": "",
        "email": "contact@maison-verdier.example",
        "tva_intra": "",
        "notes": "",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "4 quai des Tanneurs",
            "ligne2": "",
            "cp": "69009",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France"
        }
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/suppliers" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Maison Verdier","commercial1":"Julie Arnaud","tel":"0472000000","email":"contact@maison-verdier.example","adresse":{"ligne1":"4 quai des Tanneurs","cp":"69009","ville":"Lyon","pays_code":"FR"}}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/suppliers/{id}

**Lire un fournisseur**

Renvoie un fournisseur par son identifiant, qu'il soit archivé ou non.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du fournisseur (champ `id`). |

Réponse en cas de succès (statut 200) : Le fournisseur.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant du fournisseur. C'est la valeur de `fournisseur.id` dans un produit. |
| `data.name` | texte | Nom du fournisseur. |
| `data.commercial1` | texte | Nom du premier contact commercial. |
| `data.commercial2` | texte | Nom du second contact commercial. |
| `data.tel` | texte | Téléphone. |
| `data.mobile` | texte | Mobile. |
| `data.email` | texte | Adresse mail. |
| `data.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.notes` | texte | Notes libres du commerçant. |
| `data.archived` | booléen | `true` si le fournisseur est archivé : il n'est plus proposé dans l'application, mais les produits qui le portent le gardent. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `data.adresse` | objet | Adresse du fournisseur. |
| `data.adresse.ligne1` | texte | Adresse, première ligne. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant du pays (voir `GET /v1/countries`). 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays à deux lettres. |
| `data.adresse.pays` | texte | Nom du pays en français. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 7,
        "name": "Maison Verdier",
        "commercial1": "Julie Arnaud",
        "commercial2": "",
        "tel": "0472000000",
        "mobile": "",
        "email": "contact@maison-verdier.example",
        "tva_intra": "",
        "notes": "",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "4 quai des Tanneurs",
            "ligne2": "",
            "cp": "69009",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France"
        }
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/suppliers/7" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### PATCH /v1/suppliers/{id}

**Modifier un fournisseur**

Modifie un fournisseur et renvoie sa fiche après modification.

La modification est partielle : seuls les champs envoyés changent. Il n'existe pas de suppression : pour retirer un élément, archivez-le avec `archived` à `true`. Les produits qui le portent le gardent. Pour vider un champ texte, envoyez-le avec une chaîne vide.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant du fournisseur (champ `id`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom du fournisseur. De 3 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `commercial1` | texte | Premier contact commercial. 100 caractères au maximum. |
| `commercial2` | texte | Second contact commercial. 100 caractères au maximum. |
| `tel` | texte | Téléphone. 17 caractères au maximum. |
| `mobile` | texte | Mobile. 17 caractères au maximum. |
| `email` | texte | Adresse mail. 50 caractères au maximum. |
| `tva_intra` | texte | Numéro de TVA intracommunautaire. 32 caractères au maximum. |
| `notes` | texte | Notes libres. 5 000 caractères au maximum. |
| `adresse` | objet | Adresse du fournisseur. Seuls les champs envoyés changent. |
| `adresse.ligne1` | texte | Adresse, première ligne. 50 caractères au maximum. |
| `adresse.ligne2` | texte | Complément d'adresse. 50 caractères au maximum. |
| `adresse.cp` | texte | Code postal. 9 caractères au maximum. |
| `adresse.ville` | texte | Ville. 30 caractères au maximum. |
| `adresse.pays_code` | texte | Code du pays à deux lettres (voir `GET /v1/countries`). À la création, s'il est absent : le pays du magasin principal. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 200) : Le fournisseur après modification.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant du fournisseur. C'est la valeur de `fournisseur.id` dans un produit. |
| `data.name` | texte | Nom du fournisseur. |
| `data.commercial1` | texte | Nom du premier contact commercial. |
| `data.commercial2` | texte | Nom du second contact commercial. |
| `data.tel` | texte | Téléphone. |
| `data.mobile` | texte | Mobile. |
| `data.email` | texte | Adresse mail. |
| `data.tva_intra` | texte | Numéro de TVA intracommunautaire. |
| `data.notes` | texte | Notes libres du commerçant. |
| `data.archived` | booléen | `true` si le fournisseur est archivé : il n'est plus proposé dans l'application, mais les produits qui le portent le gardent. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `data.adresse` | objet | Adresse du fournisseur. |
| `data.adresse.ligne1` | texte | Adresse, première ligne. |
| `data.adresse.ligne2` | texte | Complément d'adresse. |
| `data.adresse.cp` | texte | Code postal. |
| `data.adresse.ville` | texte | Ville. |
| `data.adresse.id_pays` | entier | Identifiant du pays (voir `GET /v1/countries`). 0 si non renseigné. |
| `data.adresse.pays_code` | texte | Code du pays à deux lettres. |
| `data.adresse.pays` | texte | Nom du pays en français. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 7,
        "name": "Maison Verdier",
        "commercial1": "Julie Arnaud",
        "commercial2": "",
        "tel": "0472000000",
        "mobile": "",
        "email": "contact@maison-verdier.example",
        "tva_intra": "",
        "notes": "",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00",
        "adresse": {
            "ligne1": "4 quai des Tanneurs",
            "ligne2": "",
            "cp": "69009",
            "ville": "Lyon",
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France"
        }
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/suppliers/7" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"mobile":"0611223344","adresse":{"ville":"Villeurbanne","cp":"69100"}}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/collections

**Lister les collections**

Renvoie les collections du compte, par identifiant croissant. C'est ici que se traduit le `collec.id` d'un produit.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez l'adresse avec `after` égal à `meta.next_after`. Les éléments archivés ne sont renvoyés qu'avec `archived=true`.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `archived` | URL (?nom=valeur) | non | `true` pour inclure aussi les éléments archivés. `false` par défaut : seuls les éléments en service sont renvoyés. |

Réponse en cas de succès (statut 200) : Une page de collections.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Une page, par identifiant croissant. Liste vide s'il n'y a rien. |
| `data[].id` | entier | Identifiant de la collection. C'est la valeur de `collec.id` dans un produit. |
| `data[].name` | texte | Nom de la collection. |
| `data[].archived` | booléen | `true` si la collection est archivée. |
| `data[].date_creation` | texte | Date de création. |
| `data[].date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 3,
            "name": "Printemps 2027",
            "archived": false,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/collections" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/collections

**Créer une collection**

Crée une collection et la renvoie.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la collection. De 3 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 201) : La collection créée.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la collection. C'est la valeur de `collec.id` dans un produit. |
| `data.name` | texte | Nom de la collection. |
| `data.archived` | booléen | `true` si la collection est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 3,
        "name": "Printemps 2027",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/collections" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Printemps 2027"}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### PATCH /v1/collections/{id}

**Renommer ou archiver une collection**

Renomme ou archive une collection, et la renvoie après modification.

La modification est partielle : seuls les champs envoyés changent. Il n'existe pas de suppression : pour retirer un élément, archivez-le avec `archived` à `true`. Les produits qui le portent le gardent.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant de la collection (champ `id`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la collection. De 3 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 200) : La collection après modification.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la collection. C'est la valeur de `collec.id` dans un produit. |
| `data.name` | texte | Nom de la collection. |
| `data.archived` | booléen | `true` si la collection est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 3,
        "name": "Printemps 2027",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/collections/3" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Printemps-été 2027"}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/categories

**Lister les catégories**

Renvoie les catégories du compte, tous niveaux confondus, par identifiant croissant. Les catégories forment une arborescence de 5 niveaux au plus : chacune donne son parent (`id_parent`), son niveau et son chemin complet depuis la racine (`chemin`). Pour reconstruire l'arbre, parcourez toute la liste puis regroupez par `id_parent`.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez l'adresse avec `after` égal à `meta.next_after`. Les éléments archivés ne sont renvoyés qu'avec `archived=true`.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `archived` | URL (?nom=valeur) | non | `true` pour inclure aussi les éléments archivés. `false` par défaut : seuls les éléments en service sont renvoyés. |

Réponse en cas de succès (statut 200) : Une page de catégories.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Une page, par identifiant croissant. Liste vide s'il n'y a rien. |
| `data[].id` | entier | Identifiant de la catégorie. C'est la valeur de `categories[].id` dans un produit. |
| `data[].name` | texte | Nom de la catégorie. |
| `data[].id_parent` | entier | Identifiant de la catégorie parente. 0 pour une catégorie de premier niveau. |
| `data[].niveau` | entier | Niveau dans l'arborescence, de 1 (racine) à 5. |
| `data[].chemin` | liste de texte | Noms des catégories depuis la racine jusqu'à celle-ci, elle comprise. Exemple : `["Vêtements", "Homme", "Chemises"]`. |
| `data[].archived` | booléen | `true` si la catégorie est archivée. |
| `data[].date_creation` | texte | Date de création. |
| `data[].date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 12,
            "name": "Chemises",
            "id_parent": 5,
            "niveau": 3,
            "chemin": [
                "Vêtements",
                "Homme",
                "Chemises"
            ],
            "archived": false,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/categories" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/categories

**Créer une catégorie**

Crée une catégorie et la renvoie. Sans `id_parent`, elle est créée au premier niveau ; avec `id_parent`, elle devient une sous-catégorie de cette catégorie. L'arborescence est limitée à 5 niveaux, et on ne crée rien sous une catégorie archivée.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés. Pour une catégorie, le nom doit être unique parmi les catégories du même parent seulement.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la catégorie. De 2 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `id_parent` | entier | À la création seulement : identifiant de la catégorie parente. Absent ou 0 pour une catégorie de premier niveau. Le parent ne peut pas être changé ensuite. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 201) : La catégorie créée.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la catégorie. C'est la valeur de `categories[].id` dans un produit. |
| `data.name` | texte | Nom de la catégorie. |
| `data.id_parent` | entier | Identifiant de la catégorie parente. 0 pour une catégorie de premier niveau. |
| `data.niveau` | entier | Niveau dans l'arborescence, de 1 (racine) à 5. |
| `data.chemin` | liste de texte | Noms des catégories depuis la racine jusqu'à celle-ci, elle comprise. Exemple : `["Vêtements", "Homme", "Chemises"]`. |
| `data.archived` | booléen | `true` si la catégorie est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 12,
        "name": "Chemises",
        "id_parent": 5,
        "niveau": 3,
        "chemin": [
            "Vêtements",
            "Homme",
            "Chemises"
        ],
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/categories" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Chemises","id_parent":5}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### PATCH /v1/categories/{id}

**Renommer ou archiver une catégorie**

Renomme ou archive une catégorie, et la renvoie après modification. Une catégorie ne change pas de parent.

La modification est partielle : seuls les champs envoyés changent. Il n'existe pas de suppression : pour retirer un élément, archivez-le avec `archived` à `true`. Les produits qui le portent le gardent.

Une catégorie qui a des sous-catégories en service ne peut pas être archivée : archivez d'abord ses sous-catégories. À l'inverse, on ne remet pas en service une catégorie dont le parent est archivé.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `id` | chemin | oui | Identifiant de la catégorie (champ `id`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la catégorie. De 2 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `id_parent` | entier | À la création seulement : identifiant de la catégorie parente. Absent ou 0 pour une catégorie de premier niveau. Le parent ne peut pas être changé ensuite. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 200) : La catégorie après modification.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la catégorie. C'est la valeur de `categories[].id` dans un produit. |
| `data.name` | texte | Nom de la catégorie. |
| `data.id_parent` | entier | Identifiant de la catégorie parente. 0 pour une catégorie de premier niveau. |
| `data.niveau` | entier | Niveau dans l'arborescence, de 1 (racine) à 5. |
| `data.chemin` | liste de texte | Noms des catégories depuis la racine jusqu'à celle-ci, elle comprise. Exemple : `["Vêtements", "Homme", "Chemises"]`. |
| `data.archived` | booléen | `true` si la catégorie est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 12,
        "name": "Chemises",
        "id_parent": 5,
        "niveau": 3,
        "chemin": [
            "Vêtements",
            "Homme",
            "Chemises"
        ],
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/categories/12" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Chemises et polos"}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/custom-lists

**Lister les listes personnalisées**

Chaque compte dispose de trois listes personnalisées pour classer ses produits selon ses propres critères (une matière, une saison, un rayon). Cette adresse renvoie les trois, avec le nom que le commerçant leur a donné : appelez-la pour savoir ce que signifient `id_custom_list_1`, `id_custom_list_2` et `id_custom_list_3` dans un produit.

Les valeurs de chaque liste se lisent par `GET /v1/custom-lists/{list}/values`. Une liste dont `affiche` vaut `false` n'est pas utilisée par le commerçant. Le nom et l'affichage d'une liste se modifient par `PATCH /v1/custom-lists/{list}`.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Les trois listes personnalisées.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Les trois listes personnalisées, dans l'ordre. |
| `data[].id_list` | entier | Numéro de la liste : 1, 2 ou 3. À utiliser dans l'adresse `/v1/custom-lists/{list}/values`. |
| `data[].champ` | texte | Champ d'un produit qui porte une valeur de cette liste : `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3`. |
| `data[].libelle` | texte | Nom que le commerçant a donné à cette liste (exemples : « Matière », « Saison »). |
| `data[].affiche` | booléen | `true` si le commerçant utilise cette liste dans ses fiches produit. |
| `data[].nb_values` | entier | Nombre de valeurs en service dans la liste. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments renvoyés. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id_list": 1,
            "champ": "id_custom_list_1",
            "libelle": "Matière",
            "affiche": true,
            "nb_values": 8
        },
        {
            "id_list": 2,
            "champ": "id_custom_list_2",
            "libelle": "Customisé 2",
            "affiche": false,
            "nb_values": 0
        },
        {
            "id_list": 3,
            "champ": "id_custom_list_3",
            "libelle": "Customisé 3",
            "affiche": false,
            "nb_values": 0
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 3
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/custom-lists" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### PATCH /v1/custom-lists/{list}

**Renommer ou afficher une liste personnalisée**

Donne son nom à l'une des trois listes personnalisées, ou change son affichage dans les fiches produit, et la renvoie après modification.

C'est l'appel à faire pour mettre une liste en service : donnez-lui un `libelle` parlant (« Matière », « Saison ») et passez `affiche` à `true`, puis ajoutez ses valeurs par `POST /v1/custom-lists/{list}/values`. Avant de renommer une liste, lisez `GET /v1/custom-lists` : si elle porte déjà un nom choisi par le commerçant ou contient des valeurs, elle est utilisée, et la renommer changerait le sens de ce que portent ses produits.

La modification est partielle : seuls les champs envoyés changent. Il y a toujours exactement trois listes : on ne peut ni en créer ni en supprimer.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `list` | chemin | oui | Numéro de la liste personnalisée : 1, 2 ou 3 (voir `GET /v1/custom-lists`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `libelle` | texte | Nom de la liste, tel que le commerçant le verra dans ses fiches produit. De 1 à 50 caractères. |
| `affiche` | booléen | `true` pour que la liste apparaisse dans les fiches produit, `false` pour la masquer. Masquer une liste ne supprime ni ses valeurs ni ce que portent les produits. |

Réponse en cas de succès (statut 200) : La liste après modification.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id_list` | entier | Numéro de la liste : 1, 2 ou 3. À utiliser dans l'adresse `/v1/custom-lists/{list}/values`. |
| `data.champ` | texte | Champ d'un produit qui porte une valeur de cette liste : `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3`. |
| `data.libelle` | texte | Nom que le commerçant a donné à cette liste (exemples : « Matière », « Saison »). |
| `data.affiche` | booléen | `true` si le commerçant utilise cette liste dans ses fiches produit. |
| `data.nb_values` | entier | Nombre de valeurs en service dans la liste. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id_list": 1,
        "champ": "id_custom_list_1",
        "libelle": "Matière",
        "affiche": true,
        "nb_values": 0
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/custom-lists/1" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"libelle":"Matière","affiche":true}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/custom-lists/{list}/values

**Lister les valeurs d'une liste personnalisée**

Renvoie les valeurs d'une des trois listes personnalisées, par identifiant croissant. C'est ici que se traduit l'identifiant porté par `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3` dans un produit.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez l'adresse avec `after` égal à `meta.next_after`. Les éléments archivés ne sont renvoyés qu'avec `archived=true`.

- Clé d'API : requise. Permission : `read_products` (Lire les produits, fournisseurs, collections et catégories).
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `list` | chemin | oui | Numéro de la liste personnalisée : 1, 2 ou 3 (voir `GET /v1/custom-lists`). |
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |
| `archived` | URL (?nom=valeur) | non | `true` pour inclure aussi les éléments archivés. `false` par défaut : seuls les éléments en service sont renvoyés. |

Réponse en cas de succès (statut 200) : Une page de valeurs.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Une page, par identifiant croissant. Liste vide s'il n'y a rien. |
| `data[].id` | entier | Identifiant de la valeur. C'est ce que porte `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3` dans un produit. |
| `data[].id_list` | entier | Numéro de la liste à laquelle la valeur appartient : 1, 2 ou 3. |
| `data[].name` | texte | Libellé de la valeur. |
| `data[].archived` | booléen | `true` si la valeur est archivée. |
| `data[].date_creation` | texte | Date de création. |
| `data[].date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 4,
            "id_list": 1,
            "name": "Coton bio",
            "archived": false,
            "date_creation": "2026-03-14T10:22:00+01:00",
            "date_update": "2026-10-02T16:05:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/custom-lists/1/values" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### POST /v1/custom-lists/{list}/values

**Ajouter une valeur à une liste personnalisée**

Ajoute une valeur à l'une des trois listes personnalisées et la renvoie.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés. Le nom doit être unique dans la liste concernée.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `list` | chemin | oui | Numéro de la liste personnalisée : 1, 2 ou 3 (voir `GET /v1/custom-lists`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la valeur. De 2 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 201) : La valeur créée.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la valeur. C'est ce que porte `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3` dans un produit. |
| `data.id_list` | entier | Numéro de la liste à laquelle la valeur appartient : 1, 2 ou 3. |
| `data.name` | texte | Libellé de la valeur. |
| `data.archived` | booléen | `true` si la valeur est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 4,
        "id_list": 1,
        "name": "Coton bio",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X POST "https://api.wanapos.com/v1/custom-lists/1/values" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"name":"Coton bio"}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### PATCH /v1/custom-lists/{list}/values/{id}

**Renommer ou archiver une valeur de liste**

Renomme ou archive une valeur d'une liste personnalisée, et la renvoie après modification. La valeur doit appartenir à la liste donnée dans l'adresse, sinon elle est introuvable.

La modification est partielle : seuls les champs envoyés changent. Il n'existe pas de suppression : pour retirer un élément, archivez-le avec `archived` à `true`. Les produits qui le portent le gardent.

Un nom déjà pris est refusé avec l'erreur `duplicate_name`, qui donne l'identifiant existant : réutilisez-le plutôt que de créer un doublon. La comparaison ne tient compte ni des majuscules, ni des accents, ni des espaces autour, et inclut les éléments archivés.

- Clé d'API : requise. Permission : `write_products` (Créer des produits ; créer et modifier fournisseurs, collections et catégories).
- Quota : compte comme une écriture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `list` | chemin | oui | Numéro de la liste personnalisée : 1, 2 ou 3 (voir `GET /v1/custom-lists`). |
| `id` | chemin | oui | Identifiant de la valeur (champ `id`). |
| `dry_run` | URL (?nom=valeur) | non | `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é. |
| `Idempotency-Key` | en-tête | non | 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 |
|---|---|---|
| `name` | texte | Nom de la valeur. De 2 à 50 caractères. Un nom déjà pris est refusé (`duplicate_name`), sans tenir compte des majuscules ni des accents. |
| `archived` | booléen | À la modification seulement : `true` pour archiver, `false` pour remettre en service. |

Réponse en cas de succès (statut 200) : La valeur après modification.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.id` | entier | Identifiant de la valeur. C'est ce que porte `id_custom_list_1`, `id_custom_list_2` ou `id_custom_list_3` dans un produit. |
| `data.id_list` | entier | Numéro de la liste à laquelle la valeur appartient : 1, 2 ou 3. |
| `data.name` | texte | Libellé de la valeur. |
| `data.archived` | booléen | `true` si la valeur est archivée. |
| `data.date_creation` | texte | Date de création. |
| `data.date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "id": 4,
        "id_list": 1,
        "name": "Coton bio",
        "archived": false,
        "date_creation": "2026-03-14T10:22:00+01:00",
        "date_update": "2026-10-02T16:05:00+02:00"
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl -X PATCH "https://api.wanapos.com/v1/custom-lists/1/values/4" -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" -d '{"archived":true}'
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 404 : L'élément demandé n'existe pas sur ce compte. Code : `resource_not_found`.
- Statut 409 : Ce nom est déjà porté par un autre élément du même classement. Code : `duplicate_name`. Le message et l'indication donnent l'identifiant existant. Rien n'a été enregistré.
- Statut 422 : Données envoyées invalides. Code : `validation_failed`. Le champ `details` liste chaque erreur.
- Statut 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.
- Statut 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`.

### GET /v1/shops

**Lister les magasins et leurs points de caisse**

Renvoie tous les magasins du compte avec leur adresse, leur téléphone, leur taux de TVA par défaut et leurs points de caisse. Toute clé valide peut l'appeler.

C'est ici que se traduisent les identifiants `id_shop` et `id_point_caisse` rencontrés ailleurs (lignes de vente, prix d'un produit par magasin, magasin d'origine d'un client). Les magasins archivés sont listés aussi, en fin de liste, pour que d'anciennes ventes restent lisibles : testez `archived` et `actif` avant de considérer qu'un magasin est en service.

La liste est courte et renvoyée en une seule fois, sans paramètre. `GET /v1/me` donne une version réduite de cette liste, limitée aux magasins non archivés.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Les magasins du compte.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Magasins du compte : d'abord ceux en service, puis les magasins archivés. |
| `data[].id` | entier | Identifiant du magasin. C'est la valeur des champs `id_shop` rencontrés ailleurs dans l'API. |
| `data[].name` | texte | Nom du magasin. |
| `data[].tel` | texte | Téléphone du magasin. Chaîne vide si non renseigné. |
| `data[].tva_taux` | nombre | Taux de TVA par défaut du magasin, en pourcentage (exemple : 20). Un produit sans taux propre prend celui-ci. |
| `data[].actif` | booléen | `true` si le magasin est en service. |
| `data[].archived` | booléen | `true` si le magasin a été archivé par le commerçant. Il reste listé pour que ses anciennes ventes restent lisibles. |
| `data[].date_creation` | texte | Date de création du magasin. |
| `data[].adresse` | objet | Adresse du magasin. |
| `data[].adresse.ligne1` | texte | Adresse, première ligne. |
| `data[].adresse.ligne2` | texte | Complément d'adresse. |
| `data[].adresse.cp` | texte | Code postal. |
| `data[].adresse.ville` | texte | Ville. |
| `data[].adresse.id_pays` | entier | Identifiant du pays (voir `GET /v1/countries`). 0 si non renseigné. |
| `data[].adresse.pays_code` | texte | Code du pays à deux lettres (exemple : `FR`). Chaîne vide si non renseigné. |
| `data[].adresse.pays` | texte | Nom du pays en français. |
| `data[].points_caisse` | liste | Points de caisse du magasin. Liste vide s'il n'en a aucun. |
| `data[].points_caisse[].id` | entier | Identifiant du point de caisse. C'est la valeur des champs `id_point_caisse` rencontrés ailleurs dans l'API. |
| `data[].points_caisse[].name` | texte | Nom du point de caisse. |
| `data[].points_caisse[].actif` | booléen | `true` si le point de caisse est en service. |
| `data[].points_caisse[].date_creation` | texte | Date de création du point de caisse. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments renvoyés. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 1,
            "name": "Magasin principal",
            "tel": "0102030405",
            "tva_taux": 20,
            "actif": true,
            "archived": false,
            "date_creation": "2025-03-12T10:04:11+01:00",
            "adresse": {
                "ligne1": "12 rue des Lilas",
                "ligne2": "",
                "cp": "69002",
                "ville": "Lyon",
                "id_pays": 63,
                "pays_code": "FR",
                "pays": "France"
            },
            "points_caisse": [
                {
                    "id": 1,
                    "name": "Point de caisse 1",
                    "actif": true,
                    "date_creation": "2025-03-12T10:04:11+01:00"
                }
            ]
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/shops" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/users

**Lister les utilisateurs du compte**

Renvoie les utilisateurs du compte, c'est-à-dire les personnes qui se connectent à l'application : leur identifiant, le nom qu'elles se sont donné, leur profil et leur point de caisse principal. Permission requise : `read_users`.

L'adresse mail d'un utilisateur n'est jamais renvoyée, pas plus qu'aucune donnée de connexion. `alias` est souvent vide pour le titulaire du compte : utilisez `titulaire` pour le reconnaître.

Le profil indique le rôle de l'utilisateur. Le détail de ce qu'un profil autorise n'est pas encore disponible par l'API. Les utilisateurs archivés sont listés aussi, en fin de liste.

La liste est courte et renvoyée en une seule fois, sans paramètre.

- Clé d'API : requise. Permission : `read_users` (Lire les utilisateurs du compte (nom et profil)).
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Les utilisateurs du compte.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Utilisateurs du compte : d'abord ceux en service, puis les utilisateurs archivés. |
| `data[].id` | entier | Identifiant de l'utilisateur. |
| `data[].alias` | texte | Nom que l'utilisateur s'est donné dans l'application. Souvent vide pour le titulaire du compte. |
| `data[].titulaire` | booléen | `true` pour le titulaire du compte, la personne qui l'a créé. Il y en a un seul. |
| `data[].id_profil` | entier | Identifiant du profil de l'utilisateur. |
| `data[].profil` | texte | Nom du profil. Les trois profils d'origine s'appellent `admin`, `responsable` et `vendeur`. |
| `data[].profil_personnalise` | booléen | `true` si le profil a été créé par le commerçant, `false` pour l'un des trois profils d'origine. |
| `data[].id_point_caisse_principal` | entier | Identifiant du point de caisse sur lequel l'utilisateur travaille par défaut (voir `GET /v1/shops`). |
| `data[].archived` | booléen | `true` si l'utilisateur a été archivé : il ne peut plus se connecter, mais reste listé. |
| `data[].date_creation` | texte | Date de création de l'utilisateur. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments renvoyés. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 2137,
            "alias": "",
            "titulaire": true,
            "id_profil": 1,
            "profil": "admin",
            "profil_personnalise": false,
            "id_point_caisse_principal": 1,
            "archived": false,
            "date_creation": "2025-03-12T10:04:11+01:00"
        },
        {
            "id": 2201,
            "alias": "Camille",
            "titulaire": false,
            "id_profil": 3,
            "profil": "vendeur",
            "profil_personnalise": false,
            "id_point_caisse_principal": 1,
            "archived": false,
            "date_creation": "2025-06-02T09:30:00+02:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 2
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/users" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/payment-methods

**Lister les moyens de paiement**

Renvoie les moyens de paiement du compte : ceux d'origine (espèces, carte bancaire, chèque, avoir, crédit) et ceux que le commerçant a créés. Toute clé valide peut l'appeler.

`actif` dit si le moyen de paiement est proposé au moment d'encaisser. Les moyens archivés sont listés aussi, en fin de liste.

La liste est courte et renvoyée en une seule fois, sans paramètre.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Les moyens de paiement du compte.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Moyens de paiement du compte, dans l'ordre d'affichage, archivés en fin de liste. |
| `data[].id` | entier | Identifiant du moyen de paiement. |
| `data[].name` | texte | Nom du moyen de paiement. |
| `data[].actif` | booléen | `true` si le moyen de paiement est proposé au moment d'encaisser. |
| `data[].is_default` | booléen | `true` pour un moyen de paiement d'origine (espèces, carte bancaire, chèque, avoir, crédit), `false` pour un moyen créé par le commerçant. |
| `data[].position` | entier | Ordre d'affichage dans l'application. |
| `data[].archived` | booléen | `true` si le moyen de paiement a été archivé par le commerçant. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments renvoyés. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 1,
            "name": "Espèces",
            "actif": true,
            "is_default": true,
            "position": 1,
            "archived": false
        },
        {
            "id": 2,
            "name": "Carte bancaire",
            "actif": true,
            "is_default": true,
            "position": 2,
            "archived": false
        },
        {
            "id": 6,
            "name": "Virement",
            "actif": true,
            "is_default": false,
            "position": 6,
            "archived": false
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 3
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/payment-methods" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/promotions

**Lister les promotions**

Renvoie les promotions du compte, archivées comprises, par identifiant croissant. Toute clé valide peut l'appeler.

C'est ici que se traduit l'`id_promotion` d'une ligne de vente. Une promotion est soit une remise en pourcentage (`mode` = `pc`), soit un prix fixe (`mode` = `pf`). Elle s'applique entre `start` et `end`, dans les magasins de `id_shops`. La liste des produits rattachés à une promotion n'est pas renvoyée.

Le parcours se fait par curseur : tant que `meta.has_more` vaut `true`, rappelez l'adresse avec `after` égal à `meta.next_after`.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Paramètres :

| Nom | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `limit` | URL (?nom=valeur) | non | Nombre d'éléments par page, de 1 à 100. 50 par défaut. |
| `after` | URL (?nom=valeur) | non | Curseur de parcours : ne renvoie que les éléments dont l'identifiant est supérieur. Absent ou 0 pour la première page, puis la valeur `next_after` de la réponse précédente. |

Réponse en cas de succès (statut 200) : Une page de promotions.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Promotions, par identifiant croissant. Liste vide si le compte n'en a aucune. |
| `data[].id` | entier | Identifiant de la promotion. C'est la valeur du champ `id_promotion` d'une ligne de vente. |
| `data[].name` | texte | Nom de la promotion. |
| `data[].mode` | texte | `pc` : remise en pourcentage (voir `remise_pc` et `arrondi`). `pf` : prix fixe (voir `prix`). |
| `data[].start` | texte | Premier jour de la promotion, au format `2026-11-01`. Chaîne vide si non renseigné. |
| `data[].end` | texte | Dernier jour de la promotion. Chaîne vide si non renseigné. |
| `data[].remise_pc` | nombre | Pourcentage de remise, en mode `pc`. 0 en mode `pf`. |
| `data[].arrondi` | texte | Arrondi appliqué au prix remisé, en mode `pc` : `sans`, `entier_sup` (à l'entier supérieur) ou `entier_inf` (à l'entier inférieur). `sans` en mode `pf`. |
| `data[].prix` | nombre | Prix de vente pendant la promotion, en mode `pf`. 0 en mode `pc`. |
| `data[].apply_impact_pv` | booléen | En mode `pf` : `true` si l'écart de prix propre à une variante s'ajoute au prix fixe. |
| `data[].apply_impact_shop` | booléen | En mode `pf` : `true` si l'écart de prix propre à un magasin s'ajoute au prix fixe. |
| `data[].id_shops` | liste de entier | Identifiants des magasins rattachés à la promotion. |
| `data[].archived` | booléen | `true` si la promotion a été archivée par le commerçant. |
| `data[].date_creation` | texte | Date de création de la promotion. |
| `data[].date_update` | texte | Date de la dernière modification. Chaîne vide si inconnue. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments dans cette page. |
| `meta.has_more` | booléen | `true` s'il reste une page à lire. |
| `meta.next_after` | entier | Valeur à passer dans `after` pour la page suivante. 0 quand le parcours est terminé. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id": 14,
            "name": "Soldes d'hiver",
            "mode": "pc",
            "start": "2027-01-06",
            "end": "2027-02-02",
            "remise_pc": 30,
            "arrondi": "entier_inf",
            "prix": 0,
            "apply_impact_pv": false,
            "apply_impact_shop": false,
            "id_shops": [
                1,
                2
            ],
            "archived": false,
            "date_creation": "2026-12-18T16:20:05+01:00",
            "date_update": "2026-12-19T09:02:40+01:00"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 1,
        "has_more": false,
        "next_after": 0
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/promotions" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/customer-fields

**Lire la définition des champs de la fiche client**

Renvoie la liste des champs d'un client, avec le libellé que le commerçant voit dans ses écrans, et les valeurs acceptées pour la civilité. Toute clé valide peut l'appeler.

Appelez cette adresse avant de créer ou de modifier des clients. Chaque compte dispose de neuf champs personnalisés (`libre_1` à `libre_3`, `custom_io_1` à `custom_io_3`, `custom_date_1` à `custom_date_3`) dont le sens est propre au commerçant : `libelle` dit ce qu'il y range. Un champ dont `affiche` vaut `false` n'est pas utilisé dans ses écrans : évitez de le remplir sans raison, même si l'API l'accepte.

`champ` reprend exactement le nom du champ dans un client, avec un point pour un champ de l'adresse (`adresse.cp`).

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : La définition des champs de la fiche client.

| Champ | Type | Description |
|---|---|---|
| `data` | objet |  |
| `data.civilites` | liste de texte | Valeurs acceptées pour le champ `civilite` d'un client. La chaîne vide signifie « aucune civilité ». |
| `data.champs` | liste | Champs de la fiche client. |
| `data.champs[].champ` | texte | Nom du champ tel qu'il apparaît dans un client (exemples : `nom`, `adresse.cp`, `libre_1`). |
| `data.champs[].libelle` | texte | Libellé que le commerçant voit dans ses écrans. Pour un champ personnalisé, c'est le nom qu'il lui a donné. |
| `data.champs[].type` | texte | Nature de la valeur : `texte`, `nombre`, `oui_non`, `date` ou `liste` (valeur à choisir dans une liste fermée). |
| `data.champs[].affiche` | booléen | `true` si le commerçant utilise ce champ dans ses écrans. Un champ non affiché reste lisible et modifiable par l'API. |
| `data.champs[].personnalise` | booléen | `true` pour l'un des neuf champs personnalisés, dont le sens dépend du commerçant. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |

Exemple de réponse :

```json
{
    "data": {
        "civilites": [
            "",
            "M.",
            "Mme",
            "Mlle",
            "Sct"
        ],
        "champs": [
            {
                "champ": "nom",
                "libelle": "Nom",
                "type": "texte",
                "affiche": true,
                "personnalise": false
            },
            {
                "champ": "adresse.cp",
                "libelle": "CP",
                "type": "texte",
                "affiche": true,
                "personnalise": false
            },
            {
                "champ": "libre_1",
                "libelle": "Pointure",
                "type": "texte",
                "affiche": true,
                "personnalise": true
            },
            {
                "champ": "custom_date_1",
                "libelle": "Date d'anniversaire",
                "type": "date",
                "affiche": true,
                "personnalise": true
            }
        ]
    },
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61"
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/customer-fields" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/countries

**Lister les pays**

Renvoie la liste des pays connus de Wanapos, par ordre alphabétique. Elle est la même pour tous les comptes. Toute clé valide peut l'appeler.

`pays_code` est la valeur à donner dans `adresse.pays_code` pour créer ou modifier un client. La liste compte environ deux cents lignes et est renvoyée en une seule fois, sans paramètre : inutile de la relire à chaque appel.

- Clé d'API : requise. Permission : aucune en particulier, toute clé valide convient.
- Quota : compte comme une lecture.

Réponse en cas de succès (statut 200) : Les pays.

| Champ | Type | Description |
|---|---|---|
| `data` | liste | Pays, par ordre alphabétique. |
| `data[].id_pays` | entier | Identifiant du pays. |
| `data[].pays_code` | texte | Code du pays à deux lettres. C'est la valeur à donner dans `adresse.pays_code` pour créer ou modifier un client. |
| `data[].pays` | texte | Nom du pays en français. |
| `meta` | objet |  |
| `meta.request_id` | texte | Identifiant de l'appel. |
| `meta.count` | entier | Nombre d'éléments renvoyés. |

Exemple de réponse :

```json
{
    "data": [
        {
            "id_pays": 20,
            "pays_code": "BE",
            "pays": "Belgique"
        },
        {
            "id_pays": 63,
            "pays_code": "FR",
            "pays": "France"
        }
    ],
    "meta": {
        "request_id": "3f9a1c0b7d2e4a61",
        "count": 2
    }
}
```

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/countries" -H "Authorization: Bearer VOTRE_CLE"
```

Erreurs possibles :

- Statut 401 : Clé absente, inconnue ou révoquée. Codes : `missing_key`, `invalid_key`.
- Statut 403 : Appel refusé pour ce compte ou cette clé. Codes : `api_not_activated`, `account_not_eligible`, `access_blocked`, `missing_scope`.
- Statut 422 : Un paramètre est absent, inconnu ou invalide. Code : `invalid_parameter`. Le champ `field` nomme le paramètre.
- Statut 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.

### GET /v1/openapi.json

**Description technique de l'API (OpenAPI 3)**

Renvoie ce document. Adresse ouverte sans clé : elle ne contient aucune donnée de compte. Le document est renvoyé tel quel, sans l'enveloppe `data`.

- Clé d'API : non requise.

Réponse en cas de succès (statut 200) : Le document OpenAPI.

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/openapi.json"
```

### GET /v1/documentation.md

**Documentation complète en texte brut (Markdown)**

Renvoie toute la documentation de l'API en Markdown, générée à partir de la description technique. Adresse ouverte sans clé. C'est le document à transmettre à un assistant IA pour qu'il sache utiliser l'API.

- Clé d'API : non requise.

Réponse en cas de succès (statut 200) : La documentation en Markdown.

Exemple d'appel :

```bash
curl "https://api.wanapos.com/v1/documentation.md"
```

## Toutes les erreurs

Une erreur a toujours cette forme : `{"error": {"code", "message", "hint", "field", "details", "request_id"}}`. Le champ `code` est stable : c'est lui qu'un programme doit tester. Le champ `hint` dit comment corriger.

| Code | Statut HTTP | Signification |
|---|---|---|
| `not_found` | 404 | L'adresse appelée n'existe pas. |
| `method_not_allowed` | 405 | L'adresse existe, mais pas avec cette méthode HTTP. L'en-tête Allow liste les méthodes acceptées. |
| `resource_not_found` | 404 | L'élément demandé n'existe pas sur le compte lié à la clé. |
| `https_required` | 400 | L'appel a été fait en HTTP simple. Seul HTTPS est accepté. |
| `key_in_url` | 400 | Une clé a été placée dans l'URL. Elle doit être envoyée dans l'en-tête Authorization, et la clé exposée doit être révoquée. |
| `api_disabled` | 503 | L'API est momentanément indisponible. Réessayer plus tard. |
| `too_many_failed_attempts` | 429 | Trop d'appels avec une clé invalide depuis la même adresse IP. Attendre le délai indiqué par Retry-After. |
| `missing_key` | 401 | Aucune clé n'a été fournie. |
| `invalid_key` | 401 | La clé est inconnue ou a été révoquée. |
| `api_not_activated` | 403 | L'API n'est pas activée sur le compte. Le titulaire l'active dans son compte Wanapos. |
| `account_not_eligible` | 403 | Le compte n'a pas d'abonnement actif. |
| `access_blocked` | 403 | L'accès à l'API est suspendu sur ce compte. |
| `missing_scope` | 403 | La clé n'a pas la permission exigée. Le champ field nomme la permission manquante. |
| `rate_limited` | 429 | Trop d'appels dans la minute. Attendre le délai indiqué par Retry-After, puis espacer les appels. |
| `daily_quota_exceeded` | 429 | Le quota journalier de lecture ou d'écriture est atteint. Il revient à zéro à minuit, heure de Paris. |
| `body_too_large` | 413 | Le contenu envoyé dépasse la taille maximale. Découper l'envoi en plusieurs appels. |
| `unsupported_media_type` | 415 | Le contenu envoyé n'est pas déclaré comme du JSON. |
| `invalid_json` | 400 | Le contenu envoyé n'est pas un objet JSON valide. |
| `validation_failed` | 422 | Des données envoyées sont invalides. Le champ details liste chaque erreur avec son champ. Rien n'a été enregistré. |
| `invalid_parameter` | 422 | Un paramètre de l'URL est invalide. Le champ field le nomme. |
| `idempotency_key_required` | 400 | Cet appel exige l'en-tête Idempotency-Key. |
| `idempotency_key_invalid` | 400 | L'en-tête Idempotency-Key n'a pas la forme attendue (8 à 100 caractères : lettres, chiffres, tiret, tiret bas, point, deux-points). |
| `idempotency_key_reused` | 422 | Cet Idempotency-Key a déjà servi pour une requête différente. Utiliser un nouvel identifiant par nouvelle requête. |
| `request_in_progress` | 409 | Une requête portant le même Idempotency-Key est en cours de traitement. Réessayer dans quelques secondes avec le même identifiant. |
| `account_busy` | 503 | Une autre écriture est en cours sur ce compte. Rien n'a été enregistré : renvoyer la même requête après quelques secondes. |
| `duplicate_email` | 409 | Un client actif porte déjà cette adresse mail. L'erreur donne les identifiants existants : modifier le client existant, ou renvoyer avec `?allow_duplicate_email=true`. |
| `duplicate_barcode` | 409 | Un autre produit porte déjà ce code-barres externe (`bc_ext`). L'erreur donne les identifiants des produits concernés : vérifier que le produit n'existe pas déjà, ou renvoyer avec `?allow_duplicate_bc_ext=true`. |
| `duplicate_name` | 409 | Un fournisseur, une collection, une catégorie ou une valeur de liste porte déjà ce nom. L'erreur donne l'identifiant existant : l'utiliser au lieu de créer un doublon, ou choisir un autre nom. |
| `points_out_of_range` | 409 | L'ajustement ferait passer le solde de points sous 0 ou au-dessus du maximum. Le message donne le solde actuel. Rien n'a été modifié. |
| `internal_error` | 500 | Erreur interne. Réessayer, puis contacter l'assistance en indiquant le request_id. |
