API de création de tampons en ligne

API Version

POST

/api/stamp/v2/create

Request
Response

{
    "cardIdx": 123,
    "storeIdx": 22,
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "activeYn": "Y",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cardIdx integer required: Card IDX.
Le Card IDX peut être consulté sur la page « Carte de Tampons » du tableau de bord.
strtYmd date required: Date de début de validité du tampon. Exemple : 2025-01-01
endYmd date required: 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: Statut d’activation du tampon.
Si désactivé, les clients ne pourront pas utiliser le tampon.
memo string: Note interne à des fins de référence.
userId string: ID utilisateur.
Utilisé pour gérer le destinataire de l’émission du tampon.
En général, saisissez l’identifiant de connexion du membre du site web.
Si ce champ n’est pas 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.
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.

{
    "code": 0,
    "message": "",
    "result": 1347
}

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 integer: Valeur de réponse. Le Stamp IDX généré sera renvoyé.
Exemple : 1347

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

L'agence émettrice, la portée d'utilisation et l'agence d'utilisation suivent les valeurs définies sur la carte de tampons. Vous ne pouvez choisir le magasin émetteur directement via storeIdx que si la carte le laisse vide. Envoyer une valeur différente de celle de la carte renvoie 400 (code d'erreur 1221).

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 pour créer des campagnes basées sur des tampons et des systèmes de récompense.

Campagnes de récompense basées sur les visites
Programmes de collecte de tampons en magasin
Systèmes de validation des activités utilisateurs
Suivi d’actions spécifiques (achats, participation, etc.)

Idéale pour suivre les actions des utilisateurs et les transformer en récompenses.

Relation entre carte de tampons et tampons

La carte de tampons définit les règles et le design de la campagne, tandis que les tampons sont les unités attribuées aux utilisateurs.

Lors de l’appel à l’API de création, utilisez cardIdx pour définir sur quelle carte attribuer le tampon.

L’IDX de la carte est disponible dans le tableau de bord. Chaque carte ayant ses propres conditions et récompenses, il est essentiel de sélectionner la bonne.

Structure et composants de création de tampons

Un tampon n’est pas une simple donnée, mais une unité représentant l’activité de l’utilisateur.

Composants clés :

Identifiant de carte (cardIdx) : ID de la carte associée
Période de validité (strtYmd, endYmd) : Période pendant laquelle le tampon est valide
Statut (activeYn) : Indique si le tampon est actif et utilisable
Informations utilisateur (userId, userNm, userEmail, etc.) : Utilisateur cible
Données supplémentaires (memo, userEtc1, userEtc2) : Données personnalisées

Cela permet un suivi et une gestion personnalisés des activités utilisateurs.

Intégration des données utilisateur

Le champ userId est utilisé pour identifier et gérer le destinataire du tampon.

En général, l’ID utilisateur interne est utilisé. S’il n’est pas fourni, le système en génère un automatiquement.

En ajoutant userNm, userPhnno et userEml, vous pouvez stocker les coordonnées et suivre l’activité des tampons par utilisateur depuis le tableau de bord.

Cas d’utilisation

Tampon de bienvenue à l’inscription : Attribution automatique d’un tampon via l’API lorsque l’utilisateur termine son inscription
Récompenses d’achat automatisées : Appel de l’API après paiement pour attribuer des tampons selon le nombre d’achats
Campagnes à durée limitée : Émission de tampons valables uniquement sur une période définie via strtYmd·endYmd
Suivi de participation aux événements : Attribution de tampons pour enregistrer l’historique de participation
Gestion des campagnes de récompense : Attribution de coupons ou avantages selon les tampons accumulés

Différence avec l’API de coupons

L’API de coupons et l’API de tampons sont toutes deux utilisées en marketing, mais leurs objectifs et usages diffèrent clairement.

L’API de coupons est orientée conversion, incitant à l’achat immédiat via des réductions.
L’API de tampons est orientée rétention, en enregistrant les actions des utilisateurs et en favorisant l’engagement récurrent.

1. Objectif

API de coupons → Réduction → Inciter à l’achat (Conversion)
API de tampons → Suivi des actions → Encourager le retour (Retention)

Les coupons sont efficaces pour le chiffre d’affaires à court terme, tandis que les tampons renforcent la fidélisation à long terme.

2. Moment d’utilisation

Coupon → Avant ou pendant le paiement
Tampon → Lors d’une action (visite, participation, etc.)

Le coupon déclenche l’achat immédiat, tandis que le tampon incite à la prochaine action.

3. Structure des données

Les coupons sont basés sur des événements ponctuels.

Usage unique ou limité
Axé sur la réduction
Consommé ou mis à jour à l’utilisation

Les tampons sont cumulables.

Attribuables plusieurs fois
Suivi par utilisateur
Récompense après condition atteinte

En résumé, les coupons sont des déclencheurs uniques, tandis que les tampons sont des données cumulatives.

4. Stratégie marketing

Stratégie basée sur les coupons :

Acquisition de nouveaux utilisateurs
Augmentation du taux de conversion
Promotion de produits

Stratégie basée sur les tampons :

Encourager les visites répétées
Renforcer la fidélité client
Campagnes à long terme

5. Utilisation combinée

Dans la pratique, les deux APIs sont souvent utilisées ensemble.

Exemple :

Accumulation de tampons (ex. 10 visites)
Émission automatique d’un coupon après condition atteinte
Utilisation du coupon pour déclencher l’achat

Ce flux relie Engagement → Rétention → Conversion dans un parcours unifié.

Points à considérer

cardIdx doit correspondre à un identifiant de carte valide
Définir des règles claires pour éviter les doublons par utilisateur
Une mauvaise configuration des périodes peut affecter les performances de la campagne

API de création de tampons (v2)