스탬프 도장 제거 API (v1)
스탬프 도장 제거 API는 생성된 스탬프에서 도장을 1개 차감하는 기능을 제공합니다.
정상적인 적립 흐름보다는 오적립 수정, 이벤트 조건 변경, 사용자 클레임 대응 등 예외 상황을 처리하기 위한 보정 도구입니다.
단, 도장 개수는 0 이하로 감소하지 않습니다.
이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.
신규 연동에는 최신 버전인 v2 사용을 권장합니다.
v1는 기존 연동을 유지하기 위한 버전으로, 신규 기능이나 개선 사항은 제공되지 않습니다.
/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
숫자 파라미터 검증
숫자로 받는 파라미터에 숫자가 아닌 값이나 서버가 처리할 수 있는 범위를 넘는 숫자를 보내면 요청은 400(오류 코드 653)으로 즉시 거부됩니다.
이 경우 스탬프 정보와 적립 이력은 전혀 바뀌지 않으며, 이벤트 기록과 Webhook 전송도 발생하지 않습니다. 실패 응답을 받았다면 아무것도 저장되지 않은 상태입니다.
동작 변경 안내. 이전 v1은 이 검증에 걸려도 요청을 그대로 다음 단계까지 진행했습니다. 그래서 다른 파라미터의 오류 메시지로 덮이거나, 응답은 오류인데 스탬프 정보 일부가 실제로 저장되는 경우가 있었습니다. 현재는 최신 버전과 동일하게 처리 전에 400으로 끊습니다.
도장 차감이 필요한 상황
이 API는 자주 호출되는 기능이 아니라 문제 상황을 해결하기 위한 관리 도구입니다.
다음과 같은 경우에 사용됩니다.
- 동일 이벤트가 중복 처리되어 도장이 두 번 적립된 경우
- 시스템 오류로 도장이 잘못 증가된 경우
- 이벤트 조건 변경으로 기존 적립 데이터를 재조정해야 하는 경우
- 잘못된 적립을 취소해야 하는 경우
잘못된 적립 데이터를 방치하면 리워드 비용이 증가하고 이벤트 신뢰도가 하락합니다.
차감 API는 이를 즉시 바로잡는 수단입니다.
도장 추가 API와의 관계
두 API는 반대 방향으로 동작하지만 역할이 명확히 구분됩니다.
Add Stamp→ 정상 이벤트 흐름에서 고객 행동을 기록Remove Stamp→ 예외 상황에서 데이터를 보정·롤백
Add Stamp API를 호출하는 모든 시나리오에서 취소나 실패 케이스를 함께 설계하고,
그 처리 흐름에 Remove Stamp를 연결해 두는 것이 안정적인 스탬프 시스템의 기본 구조입니다.
운영 관점에서의 중요 포인트
스탬프 차감 API는 자주 사용되는 기능이 아니라 문제 상황을 해결하기 위한 핵심 관리 API입니다.
- 잘못된 데이터 방치 시 이벤트 신뢰도 하락
- 과적립 상태 유지 시 리워드 비용 증가
- 사용자 경험 저하 가능성
따라서 반드시 로그 기록 및 관리자 권한 제어와 함께 사용하는 것이 권장됩니다.
사용 시 주의사항
- 도장은 0 이하로 감소하지 않으므로, 차감 전에 검증 API로 현재
stamps값을 먼저 확인하는 것이 권장됩니다. - 반복 호출 시 의도하지 않은 과도한 차감이 발생할 수 있습니다.
- 클라이언트에서 직접 호출하는 구조는 위험합니다. 서버에서 조건을 검증한 후 제한적으로 호출하는 방식으로 설계하세요.
- 차감 이력은 별도로 로그를 기록하고 관리자 권한 제어와 함께 운영하는 것이 권장됩니다.