スタンプ追加API (v1)

スタンプ追加APIは、既存のスタンプに対して1つスタンプを加算する機能です。

ユーザーが購入・来店・特定のアクションを完了した際に、このAPIを呼び出すことでスタンプが自動的に1つ追加されます。
スタンプカードで設定された最大数に達している場合は、それ以上追加されません。

このAPIはパーソナルプラン以上で利用できます。

v1（レガシー）ドキュメントです。

新規連携には、最新バージョンである v2 のご利用を推奨します。
v1 は既存連携を維持するためのバージョンであり、新機能や改善は提供されません。

API Version

PUT

/api/stamp/v1/add

Request
Response

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required: スタンプIDX。

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

Response Parameters

code integer: 応答コード: 0 = 成功、それ以外の値 = エラー
message string: 応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
result null

数値パラメータの検証

数値で受け取るパラメータに数値以外の値や、サーバーが処理できる範囲を超える数値を送ると、リクエストは400(エラーコード653)で直ちに拒否されます。

この場合、スタンプ情報と付与履歴は一切変更されず、イベント記録やWebhook送信も発生しません。失敗レスポンスを受け取った場合は何も保存されていない状態です。

動作変更のお知らせ。 以前のv1はこの検証に失敗してもリクエストをそのまま次の段階まで進めていました。そのため他のパラメータのエラーメッセージで上書きされたり、レスポンスはエラーなのにスタンプ情報の一部が実際に保存されることがありました。現在は最新バージョンと同じく、処理の前に400で中断します。

このAPIがスタンプシステムの中核である理由

スタンプ作成APIがカードを発行する役割であるのに対し、スタンプ追加APIはユーザーの実際の行動を記録する役割を担います。

ユーザーが来店や購入を行うたびにこのAPIを呼び出すことで、ポイントシステムなしでも行動ベースのリワード施策を実現できます。

決済完了、商品購入、アンケート参加など、あらゆる行動を1回のAPI呼び出しでスタンプ付与に連携できます。

最大スタンプ数到達時の処理方法

カードに設定された最大スタンプ数に達した場合、それ以上は追加されません。
推奨される処理フローは以下の通りです。

検証APIで stamps と maxStamps を確認
両者が同じ場合、スタンプは満了状態です
更新API で useYn を Y に変更し特典利用済みに設定
スタンプ作成API を呼び出し、新しいサイクルを開始
新しいスタンプで次の積立サイクルを開始

付与条件と制限事項

スタンプ付与は常に実行されるわけではありません。

以下の条件を満たす必要があります。

スタンプが有効状態であること（activeYn = Y）
有効期間内であること（strtYmd ~ endYmd）
最大数に達していないこと（stamps < maxStamps）
すでに利用済みでないこと

これらの条件により、キャンペーンルールに沿った正確な付与が保証されます。

活用例

来店付与イベント: 来店時にスタンプを1つ付与
購入リワード: 決済完了後にスタンプを自動付与
ミッション型イベント: 特定の行動完了時にスタンプ付与
デイリーチェックイン: 毎日のログインでスタンプ1つ付与

運用上の重要ポイント

スタンプ付与APIはキャンペーン品質を左右する重要な要素です。

誤った付与はキャンペーンの信頼性を低下させます
重複したAPI呼び出しにより過剰付与が発生する可能性があります
ユーザー体験に直接影響します

必ず検証とサーバー側ロジック制御と組み合わせて使用してください。