스템프 검증 API

스탬프 검증 API는 도장 추가, 도장 제거, 혜택 사용 처리 전에 스탬프가 유효한 상태인지 확인하는 기능을 제공합니다.

스탬프 IDX의 유효성, 유효기간, 활성화 여부, 이미 혜택이 사용된 스탬프인지를 한 번에 검증합니다.

단순 유효성 확인을 넘어 현재 적립 현황과 카드 정보까지 함께 반환되므로, 고객에게 보여줄 스탬프 화면을 구성할 수 있습니다.

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

GET

/api/stamp/v1/validate?stampIdx={stampIdx} 


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
스템프 IDX. 
{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsitePwd": "123456",
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "payloadVersion": "v1"
    }
}

Response Parameters

code integer
응답 코드: 0 = 성공, 그 외 값 = 오류
message string
응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result object
검증에 성공하면 응답값에 스템프 정보가 포함되어 반환됩니다.
검증에 실패하면 응답값은 null이며, 오류 메시지를 통해 원인을 확인할 수 있습니다.
stampIdx integer
스템프 IDX.
domain string
스템프 도메인.
cardIdx integer
카드 IDX.
cardNm string
카드 이름.
cardTtl string
카드 제목.
stamps integer
현재까지 적립된 도장 수.
maxStamps integer
카드의 최대 도장 수.
stampUrl string
스템프 페이지의 URL.
url string
스템프 페이지에서 버튼 클릭 시 이동될 URL.
strtYmd date
스템프 유효 시작일.
endYmd date
스템프 유효 만료일.
onsiteYn string
Enum:
YN
현장 적립 여부로 값이 Y이면, 매장에서 직원이 도장 적립이 가능합니다.
onsitePwd string
현장적립 비밀번호. 현장적립 여부(Y)일 경우, 스템프 혜택 사용 API 호출 시 반드시 필요합니다.
memo string
내부 참고용 메모.
activeYn string
Enum:
YN
스템프 활성화 여부. 비활성화되면 고객이 스템프를 사용할 수 없습니다.
userId string
사용자 ID. 스템프 발급 대상자를 관리하는데 사용됩니다.
일반적으로 웹사이트 회원의 로그인 ID를 입력합니다.
설정되지 않으면 시스템에 의해 자동으로 사용자 ID가 생성됩니다.
userNm string
사용자 이름. 내부 관리용.
userPhnno string
사용자 연락처. 내부 관리용.
userEml string
사용자 이메일. 내부 관리용.
userEtc1 string
추가 내부 관리용 필드.
userEtc2 string
추가 내부 관리용 필드.
stampImgUrl string
스템프 도장의 이미지 URL.
regYmdt datetime
스템프 생성 날짜. 예: 2025-07-21 11:50:20

스탬프 검증은 어떤 역할을 하나요?

스탬프 검증 API는 단순 유효성 체크가 아니라 현재 적립 상태를 기반으로 다음 행동을 결정하는 API입니다.

  • 추가 적립 가능 여부 판단
  • 목표 달성 여부 확인
  • 이벤트 참여 상태 확인
  • 사용자별 진행 상황 조회

즉, 스탬프 검증은 이벤트 진행 상태를 읽는 핵심 API입니다.

검증 결과로 판단할 수 있는 것

응답 데이터(result)에는 스탬프 진행에 필요한 모든 정보가 포함됩니다.

이를 통해 다음과 같은 판단이 가능합니다.

  • 현재 적립 수 (stamps)와 최대 적립 수 (maxStamps) 비교
  • 추가 적립 가능 여부 판단
  • 목표 달성 여부 확인 (리워드 지급 조건)
  • 스탬프 활성 상태 (activeYn) 확인
  • 사용 가능 환경 (onsiteYn) 판단
  • 사용자 정보 기반 개인화 처리

핵심: “검증 API = 상태 조회 + 로직 판단 입력값”

응답 데이터 활용 방법

검증 API로 애플리케이션 로직에서 직접 활용됩니다.

예:

  • 프론트엔드에서 진행률 UI 표시
  • 적립 버튼 활성/비활성 제어
  • 목표 달성 시 리워드 노출
  • 사용자별 이벤트 상태 분기 처리

즉, 이 API는 UI와 비즈니스 로직을 연결하는 핵심 데이터 소스입니다.

쿠폰 검증 API와의 차이점

두 API 모두 유효성 확인과 함께 상세 데이터를 반환하지만, 반환되는 정보의 성격이 다릅니다.

쿠폰 검증은 할인 방식, 할인 값, 사용 횟수 등 거래 중심 데이터가 반환됩니다.
스탬프 검증은 현재 도장 수(stamps), 스템프 카드의 최대 도장 수(maxStamps), 카드 이름과 제목, 스탬프 이미지 URL 등 적립 진행 상황 데이터가 반환됩니다.

쿠폰 검증 응답은 “지금 얼마나 할인받는가”를 계산하는데 활용되고,
스탬프 검증 응답은 “지금 얼마나 모았고 얼마나 남았는가”를 고객에게 표시하는데 활용됩니다.

운영 관점에서의 중요성

스탬프 검증 API는 이벤트 흐름의 중심에 위치합니다.

  • 잘못된 적립 방지
  • 조건 미충족 상태 차단
  • 사용자 경험 개선
  • 이벤트 로직 안정성 확보

검증 없이 적립을 수행하면 데이터 불일치 및 이벤트 오류가 발생할 수 있습니다.

사용 시 주의사항

  • 검증 결과와 실제 적립 시점 사이에 상태가 변경될 수 있습니다.
  • 검증 후 즉시 적립 API를 호출하는 구조가 안전합니다.
  • 클라이언트 단 검증만으로 로직을 처리하는 것은 권장되지 않습니다.
  • 높은 트래픽 환경에서는 호출 최적화가 필요하며, 호출 실패 시 재시도를 고려하세요.