스탬프 도장 제거 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이면 이력도 웹훅도 만들지 않습니다.
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로 같은 요청을 다시 보내면 다시 처리하지 않고 최초 결과를 그대로 돌려줍니다. 중복으로 처리되지 않으며 웹훅도 다시 발송되지 않습니다.

같은 key는 같은 논리 작업의 재시도에만 사용하세요. 서로 다른 작업에는 반드시 새 key를 사용해야 합니다. 같은 key를 다른 요청 내용이나 다른 작업에 사용하면 409로 거부될 수 있습니다.

도장 차감이 필요한 상황

이 API는 자주 호출되는 기능이 아니라 문제 상황을 해결하기 위한 관리 도구입니다.
다음과 같은 경우에 사용됩니다.

동일 이벤트가 중복 처리되어 도장이 두 번 적립된 경우
시스템 오류로 도장이 잘못 증가된 경우
이벤트 조건 변경으로 기존 적립 데이터를 재조정해야 하는 경우
잘못된 적립을 취소해야 하는 경우

잘못된 적립 데이터를 방치하면 리워드 비용이 증가하고 이벤트 신뢰도가 하락합니다.
차감 API는 이를 즉시 바로잡는 수단입니다.

도장 추가 API와의 관계

두 API는 반대 방향으로 동작하지만 역할이 명확히 구분됩니다.

Add Stamp → 정상 이벤트 흐름에서 고객 행동을 기록
Remove Stamp → 예외 상황에서 데이터를 보정·롤백

Add Stamp API를 호출하는 모든 시나리오에서 취소나 실패 케이스를 함께 설계하고,
그 처리 흐름에 Remove Stamp를 연결해 두는 것이 안정적인 스탬프 시스템의 기본 구조입니다.

운영 관점에서의 중요 포인트

스탬프 차감 API는 자주 사용되는 기능이 아니라 문제 상황을 해결하기 위한 핵심 관리 API입니다.

잘못된 데이터 방치 시 이벤트 신뢰도 하락
과적립 상태 유지 시 리워드 비용 증가
사용자 경험 저하 가능성

따라서 반드시 로그 기록 및 관리자 권한 제어와 함께 사용하는 것이 권장됩니다.

사용 시 주의사항

도장은 0 이하로 감소하지 않으므로, 차감 전에 검증 API로 현재 stamps 값을 먼저 확인하는 것이 권장됩니다.
반복 호출 시 의도하지 않은 과도한 차감이 발생할 수 있습니다.
클라이언트에서 직접 호출하는 구조는 위험합니다. 서버에서 조건을 검증한 후 제한적으로 호출하는 방식으로 설계하세요.
차감 이력은 별도로 로그를 기록하고 관리자 권한 제어와 함께 운영하는 것이 권장됩니다.