API de validation des tampons (v2)

L’API de validation des tampons permet de vérifier si un tampon est dans un état valide avant l’ajout, la suppression ou l’utilisation d’une récompense.

Elle vérifie en une seule requête le stamp IDX, la période de validité, l’état actif et si la récompense a déjà été utilisée.

En plus de la validation, elle retourne l’état d’accumulation et les informations de la carte, permettant de construire l’interface utilisateur.

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

API Version

GET

/api/stamp/v2/validate?stampIdx={stampIdx}

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required: IDX du tampon.
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": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

codeinteger: Code de réponse : 0 = Succès, toute autre valeur = Erreur
messagestring: Message de réponse. Si le code n’est pas 0, un message d’erreur correspondant est renvoyé.
resultobject: Si la vérification réussit, la réponse inclura les informations du tampon.
En cas d’échec, la valeur de la réponse sera null et le message d’erreur indiquera la cause.

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

La réponse de l’API de validation v2 n’inclut pas le mot de passe du point de vente en clair (onsitePwd). Elle renvoie à la place un onsiteToken valable pendant 180 secondes.

L’objectif est de réduire au minimum l’exposition du mot de passe en clair, et non de renforcer l’authentification. L’API de validation ne vérifie pas le mot de passe lui-même ; le jeton n’ajoute donc aucun facteur d’authentification supplémentaire. Sa courte durée de validité, son usage unique et sa liaison au contexte limitent en revanche sa réutilisation.

Élément	Valeur
Durée de validité	180 secondes. La durée de validité est également renvoyée dans `onsiteTokenExpiresIn`.
Utilisations	Une seule. Une fois le jeton utilisé, seules les nouvelles tentatives avec la même `Idempotency-Key` renvoient le résultat initial.
Liaison	Organisation, compte associé à la clé d’API, ressource, action et point de vente de traitement confirmé lors de la validation
Utilisé pour	Utilisation d’un coupon, utilisation d’une récompense de tampon et mise à jour d’un tampon avec `useYn = Y`

Aucun jeton n’est émis pour les ressources qui n’utilisent pas la vérification en point de vente (onsiteYn = N). L’API de validation v1 continue de renvoyer onsitePwd en clair.

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).

Quel est le rôle de la validation des tampons ?

L’API de validation des tampons va au-delà d’une simple vérification.
Elle permet de déterminer l’action suivante en fonction de l’état actuel.

Vérifier si de nouveaux tampons peuvent être ajoutés
Confirmer si les conditions de récompense sont remplies
Vérifier la participation aux campagnes
Consulter la progression par utilisateur

En résumé, c’est l’API centrale pour analyser le progrès d’une campagne.

Ce que permet le résultat de validation

La réponse (result) contient toutes les données nécessaires pour évaluer la progression.

Elle permet de :

Comparer stamps et maxStamps
Déterminer si l’accumulation est encore possible
Vérifier si les conditions de récompense sont remplies
Contrôler l’état (activeYn)
Évaluer le contexte d’utilisation (onsiteYn)
Appliquer une personnalisation basée sur les données utilisateur

Point clé : « API de validation = état + entrée pour la logique métier »

Utilisation des données de réponse

La réponse de l’API de validation est utilisée directement dans la logique applicative.

Exemples :

Afficher la progression : Visualiser l’avancement en temps réel
Contrôler les actions : Activer ou désactiver selon l’état
Afficher les récompenses : Montrer les bénéfices atteints
Gérer les états utilisateur : Adapter la logique selon la progression

En résumé, cette API est la source de données clé reliant l’UI et la logique métier.

Différence avec l’API de validation des coupons

Les deux APIs retournent des données de validation, mais leur nature diffère.

La validation des coupons fournit des données transactionnelles comme le type de réduction, la valeur et les limites d’utilisation.
La validation des tampons fournit des données de progression comme stamps, maxStamps, nom de carte, titre et image.

La validation des coupons sert à calculer « le montant de la réduction actuelle »,
alors que la validation des tampons indique « ce qui est accumulé et ce qu’il reste à atteindre ».

Importance opérationnelle

L’API de validation des tampons est au cœur du flux d’événement.

Empêche les accumulations incorrectes
Bloque les actions lorsque les conditions ne sont pas remplies
Améliore l’expérience utilisateur
Assure la stabilité de la logique événementielle

Sans validation, des incohérences de données et des erreurs peuvent survenir.

Points à considérer

L’état peut changer entre la validation et l’exécution réelle
Il est recommandé d’appeler immédiatement l’API d’accumulation après validation
Évitez de vous reposer uniquement sur la validation côté client
En cas de trafic élevé, optimisez les appels et mettez en place des mécanismes de retry