API Validasi Stempel (v2)

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.

API Version

GET

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

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required: IDX stempel.
processStoreIdx integer: IDX toko tempat permintaan ini benar-benar diproses. Jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.
Cabang pemrosesan tidak diambil dari permintaan; server menentukannya dari toko ini. Nilai ini berbeda dari toko penerbit (storeIdx).

{
    "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",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "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",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

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.

Token verifikasi di toko (onsiteToken)

Respons API Validasi v2 tidak menyertakan kata sandi toko dalam bentuk teks biasa (onsitePwd). Sebagai gantinya, API mengembalikan onsiteToken yang berlaku selama 180 detik.

Tujuannya adalah meminimalkan paparan kata sandi dalam teks biasa, bukan memperkuat autentikasi. API Validasi tidak memverifikasi kata sandi itu sendiri, sehingga token ini tidak menambahkan faktor autentikasi baru. Masa berlaku yang singkat, penggunaan satu kali, dan pengikatan konteks membatasi penggunaan ulang token.

Item	Nilai
Masa berlaku	180 detik. Masa berlaku juga dikembalikan melalui `onsiteTokenExpiresIn`.
Jumlah penggunaan	Satu kali. Setelah token digunakan, hanya percobaan ulang dengan `Idempotency-Key` yang sama yang mengembalikan hasil awal.
Pengikatan	Organisasi, akun kunci API, sumber daya, tindakan, dan toko pemroses yang dikonfirmasi saat validasi
Digunakan untuk	Penukaran kupon, penukaran hadiah stempel, dan pembaruan stempel dengan `useYn = Y`

Token tidak diterbitkan untuk sumber daya yang tidak menggunakan verifikasi di toko (onsiteYn = N). API Validasi v1 tetap mengembalikan onsitePwd dalam bentuk teks biasa.

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.

Menentukan toko pemroses

Parameter	Arti	Deskripsi
`processStoreIdx`	Toko pemroses	Toko tempat permintaan ini benar-benar diproses. Opsional; jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.

Cabang pemroses tidak diterima dari permintaan. Server menentukannya dari toko yang Anda tentukan dan mencatatnya.

Jika cakupan penggunaan adalah BRANCH, permintaan hanya diproses bila cabang toko pemroses yang terverifikasi sama dengan cabang penggunaan, atau bila Anda melakukan autentikasi dengan kata sandi di tempat cabang tersebut. Tanpa keduanya, permintaan ditolak.

Parameter yang tidak dapat digunakan — branchIdx (cabang penerbit), storeIdx (toko penerbit), useScope (cakupan penggunaan), dan useBranchIdx (cabang penggunaan) adalah kebijakan penerbitan yang sudah tersimpan dan tidak dapat diubah melalui API ini. Jika dikirim, akan ditolak dengan 400 (kode kesalahan 1227).

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