스템프 도장 추가 API

스탬프 도장 추가 API는 생성된 스탬프에 도장을 1개 추가하는 기능을 제공합니다.

고객이 구매, 방문, 특정 행동을 완료했을 때 이 API를 호출하면 해당 스탬프에 도장이 자동으로 적립됩니다.
단, 스탬프 카드에 설정된 최대 도장 수를 초과하면 추가 적립되지 않습니다.

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

PUT

/api/stamp/v1/add 

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required
스템프 IDX. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

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

이 API가 스탬프 시스템의 핵심인 이유

스탬프 생성 API가 고객에게 적립 카드를 발급하는 역할이라면, 도장 추가 API는 고객의 실제 행동을 기록하는 역할입니다.

고객이 매장을 방문하거나 상품을 구매할 때마다 이 API를 호출하면, 별도의 포인트 시스템 없이도 고객 행동 기반의 리워드 프로그램을 완성할 수 있습니다.

결제 완료 이벤트, 상품 구매 완료, 설문 참여 등 어떤 행동이든 API 호출 하나로 도장 적립과 연결됩니다.

최대 도장 수 초과 시 처리 방법

스탬프 카드에 설정된 최대 도장 수에 도달한 상태에서 도장 추가 API를 호출하면 적립되지 않습니다.
이 시점에서의 올바른 처리 순서는 다음과 같습니다.

  1. 검증 API로 현재 stamps와 maxStamps를 확인합니다.
  2. 두 값이 같다면 도장이 모두 채워진 상태입니다.
  3. 수정 API에서 useYn을 Y로 변경해 혜택 사용 처리합니다.
  4. 쿠폰 생성 API를 연계 호출해 리워드를 자동 발급합니다.
  5. 새 스탬프를 생성해 다음 적립 사이클을 시작합니다.

적립 조건과 제한 사항

스탬프 적립은 무조건 증가하지 않습니다.

다음 조건을 만족해야 합니다.

  • 스탬프 활성 상태 (activeYn = Y)
  • 적립 기간 내 (strtYmd ~ endYmd)
  • 최대 적립 수 미도달 (stamps < maxStamps)
  • 사용 완료 상태가 아닐 것

이 조건을 통해 이벤트 정책에 맞는 정확한 적립이 보장됩니다.

활용 예시

  • 방문 적립 이벤트: 사용자가 매장 방문 시 스탬프 1개 적립
  • 구매 리워드 적립: 결제 완료 시 자동으로 스탬프 증가
  • 미션 기반 이벤트: 특정 행동 완료 시 스탬프 지급
  • 출석 체크 시스템: 매일 로그인 시 스탬프 1개 적립

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

스탬프 적립 API는 이벤트 품질을 좌우하는 핵심입니다.

  • 잘못된 적립은 이벤트 신뢰도를 떨어뜨립니다
  • 중복 호출 시 과도한 적립이 발생할 수 있습니다
  • 사용자 경험과 직접 연결됩니다

따라서 반드시 검증 + 서버 단 로직 제어와 함께 사용해야 합니다.