Ajouter ou retirer des points de fidélité à un client
/v1/customers/{id}/loyalty-points
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.
Paramètres
id |
Obligatoire | Identifiant du client (champ id). |
Idempotency-Key |
Obligatoire | Obligatoire. Identifiant unique de votre choix (8 à 100 caractères), nouveau pour chaque ajustement. |
dry_run |
Facultatif | 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. |
Exemple d'appel
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"}'
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. |
{
"data": {
"id_client": 1842,
"ajustement": 50,
"points_avant": 120,
"points_actuels": 170,
"motif": "Parrainage"
},
"meta": {
"request_id": "3f9a1c0b7d2e4a61"
}
}
Erreurs possibles
-
400
L'en-tête
Idempotency-Keyest absent ou mal formé. Codes :idempotency_key_required,idempotency_key_invalid,invalid_json. -
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. -
404
L'élément demandé n'existe pas sur ce compte. Code :
resource_not_found. -
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é. -
422
Données envoyées invalides. Code :
validation_failed. Le champdetailsliste chaque erreur. -
429
Quota dépassé. Codes :
rate_limited,daily_quota_exceeded,too_many_failed_attempts. L'en-têteRetry-Afterindique combien de secondes attendre.
Une question ? contact@wanapos.com
