API de création de coupons en ligne (v2)

L’API de création de coupons Vivoldi permet de générer des coupons de réduction de manière programmatique.

Choisissez entre une remise en pourcentage (%) ou un montant fixe, et configurez des options telles que la date d’expiration, le nombre d’utilisations, le groupe et le modèle directement dans la requête.

Pour créer des coupons en lot, utilisez le tableau de bord.
Si des images sont nécessaires, créez d’abord un groupe de coupons et importez les images dans le tableau de bord, puis générez les coupons en utilisant ce groupe.

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

API Version

POST

/api/coupon/v2/create

Request
Response

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": "N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11,
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNostring: Numéro du coupon. 8 à 16 caractères alphanumériques. Si aucune valeur n’est saisie, le système le génère automatiquement. Les caractères spéciaux ne sont pas autorisés.
Exemple : V5H8GR5T
cpnNoDigits integer
Default:16
Enum: 16128: Longueur du code coupon.
Si aucune valeur n’est fournie, la longueur par défaut (16) est utilisée.
Utilisé uniquement si aucun code n’est spécifié. Le système génère automatiquement un code avec la longueur choisie.
domain string
Par défaut :https://vvd.bz: Domaine du coupon.
S’il est laissé vide, le domaine par défaut sera utilisé.
Disponible dans les forfaits Premium et supérieurs : vous pouvez spécifier un domaine personnalisé enregistré dans la Gestion des domaines de liens.
webhookEnableYn string
Enum: YN: Activation du Webhook.
Le Webhook global doit être activé.
Cette fonctionnalité est disponible uniquement dans l’offre Enterprise.
nmstringrequired: Nom du coupon.
discTypeIdxintegerrequired: Type de réduction. (457 : Pourcentage %, 458 : Montant fixe)
discdoublerequired: Pourcentage (457) : plage de 1 à 100 %. Montant fixe (458) : saisir la valeur.
discCurrencystring: Devise. Obligatoire lors de l’utilisation d’une réduction à montant fixe (discTypeIdx:458).
strtYmddaterequired: Date de début de validité du coupon. Exemple : 2024-10-01
endYmddaterequired: 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.
useLimitintegerrequired: Limite d’utilisation du coupon. (0 : Illimité, 1–5 : Nombre d’utilisations)
Si défini sur 2 ou plus, la valeur userId doit obligatoirement ê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": "ZJLF0399WQBEQZJM"
}

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 string: Valeur de réponse. Le numéro de coupon généré est renvoyé.
Exemple : ZJLF0399WQBEQZJM

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 générer automatiquement des coupons pour des promotions, des événements ou des campagnes d’acquisition d’utilisateurs.

Elle convient à divers scénarios marketing, tels que les incitations à l’inscription, les remises ciblées et l’augmentation des conversions issues du trafic publicitaire.

Configuration du format du code coupon

Le code coupon est contrôlé via les paramètres cpNo et cpNoDigits.
Si cpNo est défini, cette valeur est utilisée comme code coupon. Sinon, le système génère automatiquement un code.

En génération automatique, vous pouvez définir la longueur avec cpNoDigits (par défaut : 16).
Adaptez la longueur selon votre usage : plus le code est long, plus le risque de collision est faible, tandis qu’un code court est plus facile à saisir.

Association des données utilisateur

Pour attribuer un coupon à un utilisateur spécifique, définissez le paramètre userId.

Pour associer des coupons à plusieurs utilisateurs, utilisez les champs userEml·userPhone·userEtc1·userEtc2 conjointement.
Ces données sont utilisées dans le tableau de bord pour identifier et filtrer les propriétaires de coupons, ce qui est utile pour les services B2C nécessitant une identification des utilisateurs.

Cas d’utilisation

Récompenses automatiques à l’inscription : Appelez l’API lors de l’inscription pour générer et envoyer un coupon personnalisé immédiatement
Promotions à durée limitée : Définissez des dates de début et de fin pour des coupons valables uniquement sur une période donnée
Suivi des conversions : Associez des coupons aux liens publicitaires pour suivre clic → utilisation → achat
Ciblage utilisateur : Proposez des remises personnalisées basées sur l’email ou l’ID utilisateur
Coupons en magasin : Définissez onsiteYn sur Y pour une validation par mot de passe par le personnel

Points à considérer

Pour créer des coupons avec images, créez d’abord un groupe de coupons et importez les images dans le tableau de bord, puis spécifiez l’ID du groupe dans grpIdx avant l’appel API.
Pour recevoir des webhooks, définissez webhookEnablYn sur Y et enregistrez l’URL Webhook à l’avance dans le tableau de bord.
Si useLimit est illimité, le coupon ne sera pas marqué comme utilisé même après utilisation.
Pour les coupons en magasin, assurez une gestion sécurisée du mot de passe de validation.