クーポン検証API（オンライン）

API Version

GET

/api/coupon/v2/validate?cpnNo={cpnNo}

Request
Response


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNostringrequired: クーポン番号。
processStoreIdx integer: このリクエストが実際に処理される店舗IDX。送信すると、組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。
処理支店はリクエストでは受け取らず、この店舗からサーバーが確認します。発行店舗(storeIdx)とは異なる値です。

{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

codeinteger: レスポンスコード: 0 = 成功、それ以外 = エラー
messagestring: レスポンスメッセージ。レスポンスコードが0以外の場合、エラー内容のメッセージが返されます。
resultobject: 検証成功時: 応答にはクーポン情報が返されます。
検証失敗時: 応答はnullとなり、エラーメッセージで確認できます。

店頭認証トークン (onsiteToken)

v2の検証APIレスポンスには、店頭用パスワードの平文（onsitePwd）は含まれません。 代わりに、180秒間有効なonsiteTokenを返します。

目的は認証強度を高めることではなく、平文パスワードの露出を最小限に抑えることです。 検証API自体はパスワードを確認しないため、このトークンが新たな認証要素を追加するわけではありません。代わりに、短い有効期限、1回限りの使用、コンテキストへのバインドによって再利用範囲を制限します。

項目	値
有効時間	180秒。有効時間は`onsiteTokenExpiresIn`としてあわせて返されます。
使用回数	1回。使用後は、同じ`Idempotency-Key`による再試行の場合にのみ最初の処理結果を返します。
バインディング	組織、APIキーのアカウント、リソース、操作、検証時に確認した処理店舗
適用対象	クーポン利用、スタンプ特典利用、`useYn = Y`によるスタンプ更新

店頭認証を使用しないリソース（onsiteYn = N）にはトークンを発行しません。 v1の検証APIは従来どおりonsitePwdの平文を返します。

処理店舗の指定

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

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

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

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

検証結果から判断できること

このAPIは単なる「利用可否」の判定にとどまらず、
クーポンの詳細データをもとに開発者が独自のロジックを構築できるよう設計されています。

レスポンス（result）を利用することで、以下の判断が可能です。

割引適用の可否および割引額の算出
特定ユーザー向けクーポンかどうかの判定（userId, userEml）
利用回数制限の超過有無（useCnt, useLimit）
クーポンの有効・無効（開始前／期限切れ）の判定（strtYmd, endYmd）
特定条件（オンライン／オフラインなど）の適用可否（onsiteYn）
適用後の遷移先URLの取得（url）

つまり、単なる結果ではなく、
アプリケーションレベルで柔軟にロジックを構築できるデータ指向APIです。

クーポン検証の仕組み

クーポンコード（cpNo）を基準に、複数の条件を総合的に検証します。

存在有無
有効期間
利用制限
ユーザー条件
適用可能な環境

検証結果は単なるBooleanではなく、構造化されたデータとして返されます。

応答データの活用方法

resultオブジェクトには、クーポンの主要な情報がすべて含まれています。

このデータをもとに、以下のような処理を実装できます。

フロントエンドでの割引額のリアルタイム計算と表示
特定ユーザーへの利用制限の適用
決済金額に応じた条件分岐の実装
クーポン状態に応じたUIメッセージ表示（期限切れ・利用済みなど）

活用例

決済前の事前チェック：ユーザーがクーポンコードを入力した際に検証し、有効な場合のみ割引を適用
ユーザー向けメッセージ：検証結果に応じて適切なメッセージを表示（期限切れ・利用済みなど）
金額ベースの割引計算：レスポンスの割引情報（disc, discType）を使って最終支払額を算出

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

利用時の注意点

検証結果は取得時点の状態を示しており、実際の利用時には変化する可能性があります。
必ず「検証 → 利用（Redeem）」のフローで実装してください。
クライアント側の検証結果のみに依存するのはセキュリティ上危険です。
割引計算はサーバー側で再検証し、正確性と安全性を確保してください。

クーポン検証API (v2)