スタンプ追加API (v2)

スタンプ追加APIは、既存のスタンプに対して1つスタンプを加算する機能です。

ユーザーが購入・来店・特定のアクションを完了した際に、このAPIを呼び出すことでスタンプが自動的に1つ追加されます。
スタンプカードで設定された最大数に達している場合は、それ以上追加されません。

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

API Version

PUT

/api/stamp/v2/add

Request
Response

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required: スタンプIDX。
stamps integer: 付与(差し引き)するスタンプ数。省略時は1で、0より大きい必要があります。
カードの上限を超える分や0未満になる分はサーバーが調整します。実際の変化量が0の場合は履歴もWebhookも作成されません。
processStoreIdx integer: このリクエストが実際に処理される店舗IDX。送信すると、組織の所有・有効状態・権限をサーバーが確認したうえで処理履歴に記録します。
処理支店はリクエストでは受け取らず、この店舗からサーバーが確認します。発行店舗(storeIdx)とは異なる値です。

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

Response Parameters

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

数値パラメータの検証

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

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

処理店舗の指定

パラメータ	意味	説明
`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を呼び出すことで、ポイントシステムなしでも行動ベースのリワード施策を実現できます。

決済完了、商品購入、アンケート参加など、あらゆる行動を1回のAPI呼び出しでスタンプ付与に連携できます。

最大スタンプ数到達時の処理方法

カードに設定された最大スタンプ数に達した場合、それ以上は追加されません。
推奨される処理フローは以下の通りです。

検証APIで stamps と maxStamps を確認
両者が同じ場合、スタンプは満了状態です
更新API で useYn を Y に変更し特典利用済みに設定
スタンプ作成API を呼び出し、新しいサイクルを開始
新しいスタンプで次の積立サイクルを開始

付与条件と制限事項

スタンプ付与は常に実行されるわけではありません。

以下の条件を満たす必要があります。

スタンプが有効状態であること（activeYn = Y）
有効期間内であること（strtYmd ~ endYmd）
最大数に達していないこと（stamps < maxStamps）
すでに利用済みでないこと

これらの条件により、キャンペーンルールに沿った正確な付与が保証されます。

活用例

来店付与イベント: 来店時にスタンプを1つ付与
購入リワード: 決済完了後にスタンプを自動付与
ミッション型イベント: 特定の行動完了時にスタンプ付与
デイリーチェックイン: 毎日のログインでスタンプ1つ付与

運用上の重要ポイント

スタンプ付与APIはキャンペーン品質を左右する重要な要素です。

誤った付与はキャンペーンの信頼性を低下させます
重複したAPI呼び出しにより過剰付与が発生する可能性があります
ユーザー体験に直接影響します

必ず検証とサーバー側ロジック制御と組み合わせて使用してください。