スタンプ追加API

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

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

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

PUT

/api/stamp/v1/add 

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required
スタンプIDX。 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

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

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

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

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

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

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

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

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

付与条件と制限事項

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

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

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

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

活用例

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

運用上の重要ポイント

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

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

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