Gain de points (points_event/created)
Enkore envoie un webhook à chaque fois qu'un consommateur gagne des points. Ce document décrit le payload de cet événement et ses déclencheurs.
Les headers, la signature HMAC et la politique de réessai sont communs à tous les webhooks et sont décrits dans Livraison et signature des webhooks.
Déclencheurs
Le webhook points_event/created est émis dans les situations suivantes :
Raison (reason) | Déclencheur |
|---|---|
order_purchased | Une commande a été enregistrée et a généré des points |
manual_attribution | Un opérateur a crédité manuellement des points au consommateur depuis le back-office |
Les points d'une mission accomplie — y compris lors d'une commande — ne sont pas comptés dans
points : ils sont annoncés par le webhook mission/accomplished,
auquel il faut s'abonner séparément. Seul balance, recalculé au moment de l'envoi, peut déjà les
inclure.
Si le calcul aboutit à 0 point pour la commande, aucun webhook n'est envoyé. Une commande peut donc être transmise à Enkore sans qu'aucun événement ne vous parvienne.
De nouvelles origines de points pourront être ajoutées à l'avenir. Traitez reason comme une
chaîne ouverte : ignorez sans erreur une valeur que vous ne connaissez pas, plutôt que de rejeter
la requête.
Format du payload
Enkore envoie une requête POST en application/json vers l'URL configurée dans le back-office.
Exemple de payload — points gagnés sur une commande
{
"event": "points_event/created",
"customerId": 42,
"points": 120,
"balance": 1370,
"reason": "order_purchased",
"orderId": 10528,
"missionReference": null
}
Exemple de payload — attribution manuelle
Une attribution manuelle n'est rattachée à aucune commande : orderId est null.
{
"event": "points_event/created",
"customerId": 42,
"points": 500,
"balance": 1870,
"reason": "manual_attribution",
"orderId": null,
"missionReference": null
}
Description des champs
| Champ | Type | Description |
|---|---|---|
event | string | Toujours "points_event/created" |
customerId | number | Identifiant externe du consommateur (correspond à l'ID dans votre plateforme e-commerce) |
points | number | null | Nombre de points crédités par cet événement. null si le montant n'a pas pu être déterminé |
balance | number | Solde de points du consommateur après l'opération |
reason | string | Origine du crédit : order_purchased ou manual_attribution |
orderId | number | null | Identifiant externe de la commande à l'origine des points. null hors contexte de commande |
missionReference | string | null | Toujours null : conservé pour compatibilité, les points de mission étant annoncés par mission/accomplished |
points est le delta de l'événement, balance le solde courant recalculé au moment de
l'envoi. Ces deux valeurs peuvent diverger d'un simple ancien solde + points si d'autres
opérations (dépense de points, expiration, déduction) ont eu lieu entre-temps. Pour afficher un
solde, utilisez balance.
Événement associé : déduction de points
La contrepartie du gain est l'événement points_event/deducted, émis lors d'une annulation ou
d'un remboursement de commande. Il utilise exactement la même structure de payload, avec deux
particularités :
eventvautpoints_event/deductedpointsporte le montant retiré, en négatif (ex :-120)balanceest le solde net courant, qui peut être négatif si les points avaient déjà été dépensés
{
"event": "points_event/deducted",
"customerId": 42,
"points": -120,
"balance": 1250,
"reason": "order_refunded",
"orderId": 10528,
"missionReference": null
}
Valeurs possibles de reason : order_refunded, order_cancelled, mission_revoked,
referral_revoked.
Il s'agit d'un type d'événement distinct : pour le recevoir, un webhook dédié doit être configuré
sur points_event/deducted, et le header X-Enkore-Event vaudra points_event/deducted.
Points d'attention côté réception
- L'envoi est asynchrone et intervient peu après l'enregistrement de la commande : ne présumez pas d'un ordre d'arrivée strict entre ce webhook et vos autres flux.
- Un gain de points peut entraîner un changement de palier. Le webhook
tier/changedest alors envoyé séparément, juste après celui-ci. - Rendez le traitement idempotent : un même événement peut être livré plusieurs fois (voir la section déduplication de la page commune).