クーポン利用API（オンライン）

API Version

PUT

/api/coupon/v2/redeem

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233",
    "processStoreIdx": 22
}

Request Parameters

cpnNo string required: クーポン番号。
onsiteToken string: 現場処理用の短期交換トークン。v2はパスワードの平文(onsitePwd)を受け付けません。
クーポンにonsiteYn = Yが設定されている場合、検証API(Validate)の応答にあるonsiteTokenをそのまま送信してください。
トークンを使うリクエストにはIdempotency-Keyが必須です。同じkeyの再試行は最初の結果をそのまま再生し、別のkeyで同じトークンを使うと400(エラーコード1228)で拒否されます。
検証で処理店舗を指定した場合、このリクエストの処理店舗も同じでなければなりません。
userId string: ユーザーID。クーポン発行者・利用者を識別するためのID。
クーポンの利用可能回数が 2～5 に設定されている場合は必ず入力してください。
memo string: 内部参照用メモ。ユーザーのIP、クーポン利用先、その他の情報を記録できます。
クーポン利用回数が無制限の場合、userIdの代わりにこのメモを使ってユーザーを区別できます。
processStoreIdx integer: このリクエストが実際に処理される店舗IDX。送信すると、組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。
処理支店はリクエストでは受け取らず、この店舗からサーバーが確認します。発行店舗(storeIdx)とは異なる値です。

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

Response Parameters

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

処理店舗の指定

パラメータ	意味	説明
`processStoreIdx`	処理店舗	このリクエストが実際に処理される店舗です。任意項目で、送信すると組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。

処理支店はリクエストでは受け取りません。指定した店舗が属する支店をサーバーが確認して記録します。

利用可能範囲がBRANCHの場合、確認された処理店舗の支店が利用可能支店と一致するか、その支店の現場パスワードで認証する必要があります。どちらもない場合は拒否されます。

使用できないパラメータ — branchIdx(発行支店)、 storeIdx(発行店舗)、useScope(利用可能範囲)、 useBranchIdx(利用可能支店)はすでに保存された発行ポリシーのため、このAPIでは変更できません。一緒に送ると400(エラーコード1227)で拒否されます。

Idempotency-Key

ネットワークエラーで応答を受け取れなかったときに安全に再試行するには、Idempotency-Keyヘッダーにリクエストごとに一意の値を入れて送信します。本文のrequestIdでも送れますが、両方を送って値が異なる場合は拒否されます。使用できる形式は英数字と. _ : -を組み合わせた8〜64文字です。

同じkeyで同じリクエストを再送すると、再処理せずに最初の結果をそのまま返します。 重複して処理されることはなく、Webhookも再送されません。

同じkeyは同じ論理操作の再試行にのみ使用してください。異なる操作には必ず新しいkeyを使用してください。同じkeyを異なるリクエスト内容や別の操作に使用すると409で拒否される場合があります。

検証APIと併用する方法

クーポン利用APIは状態を変更するため、呼び出し前に検証APIで有効性を確認することを推奨します。

事前に有効なクーポンであることを確認することで、期限切れや利用済みクーポンへの不要な処理を防げます。

基本フローは「検証 → 利用」です。

このAPIを利用する場面

クーポン検証後、実際にクーポンを適用する際に利用します。

決済完了時にクーポンを利用処理する場合
注文確定時に割引適用を記録する場合
店舗や現地での利用処理
重複利用を防ぐための状態更新

つまり、クーポンを実際に消費する最終ステップです。

クーポン利用処理の仕組み

クーポン番号（cpnNo）を基準に、クーポンを利用済み状態に変更します。

利用時に即座に利用回数が減算される
再利用不可の状態に遷移する
ユーザー情報（userId）に基づいて利用履歴を記録
memoを使って追加ログを記録可能

この処理は単なる状態変更ではなく、決済処理に紐づく重要なトランザクションです。

ユーザー識別とメモの活用

userIdはクーポンを利用したユーザーを識別するために使用されます。

利用回数が2～5回に設定されている場合は必須であり、同一ユーザーによる重複利用を防ぐ基準となります。

memoにはユーザーIPや利用場所、リクエスト元などの内部情報を記録できます。
利用回数制限がない場合は、userIdの代わりにmemoでユーザーを識別することも可能です。

店頭認証トークン (onsiteToken)

v2は店頭用パスワードの平文（onsitePwd）を受け付けません。 検証API（Validate）が返したonsiteTokenをそのまま送信してください。 onsitePwdだけを送信した場合や、onsiteTokenと一緒に送信した場合は、 400（エラーコード1227）で拒否されます。

トークンを使用するリクエストではIdempotency-Keyが必須です。同じIdempotency-Keyで再試行すると、最初の処理結果がそのまま返されます。同じトークンを別のIdempotency-Keyで再利用すると、 400（エラーコード1228）で拒否されます。

検証した店舗と実際に処理する店舗は同じである必要があります。 検証時にprocessStoreIdxを指定した場合、このリクエストでも同じ店舗を使用する必要があります。店舗を指定せずに検証したトークンへ、後から店舗を追加することはできません。

有効期限切れ、改ざん、使用済み、バインディング不一致はいずれも1228で応答します。原因を個別に公開すると、第三者が別のトークンを使って内部状態を推測できるためです。

店頭認証を使用しないリソース（onsiteYn = N）にはトークンは必要ありません。 v1は従来どおりonsitePwdの平文を受け付けます。

活用例

EC決済連携：決済完了時にAPIを呼び出し、クーポンを自動適用し割引履歴を記録
店舗での処理：スタッフがQRコードをスキャンし、クーポン番号を取得してAPIで即時利用処理
利用履歴の追跡：memoにIPやリクエスト元を記録し、不正利用や異常パターンを分析
複数回利用クーポン管理：userIdで同一ユーザーの利用回数超過を防止

削除後でも同じクーポンコードで再作成することが可能です。

利用時の注意点

安全性のため、必ず検証APIの後に呼び出してください。
利用処理後はクーポンを再利用できません。
決済失敗時に備え、ロールバック戦略が必要になる場合があります。
重複リクエストによる二重利用を防ぐため、対策を実装してください。

クーポン利用API（Redeem） (v2)