스탬프 검증 API (v2)

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

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

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

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

API Version

GET

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

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required: 스탬프 IDX.
processStoreIdx integer: 이 요청이 실제로 처리되는 매장 IDX. 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.
처리 지점은 요청으로 받지 않고 이 매장에서 서버가 확인합니다. 발행 매장(storeIdx)과는 다른 값입니다.

{
    "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",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "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",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

code integer: 응답 코드: 0 = 성공, 그 외 값 = 오류
message string: 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result object: 검증에 성공하면 응답값에 스탬프 정보가 포함되어 반환됩니다.
검증에 실패하면 응답값은 null이며, 오류 메시지를 통해 원인을 확인할 수 있습니다.

현장 인증 토큰 (onsiteToken)

v2 검증 API 응답에는 현장 비밀번호 평문(onsitePwd)이 포함되지 않습니다. 대신 180초 동안 유효한 onsiteToken을 반환합니다.

목적은 인증 강도를 높이는 것이 아니라 평문 비밀번호 노출을 최소화하는 것입니다. 검증 API는 비밀번호 자체를 확인하지 않으므로, 이 토큰이 새로운 인증 요소를 추가하는 것은 아닙니다. 대신 짧은 유효 시간, 1회 사용, 컨텍스트 바인딩을 통해 토큰의 재사용 범위를 제한합니다.

항목	값
유효 시간	180초. 유효 시간은 `onsiteTokenExpiresIn`으로 함께 반환됩니다.
사용 횟수	1회. 사용 후에는 동일한 `Idempotency-Key`로 재시도하는 경우에만 최초 처리 결과를 반환합니다.
바인딩	조직, API 키 계정, 리소스, 행위, 검증 시 확인한 처리 매장
적용 대상	쿠폰 사용 처리, 스탬프 혜택 사용 처리, 스탬프 수정의 `useYn = Y`

현장 인증을 사용하지 않는 리소스(onsiteYn = N)에는 토큰을 발급하지 않습니다. v1 검증 API는 기존과 동일하게 onsitePwd 평문을 반환합니다.

숫자 파라미터 검증

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

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

처리 매장 지정

파라미터	의미	설명
`processStoreIdx`	처리 매장	이 요청이 실제로 처리되는 매장입니다. 선택 항목이며, 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.

처리 지점은 요청으로 받지 않습니다. 지정한 매장이 속한 지점을 서버가 확인해 기록합니다.

사용 가능 범위가 BRANCH인 경우, 확인된 처리 매장의 지점이 사용 가능 지점과 같거나 해당 지점의 현장 비밀번호로 인증해야 처리됩니다. 둘 다 없으면 거부됩니다.

사용할 수 없는 파라미터 — branchIdx(발행 지점), storeIdx(발행 매장), useScope(사용 가능 범위), useBranchIdx(사용 가능 지점)는 이미 저장된 발행 정책이라 이 API로 바꿀 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

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

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

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

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

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

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

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

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

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

응답 데이터 활용 방법

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

예:

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

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

쿠폰 검증 API와의 차이점

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

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

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

운영 관점에서의 중요성

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

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

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

사용 시 주의사항

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