API de mise à jour des coupons (v2)

L’API de mise à jour des coupons permet de modifier les informations des coupons déjà émis.

En utilisant le code coupon (cpNo) comme identifiant, vous pouvez mettre à jour le type de remise, la date d’expiration, les limites d’utilisation, le groupe et les informations utilisateur.
Certains champs ne peuvent plus être modifiés une fois le coupon utilisé.

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

API Version

PUT

/api/coupon/v2/update

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "nm": "$10 discount coupon",
    "disc": 10,
    "endYmd": "2025-12-31",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

cpnNostringrequired: Numéro du coupon.
domain string: Domaine du coupon.
Disponible dans les forfaits Premium et supérieurs : vous pouvez spécifier un domaine personnalisé.
webhookEnableYn string
Enum: YN: Activation du Webhook.
Le Webhook global doit être activé.
Cette fonctionnalité est disponible uniquement dans l’offre Enterprise.
nmstring: Nom du coupon.
discTypeIdxinteger: Type de remise. (457 : Pourcentage %, 458 : Montant fixe)
discdouble: Pour un pourcentage (457) : plage de 1 à 100 %. Pour un montant fixe (458) : saisir la valeur.
discCurrencystring: Unité monétaire. Obligatoire lors de l’utilisation d’une remise en montant fixe (discTypeIdx:458).
strtYmddate: Date de début de validité du coupon. Exemple : 2024-10-01
endYmddate: Date d’expiration du coupon. Exemple : 2024-12-31
La date d’expiration ne peut être définie que jusqu’au 31 décembre de l’année suivante.
useLimitinteger: Limite d’utilisation du coupon. (0 : Illimité, 1–5 : Utilisation limitée)
Si elle est fixée à 2 ou plus, la valeur userId doit être spécifiée.
grpIdxinteger: Groupe de coupons. Utilisé pour gérer les coupons par groupe. L’IDX du groupe peut être vérifié dans le tableau de bord.
En cas de conflit entre les paramètres du groupe et ceux du coupon, les paramètres du groupe sont prioritaires.
tmplIdxinteger: Modèle de coupon. Utilisé comme référence lors de la création d’un coupon. L’IDX du modèle peut être vérifié dans le tableau de bord.
onsiteYnstring: Coupon sur site. Affiche le bouton « Utiliser le coupon » sur la page du coupon.
Nécessaire pour que le personnel en magasin puisse valider le coupon.
onsitePwdstring: Mot de passe du coupon sur site. Requis lors de l’utilisation du coupon.
memostring: Note interne à usage de référence.
urlstring: Si une URL est saisie, un bouton « Aller utiliser le coupon » s’affiche sur la page du coupon.
En cliquant sur le bouton ou sur l’image du coupon, l’utilisateur est redirigé vers cette URL.
colorstring: Couleur du texte du coupon. Entrer une valeur HEX. Exemple : #4F4F4F
backgroundstring: Couleur d’arrière-plan du coupon. Entrer une valeur HEX. Exemple : #FFFFFF
userIdstring: Utilisé pour gérer le bénéficiaire du coupon.
Obligatoire si la limite d’utilisation est fixée entre 2 et 5. Généralement l’ID de connexion ou le nom de l’utilisateur.
userNmstring: Nom de l’utilisateur du coupon. À usage interne.
userPhnnostring: Numéro de téléphone de l’utilisateur du coupon. À usage interne.
userEmlstring: Adresse e-mail de l’utilisateur du coupon. À usage interne.
userEtc1string: Champ supplémentaire pour gestion interne.
userEtc2string: Champ supplémentaire pour gestion interne.
branchIdx integer: IDX de l'agence émettrice. S'il est omis, l'émission est effectuée par le siège ; envoyez 0 pour le vider.
Disponible à partir de l'offre Business.
storeIdx integer: IDX du magasin émetteur. S'il est indiqué, l'agence à laquelle appartient le magasin devient l'agence émettrice. Envoyer une autre agence génère une erreur.
useScope string: Portée d'utilisation. Seules les valeurs ALL (tous les magasins) ou BRANCH (une agence précise) sont acceptées. Par défaut : ALL.
useBranchIdx integer: IDX de l'agence d'utilisation. Requis uniquement lorsque useScope = BRANCH ; toujours vide avec ALL.

{
    "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

Agence émettrice, magasin émetteur et portée d'utilisation

Les valeurs définies ici constituent la politique enregistrée au moment de l'émission. « Où a-t-il été émis » (agence émettrice, magasin émetteur) et « où le client peut-il l'utiliser » (portée d'utilisation, agence d'utilisation) sont des notions distinctes : les paramètres sont donc séparés.

Paramètre	Signification	Description
`branchIdx`	Agence émettrice	S'il est omis, le siège émet. Envoyez `0` pour revenir au siège.
`storeIdx`	Magasin émetteur	S'il est indiqué, l'agence du magasin devient l'agence émettrice. Envoyer une autre agence est refusé.
`useScope`	Portée d'utilisation	`ALL` (tous les magasins) ou `BRANCH` (une agence). Par défaut : `ALL`.
`useBranchIdx`	Agence d'utilisation	Requis uniquement avec `useScope=BRANCH`. Toujours vide avec `ALL`.

Paramètres non utilisables — processStoreIdx (magasin de traitement) désigne le magasin où une vérification, une utilisation, un ajout ou un retrait a réellement eu lieu ; il ne peut pas être utilisé avec cette API. S'il est envoyé, la réponse est 400 (code d'erreur 1227).

Les fonctions d'agence et de magasin sont disponibles uniquement à partir de l'offre Business.

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.

Quand utiliser cette API

Utilisez cette API lorsque vous devez modifier les conditions de coupons déjà émis.

Elle est idéale pour gérer des campagnes en cours, comme prolonger une période promotionnelle, ajuster une remise ou ajouter des restrictions par utilisateur.

Le code du coupon restant inchangé, vous pouvez mettre à jour les conditions sans réémettre ni retirer les coupons déjà distribués.

Comment prolonger la validité

Pour prolonger la date d’expiration, définissez une nouvelle valeur dans le paramètre endYmd.
Les coupons expirés peuvent être réactivés en définissant une date future. Utilisez le format YYYY-MM-DD.

Cas d’utilisation

Prolonger une promotion : Modifiez endYmd pour étendre la validité d’une campagne
Ajuster les paramètres de remise : Mettez à jour disc selon votre stratégie
Augmenter les limites d’utilisation : Augmentez useLimit pour les clients VIP
Réaffecter un groupe : Changez grpIdx pour appliquer de nouvelles configurations
Ciblage utilisateur : Proposez des remises personnalisées selon l’email ou l’ID utilisateur
Modifier la page cible : Mettez à jour l’URL du coupon vers une autre page promotionnelle

Points à considérer

Si cpNo (code coupon) est invalide, la mise à jour échouera.
Certains champs peuvent être restreints après utilisation.
Modifier la remise peut impacter l’expérience utilisateur.
Les coupons expirés peuvent ne pas être immédiatement réactivés.
Pour les coupons en magasin, mettez à jour le mot de passe en cas de changement de personnel.