スタンプ特典利用API (v2)
スタンプ特典利用APIは、すべてのスタンプを達成した後に特典（無料ドリンク、割引など）を利用済みにする機能です。
利用後、そのスタンプは再利用できず、次のサイクルを開始するために新しいスタンプを発行する必要があります。
来店や購入履歴に応じて特典を提供するシステムで利用されます。
このAPIはパーソナルプラン以上で利用できます。
/api/stamp/v2/redeem
{
"stampIdx": 394,
"onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
"processStoreIdx": 22
}Request Parameters
- stampIdx integer required
- スタンプIDX。
- onsiteToken string
-
現場処理用の短期交換トークン。v2はパスワードの平文(
onsitePwd)を受け付けません。
スタンプにonsiteYn = Yが設定されている場合、検証API(Validate)の応答にあるonsiteTokenを そのまま送信してください。
トークンを使うリクエストにはIdempotency-Keyが必須です。同じkeyの再試行は最初の結果を そのまま再生し、別のkeyで同じトークンを使うと400(エラーコード1228)で拒否されます。
検証で処理店舗を指定した場合、このリクエストの処理店舗も同じでなければなりません。 - processStoreIdx integer
-
このリクエストが実際に処理される店舗IDX。送信すると、組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。
処理支店はリクエストでは受け取らず、この店舗からサーバーが確認します。発行店舗(storeIdx)とは異なる値です。
{
"code": 0,
"message": "",
"result": null
}Response Parameters
- code integer
- 応答コード: 0 = 成功、それ以外の値 = エラー
- message string
- 応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
- result null
数値パラメータの検証
数値で受け取るパラメータに数値以外の値や、サーバーが処理できる範囲を超える数値を送ると、リクエストは400(エラーコード653)で直ちに拒否されます。
この場合、スタンプ情報と付与履歴は一切変更されず、イベント記録やWebhook送信も発生しません。失敗レスポンスを受け取った場合は何も保存されていない状態です。
処理店舗の指定
| パラメータ | 意味 | 説明 |
|---|---|---|
processStoreIdx |
処理店舗 | このリクエストが実際に処理される店舗です。任意項目で、送信すると組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。 |
処理支店はリクエストでは受け取りません。指定した店舗が属する支店をサーバーが確認して記録します。
利用可能範囲がBRANCHの場合、確認された処理店舗の支店が利用可能支店と一致するか、
その支店の現場パスワードで認証する必要があります。どちらもない場合は拒否されます。
使用できないパラメータ — branchIdx(発行支店)、
storeIdx(発行店舗)、useScope(利用可能範囲)、
useBranchIdx(利用可能支店)はすでに保存された発行ポリシーのため、このAPIでは変更できません。
一緒に送ると400(エラーコード1227)で拒否されます。
Idempotency-Key
ネットワークエラーで応答を受け取れなかったときに安全に再試行するには、Idempotency-Keyヘッダーに
リクエストごとに一意の値を入れて送信します。本文のrequestIdでも送れますが、
両方を送って値が異なる場合は拒否されます。
使用できる形式は英数字と. _ : -を組み合わせた8〜64文字です。
同じkeyで同じリクエストを再送すると、再処理せずに最初の結果をそのまま返します。 重複して処理されることはなく、Webhookも再送されません。
同じkeyは同じ論理操作の再試行にのみ使用してください。
異なる操作には必ず新しいkeyを使用してください。
同じkeyを異なるリクエスト内容や別の操作に使用すると409で拒否される場合があります。
スタンプ特典利用はどの段階か
スタンプシステムにおける最終段階です。
- スタンプの達成状況を確認
- 特典（報酬）の付与処理
- スタンプを利用済み状態に更新
単なる状態変更ではなく、イベント結果を確定する重要な最終処理です。
スタンプサイクルの完結点
このAPIはスタンプサイクルの最終ステップです。
ユーザーにとっては報酬を受け取る瞬間であり、開発者にとっては1サイクルの完了と次のサイクル開始を意味します。
特典利用後にCreate APIで新しいスタンプを即時発行することで、継続的な利用を促進できます。
スタンプサイクル全体
Create→ スタンプを発行Add Stamp→ 来店・購入で加算Validate→ 完了状況を確認Redeem→ 特典利用処理Create→ 新しいサイクルを開始
店頭認証トークン (onsiteToken)
v2は店頭用パスワードの平文（onsitePwd）を受け付けません。
検証API（Validate）が返したonsiteTokenをそのまま送信してください。
onsitePwdだけを送信した場合や、onsiteTokenと一緒に送信した場合は、
400（エラーコード1227）で拒否されます。
トークンを使用するリクエストではIdempotency-Keyが必須です。
同じIdempotency-Keyで再試行すると、最初の処理結果がそのまま返されます。
同じトークンを別のIdempotency-Keyで再利用すると、
400（エラーコード1228）で拒否されます。
検証した店舗と実際に処理する店舗は同じである必要があります。
検証時にprocessStoreIdxを指定した場合、このリクエストでも同じ店舗を使用する必要があります。
店舗を指定せずに検証したトークンへ、後から店舗を追加することはできません。
有効期限切れ、改ざん、使用済み、バインディング不一致はいずれも1228で応答します。
原因を個別に公開すると、第三者が別のトークンを使って内部状態を推測できるためです。
店頭認証を使用しないリソース（onsiteYn = N）にはトークンは必要ありません。
v1は従来どおりonsitePwdの平文を受け付けます。
利用後の自動化フロー設計
特典利用完了をトリガーに後続処理を自動化できます。
- クーポン生成APIを呼び出して特典を即時発行
- 新しいスタンプを生成して次のサイクルを開始
- Webhookを利用して利用完了通知を送信
このフローを自動化することで、特典付与から再利用促進まで一貫したリワード運用が可能になります。
運用上の重要ポイント
このAPIは単なる機能ではなく、ビジネス結果が確定する重要なポイントです。
- 誤処理により重複報酬が発生する可能性があります
- ユーザーからのクレームやトラブルにつながる可能性があります
- キャンペーンコストの増加につながります
検証→利用の順序維持、サーバー側でのトランザクション制御、ログおよび監査記録の管理を必ず実施してください。