API de validation de coupons en ligne

API Version

GET

/api/coupon/v2/validate?cpnNo={cpnNo}

Request
Response


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNostringrequired: Numéro du coupon.
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": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25",
        "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: Validation réussie : La réponse renvoie les informations du coupon.
Échec de la validation : La réponse est null et peut être vérifiée via le message d’erreur.

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.

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

Que peut-on déterminer à partir du résultat de validation ?

Cette API va au-delà d’une simple vérification « valide / non valide ».
Elle permet aux développeurs de construire leur propre logique à partir de données détaillées.

Grâce à la réponse (result), vous pouvez déterminer :

Si une remise peut être appliquée et en calculer le montant
Si le coupon est réservé à certains utilisateurs (userId, userEml)
Si les limites d’utilisation sont dépassées (useCnt, useLimit)
Si le coupon est expiré ou pas encore actif (strtYmd, endYmd)
Si certaines conditions sont remplies (online/offline, etc.) (onsiteYn)
L’URL de destination après application du coupon (url)

Autrement dit, ce n’est pas seulement un résultat,
mais une API orientée données pour une logique flexible au niveau applicatif.

Méthode de validation

La validation est effectuée sur la base du code coupon (cpNo) en tenant compte de plusieurs critères.

Existence
Période de validité
Limites d’utilisation
Conditions utilisateur
Environnement applicable

Le résultat est renvoyé sous forme de données structurées, et non comme un simple booléen.

Utilisation des données de réponse

L’objet result contient toutes les informations essentielles du coupon.

Les développeurs peuvent utiliser ces données pour :

Calculer et afficher les remises en temps réel côté frontend
Limiter l’utilisation à certains utilisateurs
Appliquer une logique conditionnelle selon le montant
Afficher des messages UI selon l’état du coupon (expiré, utilisé, etc.)

Cas d’utilisation

Validation avant paiement : Valider le coupon et l’appliquer uniquement s’il est valide
Messages utilisateur : Afficher des messages selon le résultat (expiré ou déjà utilisé)
Calcul de remise : Utiliser (disc, discType) pour calculer le montant final

Le même code peut être réutilisé après suppression.

Points à considérer

Le résultat de validation reflète l’état au moment de la requête et peut évoluer avant utilisation.
Implémentez toujours le flux : validation → utilisation (Redeem).
Se fier uniquement à la validation côté client présente un risque de sécurité.
Vérifiez à nouveau le calcul des remises côté serveur pour garantir précision et sécurité.

API de validation des coupons (v2)