Installez l’application Vivoldi sur Google Play pour que ce soit encore plus pratique.

API d’utilisation des récompenses de tampons (v2)

L’API d’utilisation des récompenses de tampons marque une récompense (boisson gratuite, réduction, etc.) comme utilisée une fois tous les tampons complétés.

Après utilisation, le tampon ne peut plus être utilisé, et un nouveau doit être émis pour démarrer un nouveau cycle.
Elle est utilisée dans les systèmes de récompense basés sur les visites ou les achats.

Cette API est disponible à partir de l’offre Personal.

PUT

/api/stamp/v2/redeem 

{
    "stampIdx": 394,
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
onsiteToken string
Jeton d'échange de courte durée. v2 n'accepte pas le mot de passe en clair (onsitePwd).
Lorsque la ressource a onsiteYn = Y, envoyez tel quel l'onsiteToken renvoyé par l'API de vérification.
Idempotency-Key est obligatoire pour les requêtes utilisant un jeton. Une nouvelle tentative avec la même clé rejoue le résultat initial ; réutiliser le même jeton avec une autre clé est refusé avec 400 (code d'erreur 1228).
Si un magasin de traitement a été indiqué lors de la vérification, cette requête doit utiliser le même.
processStoreIdx integer
IDX du magasin où cette requête est réellement traitée. S'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique de traitement.
L'agence de traitement n'est pas reçue dans la requête ; le serveur la déduit de ce magasin. Cette valeur diffère du magasin émetteur (storeIdx). 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Code de réponse : 0 = Succès, autres valeurs = Erreur
message string
Message de réponse. Si le code n’est pas 0, un message d’erreur est renvoyé.
result null

Validation des paramètres numériques

Si un paramètre numérique reçoit une valeur non numérique ou un nombre dépassant la plage que le serveur peut traiter, la requête est immédiatement refusée avec 400 (code d'erreur 653).

Dans ce cas, les données du tampon et l'historique de cumul ne changent pas du tout, et aucun enregistrement d'événement ni envoi de Webhook n'est produit. Une réponse en échec signifie que rien n'a été enregistré.

Indiquer le magasin de traitement

Paramètre Signification Description
processStoreIdx Magasin de traitement Le magasin où cette requête est réellement traitée. Facultatif : s'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique.

L'agence de traitement n'est pas reçue dans la requête. Le serveur la déduit du magasin indiqué et l'enregistre.

Si la portée d'utilisation est BRANCH, le traitement n'a lieu que si l'agence du magasin vérifié correspond à l'agence d'utilisation, ou si vous vous authentifiez avec le mot de passe sur place de cette agence. Sans l'un ou l'autre, la requête est refusée.

Paramètres non utilisables — branchIdx (agence émettrice), storeIdx (magasin émetteur), useScope (portée d'utilisation) et useBranchIdx (agence d'utilisation) relèvent de la politique d'émission déjà enregistrée et ne peuvent pas être modifiés via cette API. S'ils sont envoyés, la réponse est 400 (code d'erreur 1227).

Idempotency-Key

Pour réessayer en toute sécurité lorsqu'une réponse est perdue à cause d'une erreur réseau, envoyez une valeur unique par requête dans l'en-tête Idempotency-Key. Vous pouvez aussi l'envoyer via requestId dans le corps ; si les deux sont envoyés avec des valeurs différentes, la requête est refusée. Le format autorisé est de 8 à 64 caractères composés de lettres, de chiffres et de . _ : -.

Si vous renvoyez la même requête avec la même clé, le résultat initial est renvoyé sans nouveau traitement. Rien n'est traité deux fois et les webhooks ne sont pas renvoyés.

N'utilisez la même clé que pour les nouvelles tentatives d'une même opération logique. Pour une opération différente, utilisez toujours une nouvelle clé. Réutiliser la même clé avec un contenu différent ou pour une autre opération peut être refusé avec 409.

À quelle étape intervient cette API ?

Il s’agit de la dernière étape du système de tampons.

  • Vérifier que l’accumulation est complète
  • Traiter l’attribution de la récompense
  • Marquer le tampon comme utilisé

Il ne s’agit pas seulement d’un changement d’état, mais de la finalisation du résultat du programme.

Point final du cycle

Cette API représente la dernière étape du cycle de tampons.

Pour l’utilisateur, c’est le moment de recevoir la récompense. Pour le développeur, cela marque la fin d’un cycle et le début du suivant.

Après Redeem, appeler Create permet de maintenir l’engagement.

Cycle complet

  1. Create → Émettre un tampon
  2. Add Stamp → Accumuler
  3. Validate → Vérifier
  4. Redeem → Utiliser la récompense
  5. Create → Démarrer un nouveau cycle

Jeton de vérification en point de vente (onsiteToken)

v2 n’accepte pas le mot de passe du point de vente en clair (onsitePwd). Envoyez sans modification l’onsiteToken renvoyé par l’API de validation. L’envoi de onsitePwd seul ou avec onsiteToken est refusé avec 400 (code d’erreur 1227).

Idempotency-Key est obligatoire pour toute requête utilisant un jeton. Une nouvelle tentative avec la même Idempotency-Key renvoie le résultat initial. La réutilisation du même jeton avec une autre Idempotency-Key est refusée avec 400 (code d’erreur 1228).

Le point de vente utilisé pour la validation doit être le même que celui où l’opération est traitée. Si processStoreIdx a été indiqué lors de la validation, cette requête doit utiliser le même point de vente. Un jeton validé sans point de vente ne peut pas être associé à un point de vente par la suite.

Les jetons expirés, altérés, déjà utilisés ou présentant une liaison incorrecte renvoient tous 1228. Ces causes ne sont volontairement pas distinguées afin d’éviter qu’un tiers puisse sonder l’état interne à l’aide d’un autre jeton.

Aucun jeton n’est requis pour les ressources qui n’utilisent pas la vérification en point de vente (onsiteYn = N). v1 continue d’accepter onsitePwd en clair.

Automatisation après utilisation

Vous pouvez automatiser les actions après utilisation de la récompense.

  • Appeler l’API de création de coupons pour émettre une récompense immédiatement
  • Créer un nouveau tampon pour démarrer un nouveau cycle

Ce flux permet d’automatiser l’ensemble du cycle de récompense sans intervention manuelle.

Points clés en opération

Cette API n’est pas seulement une fonctionnalité, mais le point où les résultats métier sont définitivement validés.

Il est essentiel de garantir le flux validation → utilisation, le contrôle transactionnel côté serveur et la journalisation d’audit.