API Pembuatan Kupon Online

API Pembuatan Kupon Vivoldi memungkinkan Anda membuat kupon diskon secara terprogram.

Pilih diskon berbasis persentase (%) atau nominal tetap, lalu atur opsi seperti masa berlaku, batas penggunaan, grup, dan template langsung dalam permintaan.

Untuk membuat kupon dalam jumlah banyak, gunakan dashboard.
Jika membutuhkan gambar, buat terlebih dahulu grup kupon dan unggah gambar di dashboard, lalu buat kupon dengan merujuk ke grup tersebut.

API ini tersedia mulai dari paket Personal.

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

cpnNostring
Nomor kupon. 8–16 karakter alfanumerik. Jika tidak diisi, sistem akan membuatnya secara otomatis. Karakter khusus tidak diperbolehkan.
Contoh: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
Panjang kode kupon.
Jika tidak diisi, akan menggunakan nilai default (16).
Hanya berlaku jika kode kupon tidak ditentukan. Sistem akan membuatnya secara otomatis sesuai panjang yang dipilih.
domain string
Default:https://vvd.bz
Domain kupon.
Jika dikosongkan, akan disimpan dengan domain default.
Tersedia di paket Premium ke atas: Anda dapat menentukan domain khusus yang terdaftar di Manajemen Domain Tautan.
webhookEnableYn string
Enum:
YN
Status penggunaan Webhook.
Webhook global harus diaktifkan.
Fitur ini hanya tersedia pada paket Enterprise.
nmstringrequired
Nama kupon.
discTypeIdxintegerrequired
Jenis diskon. (457: Persentase %, 458: Jumlah tetap)
discdoublerequired
Untuk persentase (457): kisaran 1–100%. Untuk jumlah tetap (458): masukkan nominal.
discCurrencystring
Satuan mata uang. Wajib diisi jika menggunakan diskon jumlah tetap (discTypeIdx:458).
strtYmddaterequired
Tanggal mulai berlaku kupon. Contoh: 2024-10-01
endYmddaterequired
Tanggal kadaluarsa kupon. Contoh: 2024-12-31
Tanggal kedaluwarsa hanya dapat ditetapkan hingga 31 Desember tahun berikutnya.
useLimitintegerrequired
Batas penggunaan kupon. (0: Tanpa batas, 1–5: Terbatas)
Jika diatur ke 2 atau lebih, nilai userId wajib diisi.
grpIdxinteger
Grup kupon. Digunakan untuk mengelola kupon berdasarkan grup. IDX grup dapat dilihat di dasbor.
Jika ada pengaturan duplikat antara grup dan kupon, pengaturan grup akan diprioritaskan.
tmplIdxinteger
Template kupon. Digunakan sebagai referensi saat membuat kupon. IDX template dapat dilihat di dasbor.
onsiteYnstring
Penanda kupon di lokasi. Menampilkan tombol “Gunakan Kupon” pada halaman kupon.
Diperlukan agar staf toko offline dapat memverifikasi kupon.
onsitePwdstring
Kata sandi kupon di lokasi. Diperlukan saat kupon digunakan.
memostring
Catatan internal untuk referensi.
urlstring
Jika URL dimasukkan, tombol “Pergi Gunakan Kupon” akan muncul di halaman kupon.
Klik tombol atau gambar kupon akan mengarahkan ke URL tersebut.
colorstring
Warna teks kupon. Masukkan nilai HEX. Contoh: #4F4F4F
backgroundstring
Warna latar kupon. Masukkan nilai HEX. Contoh: #FFFFFF
userIdstring
Digunakan untuk mengelola penerima kupon.
Wajib diisi jika batas penggunaan diatur 2–5 kali. Biasanya menggunakan ID login atau nama pengguna.
userNmstring
Nama pengguna kupon. Untuk manajemen internal.
userPhnnostring
Nomor telepon pengguna kupon. Untuk manajemen internal.
userEmlstring
Email pengguna kupon. Untuk manajemen internal.
userEtc1string
Bidang tambahan untuk manajemen internal.
userEtc2string
Bidang tambahan untuk manajemen internal. 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

Response Parameters

code integer
Kode respons: 0 = Berhasil, nilai lainnya = Error
message string
Pesan respons. Jika kode bukan 0, pesan error akan dikembalikan.
result string
Nilai respons. Nomor kupon yang dibuat akan dikembalikan.
Contoh: ZJLF0399WQBEQZJM

Kapan menggunakan API ini

Gunakan API ini saat Anda perlu menerbitkan kupon secara otomatis untuk promosi, event, atau kampanye akuisisi pengguna.

Cocok untuk berbagai skenario pemasaran, seperti insentif pendaftaran, diskon tertarget, dan peningkatan konversi dari traffic iklan.

Pengaturan Format Kode Kupon

Kode kupon dikontrol menggunakan parameter cpNo dan cpNoDigits.
Jika cpNo ditentukan, nilai tersebut digunakan sebagai kode kupon. Jika tidak, sistem akan membuatnya secara otomatis.

Untuk pembuatan otomatis, panjang kode dapat diatur dengan cpNoDigits (default: 16).
Sesuaikan dengan kebutuhan: kode yang lebih panjang mengurangi risiko duplikasi, sedangkan yang lebih pendek lebih mudah digunakan.

Integrasi Data Pengguna

Untuk mengaitkan kupon dengan pengguna tertentu, tentukan parameter userId.

Untuk mengaitkan dengan beberapa pengguna sekaligus, gunakan field userEml·userPhone·userEtc1·userEtc2 secara bersamaan.
Data ini digunakan di dashboard untuk mengidentifikasi dan memfilter pemilik kupon, sehingga cocok untuk layanan B2C yang memerlukan identifikasi pengguna.

Contoh penggunaan

  • Reward otomatis saat pendaftaran: Panggil API saat pengguna mendaftar untuk membuat dan mengirim kupon personal secara instan
  • Promo terbatas waktu: Tentukan tanggal mulai dan akhir agar kupon hanya berlaku dalam periode tertentu
  • Pelacakan konversi iklan: Hubungkan kupon ke link iklan untuk melacak klik → penggunaan → pembelian
  • Targeting pengguna: Berikan diskon personal berdasarkan email atau user ID
  • Kupon toko offline: Set onsiteYn ke Y agar staf dapat memvalidasi kupon dengan password

Hal yang perlu diperhatikan

  • Untuk membuat kupon dengan gambar, buat grup kupon dan unggah gambar di dashboard terlebih dahulu, lalu tentukan ID grup di grpIdx sebelum memanggil API.
  • Untuk menerima webhook, set webhookEnablYn ke Y dan daftarkan URL Webhook di dashboard sebelumnya.
  • Jika useLimit tidak terbatas, kupon tidak akan ditandai sebagai selesai meskipun sudah digunakan.
  • Untuk kupon offline, pastikan pengelolaan password validasi dilakukan dengan aman.