스탬프 혜택 사용 API (v1)

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

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

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

v1(레거시) 문서입니다.

신규 연동에는 최신 버전인 v2 사용을 권장합니다.
v1는 기존 연동을 유지하기 위한 버전으로, 신규 기능이나 개선 사항은 제공되지 않습니다.

API Version

PUT

/api/stamp/v1/redeem

Request
Response

{
    "stampIdx": 394,
    "onsitePwd": "12345"
}

Request Parameters

stampIdx integer required: 스탬프 IDX.
onsitePwd string: 현장 적립용 스탬프에서 사용되는 직원 인증 비밀번호입니다.
스탬프가 onsiteYn = Y로 설정된 경우에만 필수 입력 항목이며, 매장 직원이 고객의 혜택 사용(예: 무료 음료 교환 등)을 승인할 때 이 값을 입력해야 합니다.
비밀번호는 Validate API 호출 시 반환되는 onsitePwd 값을 참고하여 입력하세요.

{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer: 응답 코드: 0 = 성공, 그 외 값 = 오류
message string: 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result null

숫자 파라미터 검증

숫자로 받는 파라미터에 숫자가 아닌 값이나 서버가 처리할 수 있는 범위를 넘는 숫자를 보내면 요청은 400(오류 코드 653)으로 즉시 거부됩니다.

이 경우 스탬프 정보와 적립 이력은 전혀 바뀌지 않으며, 이벤트 기록과 Webhook 전송도 발생하지 않습니다. 실패 응답을 받았다면 아무것도 저장되지 않은 상태입니다.

동작 변경 안내. 이전 v1은 이 검증에 걸려도 요청을 그대로 다음 단계까지 진행했습니다. 그래서 다른 파라미터의 오류 메시지로 덮이거나, 응답은 오류인데 스탬프 정보 일부가 실제로 저장되는 경우가 있었습니다. 현재는 최신 버전과 동일하게 처리 전에 400으로 끊습니다.

스탬프 혜택 사용은 어떤 단계인가요?

스탬프 시스템의 마지막 단계입니다.

적립 완료 상태 확인
혜택(보상) 지급 처리
스탬프 사용 완료 상태 전환

즉, 단순 상태 변경이 아니라 이벤트 결과를 확정하는 최종 단계입니다.

스탬프 적립 사이클의 완결점

이 API는 스탬프 시스템 전체 흐름의 마지막 단계입니다.

고객 관점에서 보면 “열심히 모은 도장으로 드디어 혜택을 받는 순간”이고, 개발자 관점에서 보면 한 사이클이 완료되고 다음 사이클이 시작되는 전환점입니다.

혜택 사용 API를 호출한 후 스탬프 생성 API로 새 스탬프를 즉시 발급하면 고객의 재참여를 자연스럽게 유도할 수 있습니다.

스탬프 전체 사이클 흐름

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

매장(현장) 적립용 스탬프 처리 방법

onsitePwd는 스탬프에 현장 적립용 비밀번호(onsiteYn = Y)가 설정된 경우에만 필요한 필드입니다.

매장 직원이 고객의 혜택 사용을 승인할 때 이 값을 입력해 무단 혜택 사용을 방지합니다.

비밀번호는 검증 API(Validate) 호출 시 반환되는 onsitePwd 값을 참고하여 입력하세요.
비밀번호가 설정되지 않은 스탬프라면 이 필드는 생략할 수 있습니다.

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

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

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

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

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

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

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

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