스탬프 혜택 사용 API (v2)

스탬프 혜택 사용 API는 고객이 모든 도장을 채운 후 제공된 혜택(무료 음료, 할인 등)을 사용 완료 상태로 처리하는 기능을 제공합니다.

혜택 사용 완료 후 해당 스탬프는 더 이상 사용할 수 없으며, 고객은 새로운 스탬프를 발급받아야 합니다.
고객의 방문·구매 이력에 따라 스탬프를 적립하고 혜택을 처리하는 시스템에 적용됩니다.

이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.

API Version

PUT

/api/stamp/v2/redeem

Request
Response

{
    "stampIdx": 394,
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required: 스탬프 IDX.
onsiteToken string: 현장 처리용 단기 교환 증표. v2는 비밀번호 평문(onsitePwd)을 받지 않습니다.
스탬프에 onsiteYn = Y가 설정돼 있으면, 검증 API(Validate) 응답의 onsiteToken을 그대로 보내세요.
증표를 쓰는 요청에는 Idempotency-Key가 필수입니다. 같은 key의 재시도는 최초 결과를 그대로 재생하고, 다른 key로 같은 증표를 다시 쓰면 400(오류 코드 1228)으로 거부됩니다.
검증에서 처리 매장을 지정했다면 이 요청의 처리 매장도 같아야 합니다. 매장 없이 검증한 증표에 매장을 새로 붙일 수도 없습니다.
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로 새 스탬프를 즉시 발급하면 고객의 재참여를 자연스럽게 유도할 수 있습니다.

스탬프 전체 사이클 흐름

Create → 고객에게 스탬프 발급
Add Stamp → 방문·구매 시 도장 적립
Validate → 도장이 모두 찼는지 확인
Redeem → 혜택 사용 완료 처리
Create → 새 스탬프 발급으로 다음 사이클 시작

현장 인증 토큰 (onsiteToken)

v2는 현장 비밀번호 평문(onsitePwd)을 받지 않습니다. 검증 API(Validate)가 반환한 onsiteToken을 그대로 전송하세요. onsitePwd만 보내거나 onsiteToken과 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

토큰을 사용하는 요청에는 Idempotency-Key가 필수입니다. 동일한 Idempotency-Key로 재시도하면 최초 처리 결과를 그대로 반환합니다. 같은 토큰을 다른 Idempotency-Key로 다시 사용하면 400(오류 코드 1228)으로 거부됩니다.

검증한 매장과 실제 처리 매장이 같아야 합니다. 검증 시 processStoreIdx를 지정했다면 이 요청에서도 같은 매장을 사용해야 합니다. 매장을 지정하지 않고 검증한 토큰에는 이후 매장을 새로 지정할 수 없습니다.

만료, 변조, 이미 사용된 토큰, 바인딩 불일치는 모두 1228로 응답합니다. 원인을 구분해 노출하면 제3자가 다른 토큰을 이용해 내부 상태를 추측할 수 있기 때문입니다.

현장 인증을 사용하지 않는 리소스(onsiteYn = N)에는 토큰이 필요하지 않습니다. v1은 기존과 동일하게 onsitePwd 평문을 받습니다.

혜택 사용 후 자동화 흐름 설계

혜택 사용 처리가 완료된 시점을 트리거로 후속 작업을 자동화할 수 있습니다.

쿠폰 생성 API를 연계 호출해 리워드 쿠폰을 즉시 발급합니다.
새 스탬프를 즉시 생성해 다음 적립 사이클을 바로 시작합니다.
웹훅을 활용해 혜택 사용 완료 알림을 고객에게 전송합니다.

이 흐름을 API로 자동화하면 직원 개입 없이 혜택 지급부터 재참여 유도까지 완성된 리워드 프로그램을 운영할 수 있습니다.

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

이 API는 단순 기능이 아니라 비즈니스 결과가 확정되는 순간입니다.

잘못 처리 시 중복 보상 발생
사용자 클레임 발생 가능
이벤트 비용 증가

따라서 반드시, 검증 → 사용 순서 유지, 서버 단 트랜잭션 처리, 로그 및 감사 기록 관리가 필요합니다.