API Validasi Stempel

API Validasi Stempel digunakan untuk memeriksa apakah stempel berada dalam kondisi valid sebelum menambah, mengurangi, atau memproses penggunaan reward.

Memverifikasi stamp IDX, periode berlaku, status aktif, serta apakah reward sudah digunakan dalam satu permintaan.

Selain validasi, API ini juga mengembalikan status akumulasi dan informasi kartu, sehingga dapat digunakan untuk membangun tampilan stempel bagi pengguna.

API ini tersedia mulai dari paket Personal ke atas.

GET

/api/stamp/v1/validate?stampIdx={stampIdx} 


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
IDX stempel. 
{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsitePwd": "123456",
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "payloadVersion": "v1"
    }
}

Response Parameters

codeinteger
Kode respons: 0 = Berhasil, nilai lain = Error
messagestring
Pesan respons. Jika kode tidak sama dengan 0, pesan kesalahan akan dikembalikan.
resultobject
Jika verifikasi berhasil, respons akan berisi informasi stempel.
Jika gagal, nilai respons akan menjadi null dan pesan kesalahan akan menunjukkan penyebabnya.
stampIdx integer
Stamp IDX.
domain string
Domain cap.
cardIdx integer
Card IDX.
cardNm string
Nama kartu.
cardTtl string
Judul kartu.
stamps integer
Jumlah cap yang telah dikumpulkan sejauh ini.
maxStamps integer
Jumlah maksimum cap pada kartu.
stampUrl string
URL halaman cap.
url string
URL tujuan yang akan dibuka saat tombol di halaman cap diklik.
strtYmd date
Tanggal mulai masa berlaku cap.
endYmd date
Tanggal berakhirnya masa berlaku cap.
onsiteYn string
Enum:
YN
Menunjukkan apakah penambahan cap di lokasi diaktifkan.
Jika nilainya Y, staf toko dapat menambahkan cap langsung di tempat.
onsitePwd string
Kata sandi untuk penambahan cap di lokasi.
Diperlukan saat menggunakan API penggunaan manfaat jika opsi di lokasi diaktifkan (Y).
memo string
Catatan internal untuk referensi.
activeYn string
Enum:
YN
Menunjukkan apakah cap aktif.
Jika dinonaktifkan, pelanggan tidak dapat menggunakan cap tersebut.
userId string
ID pengguna. Digunakan untuk mengelola penerima cap.
Biasanya ini adalah ID login anggota situs web.
Jika tidak diatur, sistem akan membuat ID pengguna secara otomatis.
userNm string
Nama pengguna. Hanya untuk keperluan internal.
userPhnno string
Nomor telepon pengguna. Hanya untuk keperluan internal.
userEml string
Alamat email pengguna. Hanya untuk keperluan internal.
userEtc1 string
Kolom tambahan untuk manajemen internal.
userEtc2 string
Kolom tambahan untuk manajemen internal.
stampImgUrl string
URL gambar cap.
regYmdt datetime
Tanggal pembuatan cap. Contoh: 2025-07-21 11:50:20

Apa peran validasi stempel?

API Validasi Stempel bukan hanya pengecekan validitas.
API ini digunakan untuk menentukan langkah berikutnya berdasarkan status akumulasi saat ini.

  • Menentukan apakah stempel dapat ditambahkan
  • Memeriksa apakah syarat reward sudah terpenuhi
  • Memastikan status partisipasi kampanye
  • Melihat progres per pengguna

Intinya, API ini adalah endpoint utama untuk membaca progres kampanye.

Apa yang bisa ditentukan dari hasil validasi

Response (result) berisi semua data yang diperlukan untuk mengevaluasi progres stempel.

Dengan data ini, Anda dapat:

  • Membandingkan stamps dengan maxStamps
  • Menentukan apakah akumulasi masih memungkinkan
  • Memeriksa apakah syarat reward terpenuhi
  • Memastikan status aktif (activeYn)
  • Menilai konteks penggunaan (onsiteYn)
  • Menerapkan personalisasi berbasis data pengguna

Inti: “API validasi = status + input untuk logika keputusan”

Cara menggunakan data response

Response dari API validasi digunakan langsung dalam logika aplikasi.

Contoh:

  • Tampilkan progres: Menampilkan progres secara real-time di frontend
  • Kontrol aksi: Mengaktifkan atau menonaktifkan tombol berdasarkan status
  • Tampilkan reward: Menampilkan reward saat target tercapai
  • Kelola kondisi pengguna: Menyesuaikan logika berdasarkan progres

Intinya, API ini adalah sumber data utama yang menghubungkan UI dan logika bisnis.

Perbedaan dengan API validasi kupon

Kedua API mengembalikan data validasi, tetapi jenis informasinya berbeda.

Validasi kupon berisi data transaksi seperti jenis diskon, nilai, dan batas penggunaan.
Validasi stempel berisi data progres seperti stamps, maxStamps, nama kartu, judul, dan URL gambar.

Validasi kupon digunakan untuk menghitung “berapa diskon saat ini”,
sementara validasi stempel menunjukkan “berapa yang sudah dikumpulkan dan berapa yang tersisa”.

Pentingnya dalam operasional

API Validasi Stempel berada di pusat alur event.

  • Mencegah akumulasi stempel yang tidak valid
  • Memblokir aksi jika syarat tidak terpenuhi
  • Meningkatkan pengalaman pengguna
  • Menjaga stabilitas logika event

Tanpa validasi, dapat terjadi inkonsistensi data dan kesalahan pada event.

Hal yang perlu diperhatikan

  • Status dapat berubah antara proses validasi dan eksekusi aktual
  • Sebaiknya langsung memanggil API akumulasi setelah validasi
  • Tidak disarankan hanya mengandalkan validasi di sisi klien
  • Pada lingkungan trafik tinggi, optimalkan pemanggilan dan siapkan mekanisme retry