API de mise à jour des tampons (v1)

L’API de mise à jour des tampons permet de modifier les données des tampons déjà émis.

Au-delà des modifications de base, vous pouvez ajuster le nombre de tampons, gérer l’utilisation des récompenses et réinitialiser les PIN, offrant un contrôle direct sur l’état utilisateur.

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

Documentation v1 (Legacy).

Pour les nouvelles intégrations, nous recommandons d’utiliser la version la plus récente, v2.
v1 est destinée à la maintenance des intégrations existantes et ne reçoit aucune nouvelle fonctionnalité ni amélioration.

API Version

PUT

/api/stamp/v1/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsitePwd": "12345",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

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, onsitePwd doit également être envoyé.
onsitePwd string: Mot de passe d’authentification du personnel pour les tampons sur site.
Requis lors du passage de useYn de N à Y pour marquer la récompense comme utilisée, si le tampon a onsiteYn = Y. La même règle de validation que l’API Redeem s’applique.
Non requis si seul le nombre de tampons est modifié ou si le tampon n’a pas de mot de passe.
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.

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

Changement de comportement. Auparavant, v1 poursuivait le traitement de la requête même lorsque cette validation échouait. L'erreur pouvait alors être remplacée par le message d'un autre paramètre, ou une partie des données du tampon était réellement enregistrée alors que la réponse signalait une erreur. Le traitement s'arrête désormais avec 400 avant traitement, comme dans la dernière version.

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.

Mot de passe du point de vente lors de l’utilisation d’une récompense

Lorsque useYn passe de N à Y pour utiliser une récompense, vous devez également envoyer onsitePwd si un mot de passe d’attribution des tampons en point de vente est configuré pour le tampon (onsiteYn = Y).

Cette exigence s’applique de la même manière qu’à l’API d’utilisation des récompenses (Redeem). Elle empêche qu’une récompense soit utilisée via l’API de mise à jour sans vérification du mot de passe.

Pour connaître le mot de passe à envoyer, consultez la valeur onsitePwd renvoyée par l’API de validation (Validate). Si aucun mot de passe de point de vente n’est configuré pour le tampon, vous pouvez omettre onsitePwd.

onsitePwd n’est pas requis si vous modifiez uniquement le nombre de tampons ou si vous mettez à jour un tampon dont la récompense a déjà été utilisée.

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