온라인 쿠폰 생성 API (v2)

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

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

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

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

API Version

POST

/api/coupon/v2/create

Request
Response

{
    "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",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11,
    "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: 추가 내부 관리용 필드.
branchIdx integer: 발행 지점 IDX. 보내지 않으면 본사 발행이며, 0을 보내면 본사로 비웁니다.
비즈니스 요금제 이상에서만 사용할 수 있습니다.
storeIdx integer: 발행 매장 IDX. 지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 오류입니다.
useScope string: 사용 가능 범위. ALL(모든 매장) 또는 BRANCH(특정 지점)만 허용됩니다. 보내지 않으면 ALL입니다.
useBranchIdx integer: 사용 가능 지점 IDX. useScope = BRANCH일 때만 필요하며, ALL이면 항상 비어 있습니다.

{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

Response Parameters

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

발행 지점·매장과 사용 가능 범위

여기서 지정하는 값은 발행 시점에 저장되는 정책입니다. "어디에서 발행됐는가"(발행 지점·발행 매장)와 "고객이 어디에서 쓸 수 있는가"(사용 가능 범위·사용 가능 지점)는 서로 다른 개념이므로 파라미터도 나뉘어 있습니다.

파라미터	의미	설명
`branchIdx`	발행 지점	보내지 않으면 본사 발행입니다. `0`을 보내면 본사로 비웁니다.
`storeIdx`	발행 매장	지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 거부됩니다.
`useScope`	사용 가능 범위	`ALL`(모든 매장) 또는 `BRANCH`(특정 지점). 보내지 않으면 `ALL`입니다.
`useBranchIdx`	사용 가능 지점	`useScope=BRANCH`일 때만 필요합니다. `ALL`이면 항상 비어 있습니다.

사용할 수 없는 파라미터 — processStoreIdx(처리 매장)는 검증·사용·적립·차감이 실제로 일어난 매장을 가리키는 값이라 이 API에서는 쓸 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

지점·매장 기능은 비즈니스 요금제 이상에서만 사용할 수 있습니다.

Idempotency-Key

네트워크 오류로 응답을 받지 못했을 때 안전하게 재시도하려면 Idempotency-Key 헤더에 요청마다 고유한 값을 담아 보냅니다. 본문의 requestId로도 보낼 수 있으며, 둘 다 보내고 값이 다르면 거부됩니다. 허용 형식은 영문·숫자와 . _ : - 를 조합한 8~64자입니다.

같은 key로 같은 요청을 다시 보내면 다시 처리하지 않고 최초 결과를 그대로 돌려줍니다. 중복으로 처리되지 않으며 웹훅도 다시 발송되지 않습니다.

같은 key는 같은 논리 작업의 재시도에만 사용하세요. 서로 다른 작업에는 반드시 새 key를 사용해야 합니다. 같은 key를 다른 요청 내용이나 다른 작업에 사용하면 409로 거부될 수 있습니다.

언제 이 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값이 무제한일 때 고객이 쿠폰을 사용하여도 사용 완료처리 되지 않습니다.
현장 쿠폰의 경우, 쿠폰 사용 처리를 위해 비밀번호 관리에 주의가 필요합니다.