Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.scalev.com/llms.txt

Use this file to discover all available pages before exploring further.

Storefront API adalah API untuk storefront custom yang berjalan di browser. Gunakan Storefront API saat Anda ingin membuat frontend sendiri dan memakai Scalev sebagai backend untuk katalog, cart, checkout, akun customer, lokasi pengiriman, order, dan payment. Storefront API berbeda dari pengaturan Storefront bawaan. Pengaturan Storefront bawaan mengatur halaman buatan Scalev, custom domain, builder homepage dan checkout, footer pages, OTP, custom HTML, dan analytics. Pengaturan Storefront API dipakai untuk storefront API-only saat Anda mengatur frontend 100%.

​
Arsitektur

Storefront API storefront bisa berupa static app di Cloudflare Pages, Vercel, Netlify, atau CDN lain. Browser memanggil https://api.scalev.com secara langsung. Gunakan fetch dengan credentials: "omit" untuk panggilan Storefront API dari browser: 
await fetch(`https://api.scalev.com/v3/stores/${storeId}/public/products`, {
  credentials: "omit",
  headers: {
    "X-Scalev-Storefront-Api-Key": storefrontApiKey,
  },
});
Kontinuitas guest cart memakai token header yang dikelola browser, bukan cookie cross-site. Lihat Auth untuk model Storefront API key, guest token, dan customer JWT.

​
Yang perlu diatur

Di dashboard, buka halaman konfigurasi store dan gunakan bagian Storefront API. Salin public Store ID. Integrasi baru sebaiknya memakai unique_id store, contoh: 
store_vlzpML8edzxO5roOdV7Oyfn6
Buat Storefront API key yang publishable: 
sfpk_...
Daftarkan setiap origin browser yang akan memanggil API: 
https://demo.scalev.shop
http://localhost:3000
CORS preflight untuk origin yang diizinkan mencakup X-Scalev-Storefront-Api-Key, X-Scalev-Guest-Token, Authorization, dan Content-Type.

​
Endpoint utama

GET  /v3/stores/{store_id}/public/products
GET  /v3/stores/{store_id}/public/products/{slug}
GET  /v3/stores/{store_id}/public/categories
GET  /v3/stores/{store_id}/public/payment-methods

GET  /v3/stores/{store_id}/public/locations/provinces
GET  /v3/stores/{store_id}/public/locations/cities?province_id=31
GET  /v3/stores/{store_id}/public/locations/subdistricts?city_id=3171
GET  /v3/stores/{store_id}/public/locations?search=Cempaka%20Putih
GET  /v3/stores/{store_id}/public/locations/{location_id}/postal-codes

GET  /v3/stores/{store_id}/public/cart
POST /v3/stores/{store_id}/public/cart/items
PATCH /v3/stores/{store_id}/public/cart/items/{item_id}
DELETE /v3/stores/{store_id}/public/cart/items/{item_id}

POST /v3/stores/{store_id}/public/checkout/shipping-options
POST /v3/stores/{store_id}/public/checkout/summary
POST /v3/stores/{store_id}/public/guest-checkout
GET  /v3/stores/{store_id}/public/orders/{secret_slug}
PATCH /v3/stores/{store_id}/public/orders/{secret_slug}
POST /v3/stores/{store_id}/public/orders/{secret_slug}/payment
POST /v3/stores/{store_id}/public/discount-codes/check
Search location memakai cursor pagination. Saat has_next bernilai true, gunakan next_cursor untuk mengambil halaman berikutnya.

​
Alur checkout browser-only

  1. Muat katalog dengan GET /public/products, GET /public/categories, dan route detail produk.
  2. Buat atau baca guest cart dengan GET /public/cart; simpan X-Scalev-Guest-Token dari response.
  3. Kirim X-Scalev-Guest-Token pada request add, update, remove, checkout, dan pembacaan cart berikutnya.
  4. Ambil opsi checkout dengan GET /public/payment-methods dan endpoint public location/postal-code.
  5. Daftar opsi pengiriman dengan POST /public/checkout/shipping-options. Cart dari X-Scalev-Guest-Token jadi sumber item; jika kosong, kirim items[] berisi variant ID langsung di body.
  6. Hitung ulang total dengan POST /public/checkout/summary setelah pembeli memilih courier service dan metode pembayaran. API mengabaikan shipping_cost dari client dan menghitung ulang dari courier service, warehouse, metode pembayaran, destinasi, dan item cart yang dipilih.
  7. Opsional, validasi kode diskon dengan POST /public/discount-codes/check. Kirim { "code": "..." } di body request, bersama konteks checkout opsional (payment_method, destination, courier_service_id, warehouse_unique_id, courier_aggregator_code, net_product_price, gross_revenue, shipping_cost). Jika X-Scalev-Guest-Token menghasilkan guest cart yang tidak kosong, cart digunakan sebagai sumber item; jika tidak, kirim items[] langsung dengan variant ID. Kode yang tidak dikenal atau tidak memenuhi syarat mengembalikan is_eligible: false; route hanya mengembalikan 404 jika store tidak ditemukan.
  8. Buat order dengan POST /public/guest-checkout.
  9. Baca order melalui GET /public/orders/{secret_slug} dan update field buyer seperti transferproof_url, transfer_time, atau notes dengan PATCH /public/orders/{secret_slug}.
  10. Panggil POST /public/orders/{secret_slug}/payment; render instruksi payment yang dikembalikan atau yang sudah ada di payment page Anda sendiri, dan gunakan payment_url hanya sebagai hosted fallback.
  11. Untuk akun customer, mulai dari /public/auth/login, lalu panggil /customers/me/* dengan customer JWT.
Lihat Checkout dan Payment untuk panduan shipping option, summary, dan rendering payment per metode.

​
Response payment

Endpoint public order mengembalikan status order, total, pengiriman, item, dan instruksi pembayaran yang aman dilihat buyer. Endpoint ini tidak mengembalikan konfigurasi store atau handler khusus dashboard. Endpoint payment public bersifat idempotent saat instruksi pembayaran atau payment_url sudah tersedia. Response payment menjelaskan cara storefront merender langkah pembayaran berikutnya. Metode manual seperti bank_transfer dan cod dapat mengembalikan pg_payment_info kosong sementara public order yang membawa instruksi buyer untuk dirender. Virtual account mengembalikan referensi provider dan detail akun di bawah objek payment_method provider. QRIS mengembalikan data QR atau payload QR image. E-wallet, card, dan invoice dapat mengembalikan provider actions atau URL hosted provider. Storefront sebaiknya merender halaman pembayarannya sendiri dari field tersebut dan memakai payment_url hanya sebagai hosted fallback.

​
Setup API

Endpoint setup memerlukan akses bisnis terautentikasi. Gunakan public Store ID untuk client baru; numeric store ID lama masih diterima. 
GET    /v3/stores/{store_id}/public-api-keys
POST   /v3/stores/{store_id}/public-api-keys
DELETE /v3/stores/{store_id}/public-api-keys/{id}

GET    /v3/stores/{store_id}/storefront/allowed-origins
POST   /v3/stores/{store_id}/storefront/allowed-origins
DELETE /v3/stores/{store_id}/storefront/allowed-origins/{id}