API de validation des tampons

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.

GET

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


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
IDX du tampon. 
{
    "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",
        "onsitePwd": "123456",
        "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",
        "payloadVersion": "v1"
    }
}

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.
stampIdx integer
Stamp IDX.
domain string
Domaine du tampon.
cardIdx integer
Card IDX.
cardNm string
Nom de la carte.
cardTtl string
Titre de la carte.
stamps integer
Nombre de tampons collectés jusqu’à présent.
maxStamps integer
Nombre maximal de tampons sur la carte.
stampUrl string
URL de la page du tampon.
url string
URL vers laquelle l’utilisateur est redirigé en cliquant sur le bouton de la page du tampon.
strtYmd date
Date de début de validité du tampon.
endYmd date
Date d’expiration du tampon.
onsiteYn string
Enum :
YN
Indique si la validation sur site est activée.
Si la valeur est Y, le personnel peut ajouter des tampons directement en magasin.
onsitePwd string
Mot de passe pour la validation sur site.
Requis lors de l’utilisation de l’API d’avantage si l’option sur site est activée (Y).
memo string
Note interne à des fins de référence.
activeYn string
Enum :
YN
Indique si le tampon est actif.
S’il est désactivé, le client ne peut pas l’utiliser.
userId string
ID utilisateur. Utilisé pour gérer le bénéficiaire du tampon.
Généralement, il correspond à l’identifiant de connexion du membre du site web.
S’il n’est pas défini, un ID utilisateur est automatiquement généré par le système.
userNm string
Nom de l’utilisateur. Usage interne uniquement.
userPhnno string
Numéro de téléphone de l’utilisateur. Usage interne uniquement.
userEml string
Adresse e-mail de l’utilisateur. Usage interne uniquement.
userEtc1 string
Champ supplémentaire pour la gestion interne.
userEtc2 string
Champ supplémentaire pour la gestion interne.
stampImgUrl string
URL de l’image du tampon.
regYmdt datetime
Date de création du tampon. Exemple : 2025-07-21 11:50:20

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