API de validation des coupons

L’API de validation des coupons Vivoldi permet de vérifier si un coupon est valide avant son utilisation.

En plus de vérifier la disponibilité, elle renvoie les informations de remise, les conditions d’utilisation et les données utilisateur, permettant de gérer des logiques métier flexibles.

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

GET

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


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNostringrequired
Numéro du coupon. 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake 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",
        "onsitePwd": "12345",
        "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"
    }
}

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.
cpnNostring
Numéro du coupon.
domain string
Domaine du coupon.
nmstring
Nom du coupon.
discTypeIdxinteger
Type de réduction. (457 : remise en %, 458 : remise en montant)
discdouble
Pour les remises en % (457) : plage de 1 à 100 %. Pour les remises en montant (458) : saisissez une valeur.
discCurrencystring
Devise. Obligatoire lors de l’utilisation d’une remise en montant (discTypeIdx :458).
formatDiscCurrencystring
Symbole monétaire.
strtYmddate
Date de début de validité du coupon.
endYmddate
Date d’expiration du coupon.
useLimitinteger
Nombre d’utilisations autorisées. (0 : illimité, 1–5 : utilisation limitée)
imgUrlstring
URL de l’image du coupon.
onsiteYnstring
Coupon sur site. Définit si le bouton « Utiliser le coupon » s’affiche sur la page du coupon.
Requis pour une utilisation en magasin physique.
onsitePwd string
Mot de passe du coupon sur site.
Obligatoire lors de l’appel à l’API d’utilisation du coupon si l’option sur site est activée (Y).
memostring
Note interne.
urlstring
Si une URL est saisie, un bouton « Aller utiliser le coupon » apparaît sur la page du coupon.
Un clic sur le bouton ou l’image du coupon redirige vers cette URL.
userIdstring
Utilisé pour gérer le destinataire du coupon.
Obligatoire si le nombre d’utilisations est défini entre 2 et 5.
En général, il s’agit de l’ID de connexion ou du nom en anglais de l’utilisateur du site.
userNmstring
Nom de l’utilisateur du coupon. Pour usage interne uniquement.
userPhnnostring
Numéro de téléphone de l’utilisateur du coupon. Pour usage interne uniquement.
userEmlstring
E-mail de l’utilisateur du coupon. Pour usage interne uniquement.
userEtc1string
Champ interne supplémentaire.
userEtc2string
Champ interne supplémentaire.
useCntinteger
Nombre d’utilisations du coupon.
regYmdtdatetime
Date de création du coupon. Exemple : 2025-07-21 11:50:20

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