スタンプ減算API (v1)

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

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

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

v1（レガシー）ドキュメントです。

新規連携には、最新バージョンである v2 のご利用を推奨します。
v1 は既存連携を維持するためのバージョンであり、新機能や改善は提供されません。

API Version

PUT

/api/stamp/v1/remove

Request
Response

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required: スタンプIDX。

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

Response Parameters

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

数値パラメータの検証

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

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

動作変更のお知らせ。 以前のv1はこの検証に失敗してもリクエストをそのまま次の段階まで進めていました。そのため他のパラメータのエラーメッセージで上書きされたり、レスポンスはエラーなのにスタンプ情報の一部が実際に保存されることがありました。現在は最新バージョンと同じく、処理の前に400で中断します。

減算が必要なケース

このAPIは頻繁に使用するものではなく、データ問題を解決するための管理ツールです。
主に以下のケースで使用されます。

同一イベントが重複処理され、スタンプが二重付与された場合
システムエラーによりスタンプが誤って増加した場合
キャンペーン条件の変更により既存データの調整が必要な場合
誤付与を取り消す必要がある場合

誤ったデータを放置するとコスト増加や信頼低下につながります。
減算APIはこれを即時に修正する手段です。

追加APIとの関係

両APIは逆方向に動作しますが、役割は明確に分かれています。

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

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

運用上の重要ポイント

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

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

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

利用時の注意点

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