Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Pembuatan Kupon Online (v2)

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/v2/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",
    "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

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.
branchIdx integer
IDX cabang penerbit. Jika tidak dikirim, diterbitkan oleh kantor pusat; kirim 0 untuk mengosongkannya.
Tersedia pada paket Business atau lebih tinggi.
storeIdx integer
IDX toko penerbit. Jika ditentukan, cabang tempat toko berada menjadi cabang penerbit. Mengirim cabang yang berbeda akan menghasilkan kesalahan.
useScope string
Cakupan penggunaan. Hanya ALL (semua toko) atau BRANCH (cabang tertentu) yang diizinkan. Jika tidak dikirim, nilainya ALL.
useBranchIdx integer
IDX cabang tempat penggunaan. Hanya diperlukan saat useScope = BRANCH; selalu kosong jika ALL. 
{
    "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

Cabang penerbit, toko penerbit, dan cakupan penggunaan

Nilai yang ditentukan di sini adalah kebijakan yang disimpan saat penerbitan. "Di mana diterbitkan" (cabang penerbit, toko penerbit) dan "di mana pelanggan dapat menggunakannya" (cakupan penggunaan, cabang penggunaan) adalah konsep yang berbeda, sehingga parameternya terpisah.

Parameter Arti Deskripsi
branchIdx Cabang penerbit Jika tidak dikirim, diterbitkan kantor pusat. Kirim 0 untuk mengosongkannya ke kantor pusat.
storeIdx Toko penerbit Jika ditentukan, cabang tempat toko berada menjadi cabang penerbit. Mengirim cabang lain akan ditolak.
useScope Cakupan penggunaan ALL (semua toko) atau BRANCH (cabang tertentu). Default ALL.
useBranchIdx Cabang penggunaan Hanya diperlukan saat useScope=BRANCH. Selalu kosong jika ALL.

Parameter yang tidak dapat digunakan — processStoreIdx (toko pemroses) menunjuk toko tempat verifikasi, penggunaan, penambahan, atau pengurangan benar-benar terjadi, sehingga tidak dapat dipakai pada API ini. Jika dikirim, akan ditolak dengan 400 (kode kesalahan 1227).

Fitur cabang dan toko hanya tersedia pada paket Business atau lebih tinggi.

Idempotency-Key

Untuk mencoba ulang dengan aman saat respons hilang karena kesalahan jaringan, kirim nilai unik per permintaan pada header Idempotency-Key. Anda juga dapat mengirimnya sebagai requestId di body; jika keduanya dikirim dengan nilai berbeda, permintaan ditolak. Format yang diizinkan adalah 8–64 karakter berupa huruf, angka, dan . _ : -.

Jika Anda mengirim ulang permintaan yang sama dengan key yang sama, hasil pertama dikembalikan tanpa diproses ulang. Tidak ada yang diproses dua kali dan webhook tidak dikirim ulang.

Gunakan key yang sama hanya untuk percobaan ulang operasi logis yang sama. Selalu gunakan key baru untuk operasi yang berbeda. Menggunakan key yang sama dengan isi permintaan lain atau untuk operasi lain dapat ditolak dengan 409.

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.