Aller au contenu principal

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_purchasedUne commande a été enregistrée et a généré des points (achat, missions accomplies sur la commande, etc.)
manual_attributionUn opérateur a crédité manuellement des points au consommateur depuis le back-office

Les points gagnés grâce à une mission accomplie lors d'une commande sont inclus dans l'événement order_purchased de cette commande : ils ne font pas l'objet d'un envoi distinct.

info

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.

attention

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​

ChampTypeDescription
eventstringToujours "points_event/created"
customerIdnumberIdentifiant externe du consommateur (correspond à l'ID dans votre plateforme e-commerce)
pointsnumber | nullNombre de points crédités par cet événement. null si le montant n'a pas pu être déterminé
balancenumberSolde de points du consommateur après l'opération
reasonstringOrigine du crédit : order_purchased ou manual_attribution
orderIdnumber | nullIdentifiant externe de la commande à l'origine des points. null hors contexte de commande
missionReferencestring | nullRéférence de la mission à l'origine des points, le cas échéant. null sinon
info

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 :

  • event vaut points_event/deducted
  • points porte le montant retiré, en négatif (ex : -120)
  • balance est 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/changed est 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).