API d’utilisation des coupons en ligne

API Version

PUT

/api/coupon/v2/redeem

Request
Response

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

Request Parameters

cpnNo string required: Numéro du coupon.
onsiteToken string: Jeton d'échange de courte durée. v2 n'accepte pas le mot de passe en clair (onsitePwd).
Lorsque la ressource a onsiteYn = Y, envoyez tel quel l'onsiteToken renvoyé par l'API de vérification.
Idempotency-Key est obligatoire pour les requêtes utilisant un jeton. Une nouvelle tentative avec la même clé rejoue le résultat initial ; réutiliser le même jeton avec une autre clé est refusé avec 400 (code d'erreur 1228).
Si un magasin de traitement a été indiqué lors de la vérification, cette requête doit utiliser le même.
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.
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": 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

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

Idempotency-Key

Pour réessayer en toute sécurité lorsqu'une réponse est perdue à cause d'une erreur réseau, envoyez une valeur unique par requête dans l'en-tête Idempotency-Key. Vous pouvez aussi l'envoyer via requestId dans le corps ; si les deux sont envoyés avec des valeurs différentes, la requête est refusée. Le format autorisé est de 8 à 64 caractères composés de lettres, de chiffres et de . _ : -.

Si vous renvoyez la même requête avec la même clé, le résultat initial est renvoyé sans nouveau traitement. Rien n'est traité deux fois et les webhooks ne sont pas renvoyés.

N'utilisez la même clé que pour les nouvelles tentatives d'une même opération logique. Pour une opération différente, utilisez toujours une nouvelle clé. Réutiliser la même clé avec un contenu différent ou pour une autre opération peut être refusé avec 409.

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.

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

v2 n’accepte pas le mot de passe du point de vente en clair (onsitePwd). Envoyez sans modification l’onsiteToken renvoyé par l’API de validation. L’envoi de onsitePwd seul ou avec onsiteToken est refusé avec 400 (code d’erreur 1227).

Idempotency-Key est obligatoire pour toute requête utilisant un jeton. Une nouvelle tentative avec la même Idempotency-Key renvoie le résultat initial. La réutilisation du même jeton avec une autre Idempotency-Key est refusée avec 400 (code d’erreur 1228).

Le point de vente utilisé pour la validation doit être le même que celui où l’opération est traitée. Si processStoreIdx a été indiqué lors de la validation, cette requête doit utiliser le même point de vente. Un jeton validé sans point de vente ne peut pas être associé à un point de vente par la suite.

Les jetons expirés, altérés, déjà utilisés ou présentant une liaison incorrecte renvoient tous 1228. Ces causes ne sont volontairement pas distinguées afin d’éviter qu’un tiers puisse sonder l’état interne à l’aide d’un autre jeton.

Aucun jeton n’est requis pour les ressources qui n’utilisent pas la vérification en point de vente (onsiteYn = N). v1 continue d’accepter onsitePwd en clair.

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.

API d’utilisation des coupons (Redeem) (v2)