쿠폰 검증 API

쿠폰 검증 API는 쿠폰 사용 처리 전에 해당 쿠폰이 유효한지 확인하는 기능을 제공합니다.

단순 사용 가능 여부뿐 아니라 할인 정보, 사용 조건, 사용자 데이터까지 함께 반환되어 다양한 비즈니스 로직에 활용할 수 있습니다.

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

GET

/api/coupon/v1/validate?cpnNo={cpnNo} 


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNo string required
쿠폰 번호. 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsitePwd": "12345",
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25"
    }
}

Response Parameters

code integer
응답 코드: 0 = 성공, 그 외 값 = 오류
message string
응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result object
검증 성공 시: 응답 값에 쿠폰 정보가 반환됩니다.
검증 실패 시: 응답 값은 null이며, 오류 메시지를 통해 확인할 수 있습니다.
cpnNo string
쿠폰 번호.
domain string
쿠폰 도메인.
nm string
쿠폰 이름.
discTypeIdx integer
Default:457
Enum:
457458
할인 유형. (457:요율 할인 %, 458:금액 할인)
disc double
Default:0
할인율(457)은 1~100% 범위, 할인금액(458)은 금액 입력
discCurrency string
Default:KRW
Enum:
KRWCADCNYEURGBPIDRJPYMURRUBSGDUSD
화폐 단위. 금액 할인(discTypeIdx:458) 사용시 필수.
formatDiscCurrency string
화폐 통화 기호.
strtYmd date
쿠폰 유효 시작일.
endYmd date
쿠폰 유효 만료일.
useLimit integer
Default:1
Enum:
012345
쿠폰 사용 가능 횟수. (0:무제한, 1~5: 횟수 제한)
imgUrl string
쿠폰 이미지 URL.
onsiteYn string
Default:N
Enum:
YN
현장쿠폰 여부. 쿠폰 페이지에 “쿠폰 사용” 버튼 표시 여부.
오프라인 매장에서 직원이 쿠폰 사용 시 필요.
onsitePwd string
현장쿠폰 비밀번호.
현장쿠폰 여부(Y)일 경우, 쿠폰 사용 API 호출 시 반드시 필요합니다.
memo string
내부 참고용 메모.
url string
URL 입력 시 쿠폰 페이지에 “쿠폰 사용하러 가기” 버튼이 표시됩니다.
버튼 또는 쿠폰 이미지 클릭 시 해당 URL로 리디렉션.
userId string
쿠폰 발급 대상자를 관리하는 데 사용됩니다.
쿠폰 사용 가능 횟수가 2~5로 설정된 경우 반드시 입력해야 하며, 일반적으로 웹사이트 회원의 로그인 ID 또는 영문 이름을 입력합니다.
userNm string
쿠폰 사용자 이름. 내부 관리용.
userPhnno string
쿠폰 사용자 연락처. 내부 관리용.
userEml string
쿠폰 사용자 이메일. 내부 관리용.
userEtc1 string
추가 내부 관리용 필드.
userEtc2 string
추가 내부 관리용 필드.
useCnt integer
쿠폰 사용 횟수.
regYmdt datetime
쿠폰 생성 날짜. 예: 2025-07-21 11:50:20

검증 결과로 무엇을 판단할 수 있나요?

이 API는 단순히 “사용 가능 / 불가”를 확인하는 것을 넘어,
쿠폰에 포함된 상세 정보를 기반으로 개발자가 직접 판단 로직을 구성할 수 있도록 설계되어 있습니다.

응답 데이터(result)를 활용하면 다음과 같은 판단이 가능합니다.

  • 할인 적용 가능 여부 및 할인 금액 계산
  • 특정 사용자 대상 쿠폰인지 여부 확인 (userId, userEml)
  • 사용 횟수 제한 초과 여부 (useCnt, useLimit)
  • 쿠폰 만료 여부 (strtYmd, endYmd)
  • 특정 조건(온/오프라인 등) 충족 여부 (onsiteYn)
  • 쿠폰 적용 후 이동 URL 확인 (url)

즉, 서버에서 단순 결과를 주는 것이 아니라
애플리케이션 레벨에서 자유롭게 로직을 구성할 수 있는 데이터 기반 API입니다.

쿠폰 검증 방식

쿠폰 번호(cpNo)를 기준으로 다양한 상태를 종합적으로 검증합니다.

  • 존재 여부
  • 유효 기간
  • 사용 제한
  • 사용자 조건
  • 적용 가능 환경

검증 결과는 단순 Boolean이 아닌 구조화된 데이터 형태로 반환됩니다.

응답 데이터 활용 방법

응답의 result 객체에는 쿠폰의 모든 핵심 정보가 포함됩니다.

개발자는 이 데이터를 기반으로 다음과 같은 처리를 할 수 있습니다.

  • 프론트엔드에서 할인 금액 즉시 계산 및 표시
  • 특정 사용자만 쿠폰 적용 가능하도록 제한
  • 결제 금액 조건에 따라 쿠폰 적용 여부 분기
  • 쿠폰 상태에 따른 UI 메시지 처리 (만료, 사용 완료 등)

활용 예시

  • 결제 전 유효성 확인: 사용자가 쿠폰 번호를 입력하면 검증 API를 먼저 호출해 유효 여부를 확인하고, 유효한 경우에만 할인을 적용합니다.
  • 사용 전 안내 메시지: 만료되었거나 이미 사용된 쿠폰인 경우, 검증 결과에 따라 사용자에게 적절한 안내 메시지를 표시합니다.
  • 결제 금액 기반 할인 계산: 검증 API 응답의 할인 정보(disc, discType)를 이용해 최종 결제 금액을 계산합니다.

쿠폰이 삭제되어도 동일한 쿠폰 번호로 다시 생성하여 복구할 수 있습니다.

사용 시 주의사항

  • 검증 결과는 조회 시점 기준이며, 실제 사용 시 상태가 변경될 수 있습니다.
  • 반드시 검증 → 쿠폰 사용(Redeem) 호출 구조로 구성해야 합니다.
  • 클라이언트에서만 검증 결과를 신뢰하는 것은 보안상 위험합니다.
  • 할인 계산은 서버에서 한 번 더 검증하는 것이 안전합니다.