스템프 도장 제거 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 값을 먼저 확인하는 것이 권장됩니다.
  • 반복 호출 시 의도하지 않은 과도한 차감이 발생할 수 있습니다.
  • 클라이언트에서 직접 호출하는 구조는 위험합니다. 서버에서 조건을 검증한 후 제한적으로 호출하는 방식으로 설계하세요.
  • 차감 이력은 별도로 로그를 기록하고 관리자 권한 제어와 함께 운영하는 것이 권장됩니다.