スタンプ検証API (v2)

スタンプ検証APIは、スタンプの付与・削除・特典利用の前に、スタンプが有効な状態かどうかを確認するための機能です。

スタンプIDXの有効性、有効期間、アクティブ状態、特典がすでに利用済みかを一度に検証できます。

検証に加えて、現在の付与状況やカード情報も返却されるため、ユーザー向けのスタンプ画面の構築に利用できます。

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

API Version

GET

/api/stamp/v2/validate?stampIdx={stampIdx}

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

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

{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "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の平文を返します。

数値パラメータの検証

数値で受け取るパラメータに数値以外の値や、サーバーが処理できる範囲を超える数値を送ると、リクエストは400(エラーコード653)で直ちに拒否されます。

この場合、スタンプ情報と付与履歴は一切変更されず、イベント記録やWebhook送信も発生しません。失敗レスポンスを受け取った場合は何も保存されていない状態です。

処理店舗の指定

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

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

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

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

スタンプ検証の役割

スタンプ検証APIは単なる有効性チェックではありません。
現在の付与状況をもとに、次に取るべきアクションを判断するためのAPIです。

追加付与が可能かどうかの判定
リワード条件の達成確認
キャンペーン参加状況の確認
ユーザーごとの進行状況の取得

つまり、スタンプ検証はキャンペーン進行状態を把握する中核APIです。

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

レスポンス（result）には、スタンプ進行を判断するために必要な情報がすべて含まれています。

これにより、以下の判断が可能です。

現在の付与数（stamps）と最大数（maxStamps）の比較
追加付与の可否判断
リワード条件の達成確認
スタンプ状態（activeYn）の確認
利用可能環境（onsiteYn）の判定
ユーザー情報に基づくパーソナライズ処理

ポイント: 「検証API = 状態取得 + ロジック判断の入力」

レスポンスデータの活用方法

検証APIのレスポンスは、アプリケーションロジックで直接活用されます。

例:

進行状況UIの表示: フロントエンドでリアルタイムの進行状況を表示
操作制御: 状態に応じて付与ボタンの有効／無効を切り替え
リワード表示: 目標達成時に特典を表示
ユーザー状態分岐: 進行状況に応じたロジック処理

つまり、このAPIはUIとビジネスロジックをつなぐ中核データソースです。

クーポン検証APIとの違い

両APIとも詳細な検証データを返しますが、情報の性質が異なります。

クーポン検証は割引方式、割引額、利用回数などの取引データを返します。
スタンプ検証は現在のスタンプ数（stamps）、最大数（maxStamps）、カード名、タイトル、画像URLなどの進行データを返します。

クーポン検証は「今いくら割引されるか」を計算するために使われ、
スタンプ検証は「どれだけ貯まっていて、あとどれくらい必要か」を表示するために使われます。

運用上の重要性

スタンプ検証APIはイベントフローの中心に位置します。

誤ったスタンプ付与の防止
条件未達成時の処理ブロック
ユーザー体験の向上
イベントロジックの安定性確保

検証なしで付与を行うと、データ不整合やイベントエラーが発生する可能性があります。

利用時の注意点

検証結果と実際の付与の間で状態が変化する可能性があります
検証後は速やかに付与APIを呼び出す構成が安全です
クライアント側の検証のみでロジックを完結させることは推奨されません
高トラフィック環境では呼び出し最適化とリトライ設計が必要です