API de mise à jour des tampons en ligne

API Version

PUT

/api/stamp/v2/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

stampIdx integer required: Stamp IDX.
cardIdx integer: Card IDX.
Le Card IDX peut être consulté sur la page « Carte de Tampons » du tableau de bord.
stamps integer: Indique le nombre de tampons accumulés.
Représente le nombre total de tampons collectés par le client. La modification de cette valeur met à jour l’état d’avancement des tampons et peut être augmentée ou réduite.
Lorsque tous les tampons sont complétés (stamps = nombre maximal défini sur la carte), vous devez définir useYn sur Y pour marquer le tampon comme utilisé.
resetPinYn string
Default :N
Enum : YN: Spécifie si le code PIN du client pour le tampon doit être réinitialisé.
Y : Réinitialise le code PIN existant du client. Après la réinitialisation, le client devra définir un nouveau code PIN lors de la prochaine visite sur la page du tampon.
N : Conserve le code PIN actuel sans modification.
useYn string
Default :N
Enum : YN: Indique si le client a utilisé la récompense du tampon.
Y : Le client a complété tous les tampons et a utilisé une récompense (par exemple, boisson gratuite, réduction, etc.). Après utilisation, le tampon devient inactif et un nouveau doit être émis.
N : La récompense n’a pas encore été utilisée.
Lors du passage de N à Y, le nombre de tampons enregistré doit avoir atteint le maximum de la carte et, si le tampon possède un mot de passe sur site, onsiteToken doit également être envoyé.
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.
domain string
Default :https://vvd.bz: Domaine du tampon.
Si vide, le domaine par défaut sera utilisé.
Disponible à partir du plan Premium — vous pouvez définir un domaine personnalisé enregistré dans la section Gestion des Domaines de Liens.
strtYmd date: Date de début de validité du tampon. Exemple : 2025-01-01
endYmd date: Date d’expiration du tampon. Exemple : 2025-12-31
La date d’expiration peut être définie jusqu’à 5 ans à compter d’aujourd’hui.
activeYn string
Default :Y
Enum : YN: Indique si le tampon est actif. Si désactivé, le client ne pourra pas utiliser le tampon.
memo string: Note interne à des fins de référence.
userId string: ID utilisateur. Utilisé pour gérer le destinataire du tampon.
En général, saisissez l’identifiant de connexion du membre du site web.
Si non défini, un ID utilisateur sera automatiquement généré par le système.
userNm string: Nom de l’utilisateur. Usage interne uniquement.
userPhnno string: Numéro de téléphone de l’utilisateur. Usage interne uniquement.
userEml string: Adresse e-mail de l’utilisateur. Usage interne uniquement.
userEtc1 string: Champ supplémentaire pour la gestion interne.
userEtc2 string: Champ supplémentaire pour la 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

Validation des paramètres numériques

Si un paramètre numérique reçoit une valeur non numérique ou un nombre dépassant la plage que le serveur peut traiter, la requête est immédiatement refusée avec 400 (code d'erreur 653).

Dans ce cas, les données du tampon et l'historique de cumul ne changent pas du tout, et aucun enregistrement d'événement ni envoi de Webhook n'est produit. Une réponse en échec signifie que rien n'a été enregistré.

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.

Pourquoi contrôler directement le nombre de tampons

Lors de l’exploitation d’un système de tampons, certaines situations nécessitent un ajustement manuel du nombre de tampons.

Cela inclut la correction d’erreurs, l’attribution de bonus lors de campagnes et les ajustements manuels par les administrateurs.

En définissant le paramètre stamps, vous pouvez augmenter ou diminuer la valeur sans écraser l’existant.
Lorsque le maximum est atteint, vous devez définir useYn sur Y pour traiter l’utilisation de la récompense.

Flux d’utilisation des récompenses et de réémission

Définir useYn sur Y marque le tampon comme utilisé.

Après utilisation, un nouveau tampon doit être émis via l’API de création pour redémarrer l’accumulation.
Ce flux constitue le cycle central des programmes de récompense basés sur les tampons.
L’automatisation de Utilisation → Nouvelle émission → Réaccumulation favorise l’engagement récurrent.

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.

Cette API n’utilise le jeton que lorsqu’une transition réelle vers l’utilisation de la récompense (N → Y) a lieu. L’envoi d’un jeton lors d’une mise à jour ordinaire qui ne modifie que la note, la période ou l’état actif est refusé avec 400 (code d’erreur 1227). Même si la requête contient useYn = Y, le jeton n’est pas consommé si aucune transition réelle N → Y n’a lieu (par exemple si la récompense a déjà été utilisée).

Cette API n’accepte pas de paramètre de point de vente de traitement (processStoreIdx). Lorsqu’une récompense est utilisée, le lieu de traitement est déterminé à partir du point de vente lié au jeton lors de la validation, et non à partir de la requête, puis enregistré dans l’événement et le Webhook. Ce lieu de traitement ne s’applique pas aux mises à jour ordinaires.

Le même jeton peut également être utilisé avec l’API d’utilisation des récompenses (Redeem), mais il ne peut être utilisé qu’une seule fois dans l’une des deux API. Une fois consommé par l’une d’elles, il est refusé par l’autre.

Quand réinitialiser le PIN

Définir resetPinYn sur Y réinitialise le PIN de l’utilisateur.

À utiliser lorsque l’utilisateur oublie son PIN, change d’appareil ou pour des raisons de sécurité.

Après réinitialisation, l’utilisateur devra créer un nouveau PIN lors de l’accès à la page de tampons. Si défini sur N ou omis, le PIN actuel est conservé.

Cas d’utilisation

Correction d’erreurs : Ajuster les tampons attribués incorrectement
Mise à jour de campagne : Appliquer les changements de conditions en cours
Réauthentification : Réinitialiser le PIN pour reconfigurer l’authentification offline
Désactivation : Désactiver les tampons à la fin de la campagne

Points à considérer

Assurez-vous que les modifications de stamps restent cohérentes avec l’historique existant
Une fois marqué comme utilisé (useYn), l’opération doit être considérée comme irréversible
Conservez des logs opérationnels et un historique détaillé pour le suivi et l’audit

API de mise à jour des tampons (v2)