스탬프 혜택 사용 API

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

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

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

PUT

/api/stamp/v1/redeem 

{
    "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

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

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

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

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

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

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

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

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

스탬프 전체 사이클 흐름

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

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

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

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

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

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

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

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

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

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

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

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

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