API d’ajout de tampons (v1)

L’API d’ajout de tampons incrémente de un le nombre de tampons d’un enregistrement existant.

Lorsqu’un utilisateur effectue un achat, une visite ou une action spécifique, cette API ajoute automatiquement un tampon.
Aucun tampon supplémentaire n’est ajouté une fois le maximum atteint sur la carte.

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/add

Request
Response

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required: Stamp IDX.

{
    "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 cette API est essentielle

Si l’API de création génère la carte, l’API d’ajout enregistre les actions réelles des utilisateurs.

Chaque achat ou visite est enregistré, permettant de construire un système de récompense basé sur le comportement sans système de points.

Une seule requête API permet de relier directement les actions à l’accumulation de tampons.

Gestion du maximum atteint

Lorsque le maximum est atteint, aucun tampon supplémentaire n’est ajouté.
Processus recommandé :

Vérifier stamps et maxStamps
Si égaux → accumulation complète
Utiliser Update API avec useYn=Y
Appeler Stamp Create API pour démarrer un nouveau cycle
Poursuivre avec un nouveau cycle d’accumulation

Conditions et limites d’accumulation

L’accumulation de tampons ne s’applique pas automatiquement dans tous les cas.

Les conditions suivantes doivent être remplies :

Le tampon est actif (activeYn = Y)
Dans la période de validité (strtYmd ~ endYmd)
Le maximum n’est pas atteint (stamps < maxStamps)
Non déjà utilisé

Ces conditions garantissent une accumulation conforme aux règles de la campagne.

Cas d’utilisation

Événements de visite : Ajouter un tampon lors d’une visite
Récompense d’achat : Ajouter automatiquement un tampon après paiement
Événements à mission : Attribuer des tampons après des actions spécifiques
Check-in quotidien : Ajouter un tampon pour chaque connexion

Points clés en opération

L’API d’accumulation des tampons est un composant essentiel qui impacte directement la qualité des campagnes.

Des accumulations incorrectes réduisent la confiance dans la campagne
Des appels API en double peuvent entraîner une accumulation excessive
Impact direct sur l’expérience utilisateur

Elle doit toujours être utilisée avec validation et contrôle logique côté serveur.