Clients

Créer un client

POST /v1/customers
vpn_key Permission write_customers Compte comme une écriture

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.

Paramètres

dry_run Facultatif true pour tout vérifier sans rien enregistrer : la réponse est celle que vous auriez obtenue, avec meta.dry_run à true. L'identifiant renvoyé n'est alors pas réservé.
allow_duplicate_email Facultatif 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 Facultatif Identifiant unique de votre choix (8 à 100 caractères). Si vous renvoyez la même requête avec le même identifiant, elle n'est pas exécutée deux fois : vous recevez la réponse d'origine. Recommandé pour toute création.

Corps JSON à envoyer

Champ Type Description
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.

Exemple d'appel

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"}}'

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. Voir tous les champs
meta objet
meta.request_id texte Identifiant de l'appel, à communiquer à l'assistance en cas de problème.
{
    "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"
    }
}

Erreurs possibles

  • 401 Clé absente, inconnue ou révoquée. Codes : missing_key, invalid_key.
  • 403 Appel refusé pour ce compte ou cette clé. Codes : api_not_activated, account_not_eligible, access_blocked, missing_scope.
  • 409 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é.
  • 422 Données envoyées invalides. Code : validation_failed. Le champ details liste chaque erreur.
  • 429 Quota dépassé. Codes : rate_limited, daily_quota_exceeded, too_many_failed_attempts. L'en-tête Retry-After indique combien de secondes attendre.
  • 503 Une autre écriture est en cours sur ce compte. Code : account_busy. Renvoyer la même requête après le délai de l'en-tête Retry-After.

Voir toutes les erreurs

Une question ? contact@wanapos.com