Dokumentasi API Multi-Toko
Dokumentasi ini mengikuti header autentikasi dan endpoint yang saat ini diproses oleh backend LENZZ STORE.
1. Gambaran Multi-Toko
Satu akun LENZZ dapat memiliki beberapa toko. Setiap toko mempunyai ID Toko internal, API ID, API KEY, status aktif/nonaktif, pengaturan IP whitelist, serta data produk dan pesanan yang dipisahkan berdasarkan toko.
API KEY bersifat rahasia dan hanya ditampilkan saat dibuat. Simpan di backend aplikasi yang terhubung, jangan di halaman HTML atau JavaScript browser.
2. Empat jenis identitas dan kredensial
| Data | Fungsi |
|---|---|
| ID Akun | Identitas permanen pengguna, misalnya LENZZ-USER-00000001. |
| ID KEY | Nomor unik numerik milik akun (11 digit pada format yang dibuat LENZZ). Berbeda dari ID Akun. |
| API ID | Pengenal publik untuk masing-masing toko yang ditampilkan pada pengelolaan API. Pada endpoint API aktif saat ini, autentikasi request memakai ID Akun, ID KEY, dan API KEY; API ID tidak dikirim sebagai header autentikasi. |
| API KEY | Kunci rahasia khusus toko yang dipakai sebagai Bearer token. |
3. Autentikasi API yang aktif
Setiap request harus dikirim melalui HTTPS dari backend server. Header yang diperiksa oleh backend saat ini adalah:
Authorization: Bearer API_KEY_TOKO X-Account-ID: LENZZ-USER-00000001 X-ID-KEY: 85580635657 Accept: application/json
Ganti contoh nilai dengan ID Akun, ID KEY akun, dan API KEY dari toko yang ingin diakses. Jangan mengirim X-Store-ID atau X-API-ID sebagai pengganti header di atas; keduanya tidak dipakai oleh middleware autentikasi endpoint aktif saat ini.
4. IP Whitelist
Jika daftar IP whitelist pada toko tidak kosong, server memeriksa alamat IP pemanggil yang diterima pada REMOTE_ADDR. Request dari IP yang tidak terdaftar akan ditolak dengan HTTP 403 dan error ip_not_allowed.
- Masukkan IP publik sumber request server-ke-server yang benar-benar terlihat oleh LENZZ.
- Untuk QRIS Generator yang berada di hosting lain, periksa IP outbound publik hosting tersebut. IP HP atau Wi-Fi pengguna bukan IP yang perlu dimasukkan.
- Jika hosting menggunakan proxy/NAT atau IP outbound khusus, tanyakan IP outbound tetap kepada penyedia hosting.
- Jika whitelist dikosongkan, pembatasan IP untuk toko tersebut tidak diterapkan.
5. Endpoint yang tersedia
Base URL endpoint:
https://DOMAIN-LENZZ/api/v1/index.php?resource=RESOURCE
| Method | Resource | Fungsi |
|---|---|---|
| GET | me | Menampilkan identitas toko yang terautentikasi. |
| GET | products | Menampilkan produk milik toko. |
| POST | products | Menambahkan produk. Payload minimal: name dan price. |
| GET | orders | Menampilkan hingga 100 pesanan terbaru milik toko. |
| POST | orders | Membuat pesanan dan meminta QRIS dinamis melalui gateway APIQris yang dikonfigurasi admin LENZZ. |
| PATCH | orders | Membatalkan pesanan yang masih pending. API toko tidak boleh menetapkan status paid. |
Contoh membuat pesanan/QRIS
POST /api/v1/index.php?resource=orders
Content-Type: application/json
{
"amount": 25000,
"customer_name": "Nama Pembayar",
"external_order_id": "ORDER-001"
}
Nominal minimum adalah Rp1.000. Jika berhasil, respons berisi order_id, status, amount, serta objek payment yang dapat memuat qr_image, payment_url, invoice, kode_unik, total_bayar, dan expires_at. Pelanggan wajib membayar sesuai total_bayar, bukan hanya nilai amount.
6. Webhook pembayaran
Webhook APIQris pada LENZZ menerima notifikasi status dari gateway. Tanda tangan diverifikasi menggunakan HMAC-SHA256 terhadap raw body dan header X-APIQris-Signature dengan format t=TIMESTAMP,v1=SIGNATURE. Timestamp dibatasi toleransi 5 menit dan referensi order_id dicocokkan dengan pesanan internal.
- Status
paid(atau eventinvoice.paid) mengubah pesanan pending menjadipaid. - Status
expired(atau eventinvoice.expired) mengubah pesanan pending menjadiexpired. - Notifikasi yang tanda tangannya tidak valid ditolak.
- Status paid hanya ditetapkan oleh webhook gateway yang tervalidasi, bukan oleh API toko.
Field Callback URL toko disimpan pada data toko. Namun, versi endpoint dan webhook yang didokumentasikan di sini belum mengirim callback keluar ke URL tersebut secara otomatis. Jangan mengandalkan callback URL eksternal sampai fitur pengiriman callback diaktifkan.
7. Kode respons umum
200— request berhasil.201— produk atau pesanan berhasil dibuat.401— kredensial hilang/tidak cocok, atau ID KEY tidak valid.403 ip_not_allowed— IP pemanggil tidak masuk whitelist toko.422— payload atau nilai input tidak valid.502 qris_gateway_failed— gateway QRIS gagal membuat pembayaran.404 endpoint_not_found— resource atau method tidak tersedia.
8. Cara mulai integrasi
- Login ke LENZZ STORE lalu buka Toko & API Saya.
- Pilih toko yang akan dihubungkan. Pastikan API toko aktif.
- Salin ID Akun dan ID KEY dari bagian identitas akun.
- Gunakan API KEY milik toko yang dipilih. API KEY tiap toko berbeda.
- Tambahkan IP outbound server aplikasi ke IP whitelist toko jika whitelist digunakan.
- Kirim request dari backend menggunakan tiga header autentikasi pada bagian 3.
- Untuk pembayaran QRIS, pastikan gateway APIQris aktif, lalu salin Webhook Callback URL dari menu pengaturan APIQris admin LENZZ ke Dashboard APIQris.