API d’utilisation des coupons (Redeem)

L’API d’utilisation des coupons Vivoldi (Redeem) permet de marquer un coupon comme utilisé.

Le traitement peut être effectué automatiquement via API sans intervention manuelle depuis le tableau de bord.
Chaque requête réduit le nombre d’utilisations restantes, et une fois la limite atteinte, toute utilisation supplémentaire est bloquée.

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

PUT

/api/coupon/v1/redeem 

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233"
}

Request Parameters

cpnNo string required
Numéro du coupon.
onsitePwd string
Mot de passe du coupon sur site. Obligatoire si un mot de passe est défini pour le coupon sur site.
userId string
ID utilisateur. Sert à identifier l’émetteur ou l’utilisateur du coupon.
Doit être renseigné si la limite d’utilisation du coupon est fixée entre 2–5.
memo string
Note interne de référence. Peut être utilisée pour enregistrer l’IP de l’utilisateur, le lieu d’utilisation du coupon ou d’autres informations.
Si l’utilisation du coupon est illimitée, ce champ peut être utilisé à la place de userId pour différencier les utilisateurs. 
{
    "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

Utilisation avec l’API de validation

Étant donné que l’API d’utilisation modifie l’état du coupon, il est recommandé de vérifier sa validité via l’API de validation avant de l’appeler.

En confirmant à l’avance qu’un coupon est valide, vous évitez des traitements inutiles pour les coupons expirés ou déjà utilisés.

Le flux standard est : validation → utilisation.

Quand utiliser cette API

Utilisez cette API lorsque vous devez appliquer un coupon après validation.

  • Marquer un coupon comme utilisé après un paiement réussi
  • Enregistrer l’utilisation d’une remise lors de la confirmation de commande
  • Gérer l’utilisation en magasin ou hors ligne
  • Mettre à jour l’état pour éviter les utilisations en double

En résumé, il s’agit de l’étape finale où le coupon est effectivement consommé.

Flux d’utilisation du coupon

Le coupon est marqué comme utilisé sur la base du code (cpnNo).

  • Le nombre d’utilisations est réduit immédiatement
  • Le coupon passe à un état non réutilisable
  • L’utilisation est enregistrée selon les données utilisateur (userId)
  • Des informations supplémentaires peuvent être enregistrées via memo

Ce processus ne se limite pas à un changement d’état, mais constitue une transaction clé liée au paiement.

Identification utilisateur et utilisation du mémo

Le userId permet d’identifier l’utilisateur ayant utilisé le coupon.

Si le coupon autorise 2 à 5 utilisations, ce champ est obligatoire et empêche les utilisations multiples par le même utilisateur.

Le champ memo permet d’enregistrer des informations internes telles que l’adresse IP, le lieu d’utilisation ou la source de la requête.
En cas d’utilisation illimitée, il peut également remplacer userId pour différencier les utilisateurs.

Gestion du mot de passe pour les coupons sur site

Le champ onsitePwd est requis si un mot de passe est défini pour le coupon.

Il est utilisé dans des scénarios en magasin ou hors ligne, où le personnel vérifie le mot de passe avant de traiter le coupon.

Cas d’utilisation

  • Intégration e-commerce : Appeler l’API après paiement pour appliquer automatiquement le coupon et enregistrer la remise
  • Utilisation en magasin : Le personnel scanne le QR code, récupère le code et l’utilise immédiatement via API
  • Suivi d’utilisation : Enregistrer l’IP et la source dans memo pour analyser les abus ou anomalies
  • Gestion des usages multiples : Utiliser userId pour empêcher un utilisateur de dépasser la limite autorisée

Le même code peut être réutilisé pour créer un nouveau coupon après suppression.

Points à considérer

  • Appelez toujours cette API après validation pour garantir la sécurité.
  • Une fois utilisé, le coupon ne peut plus être réutilisé.
  • Une stratégie de rollback peut être nécessaire en cas d’échec de paiement.
  • Implémentez des mécanismes pour éviter les utilisations en double dues à des requêtes répétées.