スタンプ減算API (v2)

スタンプ減算APIは、既存のスタンプの数を1つ減らす機能です。

通常の付与フローではなく、誤付与の修正、キャンペーン条件の変更、ユーザー対応などの例外処理で使用されます。
スタンプ数が0未満になることはありません。

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

API Version

PUT

/api/stamp/v2/remove

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は逆方向に動作しますが、役割は明確に分かれています。

Add Stamp → 通常フローでユーザー行動を記録
Remove Stamp → 例外時にデータを補正・ロールバック

Add Stamp APIを利用するすべてのケースで、キャンセルや失敗処理を設計し、
その処理フローにRemove Stampを組み込むことが、安定したシステム構築の基本です。

運用上の重要ポイント

スタンプ減算APIは頻繁に使用するものではなく、データ問題を解決するための重要な管理APIです。

誤ったデータを放置すると信頼性が低下します
過剰付与はリワードコストの増加につながります
ユーザー体験に悪影響を与える可能性があります

監査ログと厳格な管理者権限の制御と併用してください。

利用時の注意点

スタンプ数は0未満にはなりません。減算前に検証APIでstampsを確認してください
繰り返し呼び出すと過剰な減算が発生する可能性があります
クライアントから直接呼び出さず、サーバー側で制御してください
減算履歴はログとして保存し、管理者権限で保護してください