온라인 쿠폰 생성 API

비볼디 쿠폰 생성 API는 할인 쿠폰을 프로그래밍 방식으로 발급하는 기능을 제공합니다.

할인률(%) 또는 금액 방식을 선택할 수 있으며, 유효기간·사용 횟수·그룹·템플릿 등 세부 옵션을 요청 시 함께 지정할 수 있습니다.

여러 개의 쿠폰을 동시에 생성하려면 대시보드를 이용하세요.
이미지가 필요한 경우, 대시보드에서 쿠폰 그룹을 먼저 생성하고 이미지를 등록한 뒤 해당 그룹을 지정하여 쿠폰을 생성하세요.

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

POST

/api/coupon/v1/create 

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNo string
쿠폰 번호. 영문/숫자 조합 8~16자리. 값이 없으면 시스템에서 자동 생성. 특수문자 불가.
값이 비어있으면 쿠폰 번호가 시스템에 의해 자동으로 생성됩니다.
예: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
쿠폰 번호 자리수.
값이 없을 경우 기본값(16자리)이 적용됩니다.
쿠폰 번호를 직접 지정하지 않은 경우에만 사용되며, 시스템이 해당 자리수로 자동 생성합니다.
domain string
Default:https://vvd.bz
쿠폰 도메인. 값이 비어있으면 기본 도메인으로 저장됩니다.
프리미엄 요금제 이상에서는, 링크 도메인 관리에서 등록한 커스텀 도메인을 지정할 수 있습니다.
webhookEnableYn string
Enum:
YN
Webhook 사용 여부. 전역 Webhook이 활성화되어 있어야 합니다.
이 기능은 엔터프라이즈 요금제에서만 제공됩니다.
nm string required
쿠폰 이름.
discTypeIdx integer required
Default:457
Enum:
457458
할인 유형. (457:요율 할인 %, 458:금액 할인)
disc double required
Default:0
할인율(457)은 1~100% 범위, 할인금액(458)은 금액 입력
discCurrency string
Default:KRW
Enum:
KRWCADCNYEURGBPIDRJPYMURRUBSGDUSD
화폐 단위. 금액 할인(discTypeIdx:458) 사용시 필수.
strtYmd date required
쿠폰 유효 시작일. 예: 2024-10-01
endYmd date required
쿠폰 유효 만료일. 예: 2024-12-31
만료일은 다음 해 12월 31일까지만 설정할 수 있습니다.
useLimit integer required
Default:1
Enum:
012345
쿠폰 사용 가능 횟수. (0:무제한, 1~5: 횟수 제한)
2회 이상 지정시 userId 값은 반드시 지정해야 합니다.
grpIdx integer
Default:0
쿠폰 그룹. 쿠폰을 그룹으로 관리할 때 사용. 그룹IDX는 대시보드의 쿠폰 그룹 관리에서 확인 가능.
그룹 설정과 쿠폰 설정이 중복될 경우 그룹 설정이 우선순위를 갖습니다.
tmplIdx integer
Default:0
쿠폰 템플릿. 쿠폰 생성 시 참조할 템플릿. 템플릿IDX는 대시보드의 쿠폰 템플릿 관리에서 확인 가능.
onsiteYn string
Default:N
Enum:
YN
현장쿠폰 여부. 쿠폰 페이지에 “쿠폰 사용” 버튼 표시 여부.
오프라인 매장에서 직원이 쿠폰 사용 시 필요.
onsitePwd string
현장쿠폰 비밀번호. 쿠폰 사용 시 필요한 비밀번호.
memo string
내부 참고용 메모.
url string
URL 입력 시 쿠폰 페이지에 “쿠폰 사용하러 가기” 버튼이 표시됩니다.
버튼 또는 쿠폰 이미지 클릭 시 해당 URL로 리디렉션.
color string
쿠폰 글자 색상. HEX 값 입력. 예: #4F4F4F
background string
쿠폰 배경 색상. HEX 값 입력. 예: #FFFFFF
userId string
쿠폰 발급 대상자를 관리하는 데 사용됩니다.
쿠폰 사용 가능 횟수가 2~5로 설정된 경우 반드시 입력해야 하며, 일반적으로 웹사이트 회원의 로그인 ID 또는 영문 이름을 입력합니다.
userNm string
쿠폰 사용자 이름. 내부 관리용.
userPhnno string
쿠폰 사용자 연락처. 내부 관리용.
userEml string
쿠폰 사용자 이메일. 내부 관리용.
userEtc1 string
추가 내부 관리용 필드.
userEtc2 string
추가 내부 관리용 필드. 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

Response Parameters

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

언제 이 API를 사용하나요?

이 API는 프로모션, 이벤트, 회원 유입 캠페인에서 쿠폰을 자동으로 발급해야 할 때 사용합니다.

회원가입 보상, 특정 사용자 대상 할인, 광고 유입 전환 유도 등 다양한 마케팅 시나리오에 적용할 수 있습니다.

쿠폰 번호 형식 설정 방법

쿠폰 번호는 cpNo와 cpNoDigits 파라미터로 제어합니다.
cpNo를 직접 지정하면 해당 값이 그대로 쿠폰 번호로 사용되며, 지정하지 않으면 시스템이 자동으로 생성합니다.

자동 생성 시 cpNoDigits로 자릿수(기본값 16)를 조정할 수 있습니다.
자릿수는 사용 환경에 맞게 설정하되, 길수록 충돌 가능성이 줄어들고 짧을수록 입력 편의성이 높아집니다.

사용자 정보 연동

쿠폰을 특정 사용자에게 귀속시키려면 userId를 지정합니다.

여러 사용자에게 동시에 귀속시키는 경우 userEml·userPhone·userEtc1·userEtc2 필드를 함께 활용할 수 있습니다.
이 정보는 대시보드에서 쿠폰 소유자 확인 및 필터링에 사용되며, 사용자 식별이 필요한 B2C 서비스에서 유용합니다.

활용 예시

  • 회원가입 보상 쿠폰 자동 발급: 신규 가입 시 API를 호출하여 개인 전용 쿠폰을 생성하고 즉시 전달
  • 기간 한정 프로모션: 캠페인 시작일과 종료일을 지정해 특정 기간에만 유효한 쿠폰을 생성
  • 광고 캠페인 전환 추적: 광고 링크에 쿠폰을 연결하여 클릭 → 쿠폰 사용 → 구매까지 추적
  • 특정 사용자 타겟팅: 이메일 또는 사용자 ID 기반으로 맞춤형 할인 제공
  • 오프라인 매장 쿠폰: onsiteYn을 Y로 설정해 고객이 쿠폰을 제시하면 직원 비밀번호로 사용 처리

사용 시 주의사항

  • 이미지를 포함한 쿠폰을 생성하려면 API 호출 전에 대시보드에서 쿠폰 그룹을 생성하고 이미지를 등록한 뒤 grpIdx에 해당 그룹 ID를 지정해야 합니다.
  • 웹훅 수신을 원하면 webhookEnablYn을 Y로 설정하고, 대시보드에서 Webhook URL을 먼저 등록해야 합니다.
  • useLimit값이 무제한일 때 고객이 쿠폰을 사용하여도 사용 완료처리 되지 않습니다.
  • 현장 쿠폰의 경우, 쿠폰 사용 처리를 위해 비밀번호 관리에 주의가 필요합니다.