Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Pembaruan Stempel (v1)

API Pembaruan Stempel memungkinkan Anda memperbarui data stempel yang sudah diterbitkan.

Selain perubahan dasar, Anda dapat menyesuaikan jumlah stempel, memproses penukaran reward, dan mereset PIN, sehingga kontrol penuh atas status pengguna dapat dilakukan.

API ini tersedia mulai dari paket Personal ke atas.

Dokumentasi v1 (Legacy).

Untuk integrasi baru, kami menyarankan penggunaan versi terbaru, v2.
v1 ditujukan untuk mempertahankan integrasi yang sudah ada dan tidak mendapatkan fitur baru atau peningkatan.

PUT

/api/stamp/v1/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsitePwd": "12345",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

Request Parameters

stampIdx integer required
Stamp IDX.
cardIdx integer
Card IDX.
Card IDX dapat ditemukan di halaman “Kartu Cap” pada dasbor.
stamps integer
Menentukan jumlah cap yang telah dikumpulkan.
Menunjukkan total jumlah cap yang telah diperoleh pelanggan. Mengubah nilai ini akan memperbarui status cap dan dapat ditambah atau dikurangi.
Jika semua cap sudah terkumpul (stamps = jumlah maksimum cap pada kartu), Anda harus mengatur useYn ke Y untuk menandai bahwa hadiah telah digunakan.
resetPinYn string
Default:N
Enum:
YN
Menentukan apakah PIN pelanggan untuk cap akan diatur ulang.
Y: Mengatur ulang PIN pelanggan yang sudah ada. Setelah diatur ulang, pelanggan harus membuat PIN baru saat mengakses halaman cap berikutnya.
N: Menjaga PIN yang ada tanpa perubahan.
useYn string
Default:N
Enum:
YN
Menentukan apakah hadiah dari cap telah digunakan.
Y: Pelanggan telah mengumpulkan semua cap dan menukarkan hadiah (misalnya minuman gratis, diskon, dll). Setelah penukaran, cap menjadi tidak aktif dan cap baru harus diterbitkan.
N: Hadiah belum digunakan.
Saat mengubah dari N ke Y, jumlah cap yang tersimpan harus sudah mencapai maksimum kartu, dan jika stempel memiliki kata sandi di lokasi, onsitePwd harus dikirim bersamaan.
onsitePwd string
Kata sandi autentikasi karyawan untuk stempel di lokasi.
Wajib saat mengubah useYn dari N ke Y untuk menandai hadiah telah digunakan, jika stempel memiliki onsiteYn = Y. Aturan validasinya sama dengan API Redeem.
Tidak diperlukan jika hanya mengubah jumlah cap atau jika stempel tidak memiliki kata sandi.
domain string
Default:https://vvd.bz
Domain cap.
Jika dikosongkan, domain default akan digunakan.
Tersedia untuk paket Premium ke atas — Anda dapat menentukan domain kustom yang terdaftar di bagian Manajemen Domain Tautan.
strtYmd date
Tanggal mulai berlaku cap. Contoh: 2025-01-01
endYmd date
Tanggal kedaluwarsa cap. Contoh: 2025-12-31
Tanggal kedaluwarsa dapat diatur hingga maksimal 5 tahun dari hari ini.
activeYn string
Default:Y
Enum:
YN
Menunjukkan apakah cap aktif. Jika dinonaktifkan, pelanggan tidak dapat menggunakan cap tersebut.
memo string
Catatan internal untuk referensi.
userId string
ID pengguna. Digunakan untuk mengelola penerima cap.
Biasanya diisi dengan ID login anggota situs web.
Jika tidak ditentukan, sistem akan secara otomatis membuat ID pengguna.
userNm string
Nama pengguna. Hanya untuk penggunaan internal.
userPhnno string
Nomor kontak pengguna. Hanya untuk penggunaan internal.
userEml string
Alamat email pengguna. Hanya untuk penggunaan internal.
userEtc1 string
Bidang tambahan untuk pengelolaan internal.
userEtc2 string
Bidang tambahan untuk pengelolaan internal. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Kode respons: 0 = Berhasil, nilai lainnya = Error
message string
Pesan respons. Jika kode bukan 0, pesan error akan dikembalikan.
result null

Validasi parameter numerik

Jika parameter numerik menerima nilai bukan angka, atau angka di luar rentang yang dapat diproses server, permintaan langsung ditolak dengan 400 (kode kesalahan 653).

Dalam kasus itu data stempel dan riwayat perolehan sama sekali tidak berubah, dan tidak ada catatan event maupun pengiriman Webhook. Jika Anda menerima respons gagal, tidak ada yang tersimpan.

Perubahan perilaku. Sebelumnya v1 tetap melanjutkan permintaan meskipun validasi ini gagal. Akibatnya pesan kesalahan dapat tertimpa oleh pesan parameter lain, atau sebagian data stempel benar-benar tersimpan padahal respons berupa kesalahan. Sekarang permintaan dihentikan dengan 400 sebelum diproses, sama seperti versi terbaru.

Mengapa perlu mengontrol jumlah stempel secara langsung

Dalam pengelolaan sistem stempel, ada situasi di mana jumlah stempel perlu disesuaikan secara manual, bukan hanya otomatis.

Contohnya termasuk koreksi kesalahan, pemberian bonus kampanye, dan penyesuaian manual oleh admin.

Dengan mengatur parameter stamps, Anda dapat menambah atau mengurangi nilai tanpa menimpa data yang ada.
Jika jumlah maksimum tercapai, Anda harus mengatur useYn menjadi Y untuk memproses penggunaan reward.

Alur penggunaan reward dan penerbitan ulang stempel

Mengatur useYn ke Y menandai stempel sebagai telah digunakan.

Setelah digunakan, stempel baru harus diterbitkan melalui API pembuatan untuk memulai kembali akumulasi.
Alur ini merupakan siklus inti dari program reward berbasis stempel.
Otomatisasi Penggunaan → Penerbitan baru → Akumulasi ulang membantu mendorong keterlibatan berulang.

Kata sandi toko saat menukarkan hadiah

Saat mengubah useYn dari N menjadi Y untuk menukarkan hadiah, jika stempel memiliki kata sandi untuk pengumpulan stempel di toko (onsiteYn = Y), Anda juga harus mengirim onsitePwd.

Persyaratan ini berlaku dengan cara yang sama seperti pada API Penukaran Hadiah (Redeem). Tujuannya adalah mencegah hadiah ditukarkan melalui API pembaruan tanpa verifikasi kata sandi.

Untuk mengetahui kata sandi yang harus dikirim, periksa nilai onsitePwd yang dikembalikan oleh API Validasi (Validate). Jika stempel tidak memiliki kata sandi toko, onsitePwd dapat dihilangkan.

onsitePwd tidak diperlukan jika Anda hanya mengubah jumlah stempel atau memperbarui stempel yang hadiahnya sudah ditukarkan.

Kapan perlu reset PIN

Atur resetPinYn ke Y untuk mereset PIN pengguna.

Digunakan saat pengguna lupa PIN, mengganti perangkat, atau untuk alasan keamanan.

Setelah reset, pengguna akan diminta membuat PIN baru saat mengakses halaman stempel. Jika diatur ke N atau tidak dikirim, PIN lama tetap digunakan.

Contoh penggunaan

  • Koreksi kesalahan: Memperbaiki jumlah stempel yang salah
  • Pembaruan kampanye: Menyesuaikan perubahan aturan selama kampanye berjalan
  • Verifikasi ulang pengguna: Reset PIN untuk autentikasi ulang offline
  • Penonaktifan: Menonaktifkan stempel saat kampanye berakhir

Hal yang perlu diperhatikan

  • Pastikan perubahan pada stamps tetap konsisten dengan riwayat yang ada
  • Setelah ditandai digunakan (useYn), sebaiknya dianggap sebagai operasi yang tidak dapat dibatalkan
  • Kelola log operasional dan riwayat perubahan secara detail untuk kebutuhan audit