スタンプ検証API
スタンプ検証APIは、スタンプの付与・削除・特典利用の前に、スタンプが有効な状態かどうかを確認するための機能です。
スタンプIDXの有効性、有効期間、アクティブ状態、特典がすでに利用済みかを一度に検証できます。
検証に加えて、現在の付与状況やカード情報も返却されるため、ユーザー向けのスタンプ画面の構築に利用できます。
このAPIはパーソナルプラン以上で利用できます。
/api/stamp/v1/validate?stampIdx={stampIdx}
GET /api/stamp/v1/validate
?stampIdx=274
Request Parameters
- stampIdx integer required
- スタンプIDX。
{
"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",
"onsitePwd": "123456",
"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",
"payloadVersion": "v1"
}
}Response Parameters
- codeinteger
- レスポンスコード: 0 = 成功、それ以外 = エラー
- messagestring
- レスポンスメッセージ。レスポンスコードが0以外の場合、エラー内容のメッセージが返されます。
- resultobject
-
検証に成功すると、レスポンスにスタンプ情報が含まれます。
検証に失敗した場合、レスポンス値はnullとなり、エラーメッセージで原因を確認できます。 - stampIdx integer
- スタンプIDX。
- domain string
- スタンプドメイン。
- cardIdx integer
- カードIDX。
- cardNm string
- カード名。
- cardTtl string
- カードタイトル。
- stamps integer
- 現在までに集めたスタンプの数。
- maxStamps integer
- カードで設定された最大スタンプ数。
- stampUrl string
- スタンプページのURL。
- url string
- スタンプページのボタンをクリックした際に移動するURL。
- strtYmd date
- スタンプの有効開始日。
- endYmd date
- スタンプの有効期限。
- onsiteYn string
-
Enum:
YN
-
店舗でのスタンプ付与を有効にするかどうかを示します。
値が
Yの場合、店舗スタッフが現場でスタンプを押すことができます。 - onsitePwd string
-
店舗スタンプ用パスワード。
現場スタンプが有効（
Y）の場合、スタンプ特典利用API呼び出し時に必須です。 - memo string
- 内部参照用メモ。
- activeYn string
-
Enum:
YN
- スタンプの有効状態を示します。 無効化されている場合、顧客はスタンプを利用できません。
- userId string
-
ユーザーID。スタンプ発行対象者の管理に使用します。
一般的に、ウェブサイト会員のログインIDを入力します。
設定されていない場合は、システムによって自動的にユーザーIDが生成されます。 - userNm string
- ユーザー名。内部管理用。
- userPhnno string
- ユーザーの電話番号。内部管理用。
- userEml string
- ユーザーのメールアドレス。内部管理用。
- userEtc1 string
- 追加の内部管理フィールド。
- userEtc2 string
- 追加の内部管理フィールド。
- stampImgUrl string
- スタンプ画像のURL。
- regYmdt datetime
- スタンプ作成日時。例: 2025-07-21 11:50:20
スタンプ検証の役割
スタンプ検証APIは単なる有効性チェックではありません。
現在の付与状況をもとに、次に取るべきアクションを判断するためのAPIです。
- 追加付与が可能かどうかの判定
- リワード条件の達成確認
- キャンペーン参加状況の確認
- ユーザーごとの進行状況の取得
つまり、スタンプ検証はキャンペーン進行状態を把握する中核APIです。
検証結果から判断できること
レスポンス（result）には、スタンプ進行を判断するために必要な情報がすべて含まれています。
これにより、以下の判断が可能です。
- 現在の付与数（
stamps）と最大数（maxStamps）の比較 - 追加付与の可否判断
- リワード条件の達成確認
- スタンプ状態（
activeYn）の確認 - 利用可能環境（
onsiteYn）の判定 - ユーザー情報に基づくパーソナライズ処理
ポイント: 「検証API = 状態取得 + ロジック判断の入力」
レスポンスデータの活用方法
検証APIのレスポンスは、アプリケーションロジックで直接活用されます。
例:
- 進行状況UIの表示: フロントエンドでリアルタイムの進行状況を表示
- 操作制御: 状態に応じて付与ボタンの有効／無効を切り替え
- リワード表示: 目標達成時に特典を表示
- ユーザー状態分岐: 進行状況に応じたロジック処理
つまり、このAPIはUIとビジネスロジックをつなぐ中核データソースです。
クーポン検証APIとの違い
両APIとも詳細な検証データを返しますが、情報の性質が異なります。
クーポン検証は割引方式、割引額、利用回数などの取引データを返します。
スタンプ検証は現在のスタンプ数（stamps）、最大数（maxStamps）、カード名、タイトル、画像URLなどの進行データを返します。
クーポン検証は「今いくら割引されるか」を計算するために使われ、
スタンプ検証は「どれだけ貯まっていて、あとどれくらい必要か」を表示するために使われます。
運用上の重要性
スタンプ検証APIはイベントフローの中心に位置します。
- 誤ったスタンプ付与の防止
- 条件未達成時の処理ブロック
- ユーザー体験の向上
- イベントロジックの安定性確保
検証なしで付与を行うと、データ不整合やイベントエラーが発生する可能性があります。
利用時の注意点
- 検証結果と実際の付与の間で状態が変化する可能性があります
- 検証後は速やかに付与APIを呼び出す構成が安全です
- クライアント側の検証のみでロジックを完結させることは推奨されません
- 高トラフィック環境では呼び出し最適化とリトライ設計が必要です