スタンプ減算API

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

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

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

PUT

/api/stamp/v1/remove 

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required
スタンプIDX。 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

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

減算が必要なケース

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

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

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

追加APIとの関係

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

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

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

運用上の重要ポイント

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

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

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

利用時の注意点

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