API Validasi Kupon

API Validasi Kupon Vivoldi memungkinkan Anda memeriksa apakah kupon valid sebelum diproses penggunaannya.

Selain memeriksa ketersediaan, API ini juga mengembalikan informasi diskon, syarat penggunaan, dan data pengguna untuk mendukung logika bisnis yang fleksibel.

API ini tersedia mulai dari paket Personal.

GET

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


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

Request Parameters

cpnNostringrequired
Nomor kupon. 
{
    "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

codeinteger
Kode respons: 0 = Berhasil, nilai lain = Error
messagestring
Pesan respons. Jika kode tidak sama dengan 0, pesan kesalahan akan dikembalikan.
resultobject
Berhasil diverifikasi: Respons mengembalikan informasi kupon.
Gagal diverifikasi: Respons bernilai null dan dapat dilihat melalui pesan kesalahan.
cpnNostring
Nomor kupon.
domain string
Domain kupon.
nmstring
Nama kupon.
discTypeIdxinteger
Jenis diskon. (457: diskon persentase %, 458: diskon nominal)
discdouble
Untuk persentase (457): rentang 1–100%. Untuk nominal (458): masukkan jumlah.
discCurrencystring
Mata uang. Wajib diisi jika menggunakan diskon nominal (discTypeIdx:458).
formatDiscCurrencystring
Simbol mata uang.
strtYmddate
Tanggal mulai berlaku kupon.
endYmddate
Tanggal kedaluwarsa kupon.
useLimitinteger
Batas penggunaan kupon. (0: tanpa batas, 1–5: jumlah penggunaan terbatas)
imgUrlstring
URL gambar kupon.
onsiteYnstring
Kupon di lokasi. Menentukan apakah tombol “Gunakan Kupon” ditampilkan di halaman kupon.
Dibutuhkan saat kupon digunakan di toko offline.
onsitePwd string
Kata sandi kupon di lokasi.
Diperlukan saat memanggil API penggunaan kupon jika opsi kupon di lokasi diaktifkan (Y).
memostring
Catatan referensi internal.
urlstring
Jika URL dimasukkan, tombol “Pergi Gunakan Kupon” akan ditampilkan di halaman kupon.
Mengklik tombol atau gambar kupon akan mengarahkan ke URL tersebut.
userIdstring
Digunakan untuk mengelola penerima kupon.
Wajib diisi jika batas penggunaan kupon diatur 2–5 kali.
Biasanya diisi dengan ID login anggota situs atau nama dalam bahasa Inggris.
userNmstring
Nama pengguna kupon. Untuk penggunaan internal.
userPhnnostring
Nomor telepon pengguna kupon. Untuk penggunaan internal.
userEmlstring
Email pengguna kupon. Untuk penggunaan internal.
userEtc1string
Bidang tambahan untuk penggunaan internal.
userEtc2string
Bidang tambahan untuk penggunaan internal.
useCntinteger
Jumlah penggunaan kupon.
regYmdtdatetime
Tanggal pembuatan kupon. Contoh: 2025-07-21 11:50:20

Apa yang dapat ditentukan dari hasil validasi?

API ini tidak hanya sekadar memeriksa “valid / tidak valid”.
Dirancang agar developer dapat membangun logika keputusan sendiri berdasarkan data kupon yang detail.

Dengan respons (result), Anda dapat menentukan:

  • Apakah diskon dapat diterapkan dan menghitung nilainya
  • Apakah kupon hanya berlaku untuk pengguna tertentu (userId, userEml)
  • Apakah batas penggunaan telah terlampaui (useCnt, useLimit)
  • Apakah kupon sudah kedaluwarsa atau belum aktif (strtYmd, endYmd)
  • Apakah kondisi tertentu terpenuhi (online/offline, dll.) (onsiteYn)
  • URL tujuan setelah kupon diterapkan (url)

Artinya, ini bukan sekadar hasil sederhana,
melainkan API berbasis data untuk logika fleksibel di level aplikasi.

Metode validasi

Validasi dilakukan berdasarkan kode kupon (cpNo) dengan mempertimbangkan berbagai kriteria.

  • Ketersediaan
  • Masa berlaku
  • Batas penggunaan
  • Syarat pengguna
  • Lingkungan penggunaan

Hasil dikembalikan dalam bentuk data terstruktur, bukan hanya nilai boolean sederhana.

Cara menggunakan data respons

Objek result berisi semua informasi utama kupon.

Developer dapat menggunakan data ini untuk:

  • Menghitung dan menampilkan diskon secara real-time di frontend
  • Membatasi penggunaan kupon hanya untuk pengguna tertentu
  • Menerapkan logika berdasarkan jumlah pembayaran
  • Menampilkan pesan UI sesuai status kupon (kedaluwarsa, sudah digunakan, dll.)

Contoh penggunaan

  • Validasi sebelum pembayaran: Validasi kupon terlebih dahulu dan terapkan hanya jika valid
  • Pesan pengguna: Tampilkan pesan sesuai hasil validasi (kedaluwarsa atau sudah digunakan)
  • Perhitungan diskon: Gunakan (disc, discType) untuk menghitung total pembayaran

Kode kupon yang sama dapat digunakan kembali setelah dihapus.

Hal yang perlu diperhatikan

  • Hasil validasi mencerminkan kondisi saat permintaan dan dapat berubah sebelum digunakan.
  • Selalu gunakan alur: validasi → penggunaan (Redeem).
  • Mengandalkan hanya validasi di sisi klien berisiko terhadap keamanan.
  • Lakukan verifikasi ulang perhitungan diskon di server untuk memastikan akurasi dan keamanan.