スタンプ特典利用API

スタンプ特典利用APIは、すべてのスタンプを達成した後に特典（無料ドリンク、割引など）を利用済みにする機能です。

利用後、そのスタンプは再利用できず、次のサイクルを開始するために新しいスタンプを発行する必要があります。
来店や購入履歴に応じて特典を提供するシステムで利用されます。

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

PUT

/api/stamp/v1/redeem 

{
    "stampIdx": 394,
    "onsitePwd": "12345"
}

Request Parameters

stampIdx integer required
スタンプIDX。
onsitePwd string
店舗で使用する従業員認証用パスワードです。
スタンプが onsiteYn = Y に設定されている場合のみ必須項目となり、
従業員が特典利用（例：無料ドリンク交換など）を承認する際に入力します。
入力時は Validate API で返される onsitePwd の値を参照してください。 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

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

スタンプ特典利用はどの段階か

スタンプシステムにおける最終段階です。

  • スタンプの達成状況を確認
  • 特典（報酬）の付与処理
  • スタンプを利用済み状態に更新

単なる状態変更ではなく、イベント結果を確定する重要な最終処理です。

スタンプサイクルの完結点

このAPIはスタンプサイクルの最終ステップです。

ユーザーにとっては報酬を受け取る瞬間であり、開発者にとっては1サイクルの完了と次のサイクル開始を意味します。

特典利用後にCreate APIで新しいスタンプを即時発行することで、継続的な利用を促進できます。

スタンプサイクル全体

  1. Create → スタンプを発行
  2. Add Stamp → 来店・購入で加算
  3. Validate → 完了状況を確認
  4. Redeem → 特典利用処理
  5. Create → 新しいサイクルを開始

店頭（現地）スタンプ処理方法

onsitePwdは、スタンプに現地認証用パスワード（onsiteYn = Y）が設定されている場合のみ必要です。

店舗スタッフが特典利用を承認する際に入力し、不正利用を防止します。

検証APIで返されるonsitePwdを使用してください。
パスワードが未設定の場合、このフィールドは省略できます。

利用後の自動化フロー設計

特典利用完了をトリガーに後続処理を自動化できます。

  • クーポン生成APIを呼び出して特典を即時発行
  • 新しいスタンプを生成して次のサイクルを開始
  • Webhookを利用して利用完了通知を送信

このフローを自動化することで、特典付与から再利用促進まで一貫したリワード運用が可能になります。

運用上の重要ポイント

このAPIは単なる機能ではなく、ビジネス結果が確定する重要なポイントです。

  • 誤処理により重複報酬が発生する可能性があります
  • ユーザーからのクレームやトラブルにつながる可能性があります
  • キャンペーンコストの増加につながります

検証→利用の順序維持、サーバー側でのトランザクション制御、ログおよび監査記録の管理を必ず実施してください。