API d’ajout de tampons (v2)

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.

API Version

PUT

/api/stamp/v2/add

Request
Response

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required: Stamp IDX.
stamps integer: Nombre de tampons à ajouter (ou à retirer). Valeur par défaut : 1, doit être supérieure à 0.
Les quantités dépassant le maximum de la carte ou inférieures à zéro sont ajustées par le serveur. Si la variation réelle est nulle, aucun historique ni webhook n'est créé.
processStoreIdx integer: IDX du magasin où cette requête est réellement traitée. S'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique de traitement.
L'agence de traitement n'est pas reçue dans la requête ; le serveur la déduit de ce magasin. Cette valeur diffère du magasin émetteur (storeIdx).

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

Indiquer le magasin de traitement

Paramètre	Signification	Description
`processStoreIdx`	Magasin de traitement	Le magasin où cette requête est réellement traitée. Facultatif : s'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique.

L'agence de traitement n'est pas reçue dans la requête. Le serveur la déduit du magasin indiqué et l'enregistre.

Si la portée d'utilisation est BRANCH, le traitement n'a lieu que si l'agence du magasin vérifié correspond à l'agence d'utilisation, ou si vous vous authentifiez avec le mot de passe sur place de cette agence. Sans l'un ou l'autre, la requête est refusée.

Paramètres non utilisables — branchIdx (agence émettrice), storeIdx (magasin émetteur), useScope (portée d'utilisation) et useBranchIdx (agence d'utilisation) relèvent de la politique d'émission déjà enregistrée et ne peuvent pas être modifiés via cette API. S'ils sont envoyés, la réponse est 400 (code d'erreur 1227).

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 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.