クーポン検証API

Vivoldiのクーポン検証APIは、クーポン利用処理の前に有効性を確認するための機能です。

利用可否の確認だけでなく、割引情報、利用条件、ユーザーデータも取得できるため、柔軟なビジネスロジックに対応できます。

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

GET

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


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNostringrequired
クーポン番号。 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake 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",
        "onsitePwd": "12345",
        "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"
    }
}

Response Parameters

codeinteger
レスポンスコード: 0 = 成功、それ以外 = エラー
messagestring
レスポンスメッセージ。レスポンスコードが0以外の場合、エラー内容のメッセージが返されます。
resultobject
検証成功時: 応答にはクーポン情報が返されます。
検証失敗時: 応答はnullとなり、エラーメッセージで確認できます。
cpnNostring
クーポン番号。
domain string
クーポンドメイン。
nmstring
クーポン名。
discTypeIdxinteger
割引タイプ。（457: 割引率 %, 458: 金額割引）
discdouble
割引率（457）の場合: 1〜100%の範囲。金額割引（458）の場合: 金額を入力。
discCurrencystring
通貨単位。金額割引（discTypeIdx:458）を使用する場合は必須。
formatDiscCurrencystring
通貨記号。
strtYmddate
クーポン有効開始日。
endYmddate
クーポン有効期限日。
useLimitinteger
クーポン利用可能回数。（0: 無制限、1〜5: 制限回数）
imgUrlstring
クーポン画像URL。
onsiteYnstring
店舗用クーポンの有無。クーポンページに 「クーポンを使用」ボタン を表示するかどうか。
オフライン店舗でスタッフがクーポンを処理する際に必要。
onsitePwd string
現場クーポンのパスワード。
現場クーポンが有効（Y）の場合、クーポン利用APIを呼び出す際に必須です。
memostring
内部参照用メモ。
urlstring
URLを入力すると、クーポンページに 「クーポンを使いに行く」ボタン が表示されます。
ボタンまたはクーポン画像をクリックすると、そのURLにリダイレクトされます。
userIdstring
クーポン発行対象者の管理に使用。
クーポン利用可能回数が2〜5に設定されている場合は必須。
一般的にはウェブサイト会員のログインIDまたは英字の名前を入力。
userNmstring
クーポン利用者名。内部管理用。
userPhnnostring
クーポン利用者の連絡先。内部管理用。
userEmlstring
クーポン利用者のメールアドレス。内部管理用。
userEtc1string
内部追加管理用フィールド。
userEtc2string
内部追加管理用フィールド。
useCntinteger
クーポン利用回数。
regYmdtdatetime
クーポン作成日時。例: 2025-07-21 11:50:20

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

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

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

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

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

クーポン検証の仕組み

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

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

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

応答データの活用方法

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

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

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

活用例

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

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

利用時の注意点

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