> ## 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.

# Pendahuluan

> Buat storefront custom di browser dengan Scalev sebagai backend commerce.

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%.

<Warning>
  **Panggil Storefront API v3 langsung dari browser**

  Storefront API v3 dirancang untuk dipanggil langsung dari browser atau client end-user. Jangan menaruh Storefront API v3 di balik backend proxy, reverse proxy, middleware, edge function, serverless function, atau pass-through API layer milik Anda sendiri.

  Rate limiter untuk Storefront API v3 sengaja dibuat ketat karena API ini dirancang untuk penggunaan client-side langsung. Jika request ini diproxy, banyak user dapat terlihat datang dari IP server yang sama, sehingga rate limiting, deteksi spam, proteksi order duplikat, dan logika validasi lain dapat terdampak negatif.

  Untuk deployment headless storefront, anggap browser sebagai caller yang dimaksud untuk Storefront API v3. Gunakan backend Anda sendiri hanya untuk hal non-Scalev seperti admin settings, custom business logic, atau private integrations.
</Warning>

<Warning>
  **Syarat paket berlangganan**

  Request runtime Storefront API tersedia untuk bisnis dengan paket aktif Basic, Pro, atau Ultimate. Merchant di paket Free atau Lite tetap bisa mengatur public Store ID, API key publishable, dan allowed origin, tetapi panggilan API akan mengembalikan response `Store not found` yang sama sampai bisnis upgrade atau mengaktifkan lagi paket yang eligible.
</Warning>

## Urutan baca yang disarankan

1. Mulai dari halaman ini untuk memahami arsitektur, kebutuhan setup, dan peta endpoint.
2. Baca [Auth](/id/storefront-api-id/auth) untuk Storefront API key, guest cart token, dan customer JWT.
3. Baca [Checkout dan Payment](/id/storefront-api-id/checkout-payments) untuk shipping, checkout summary, pembuatan order, dan rendering payment.
4. Baca [Event konversi iklan](/id/storefront-api-id/advertising-conversion-events) jika storefront menjalankan iklan Meta, TikTok, atau SnackVideo.
5. Akhiri dengan [Bangun storefront](/id/storefront-api-id/build-a-browser-only-storefront) sebagai panduan implementasi lengkap A-Z.

## 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:

```js theme={null}
await fetch(`https://api.scalev.com/v3/stores/${storeId}/public/items`, {
  credentials: "omit",
  headers: {
    "X-Scalev-Storefront-Api-Key": storefrontApiKey,
  },
});
```

Kontinuitas guest cart memakai token header yang dikelola browser, bukan cookie cross-site. Lihat [Auth](/id/storefront-api-id/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:

```text theme={null}
store_vlzpML8edzxO5roOdV7Oyfn6
```

Buat Storefront API key yang publishable:

```text theme={null}
sfpk_...
```

Daftarkan setiap origin browser yang akan memanggil API:

```text theme={null}
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

```text theme={null}
GET  /v3/stores/{store_id}/public/items
GET  /v3/stores/{store_id}/public/items/count
GET  /v3/stores/{store_id}/public/products/{slug}
GET  /v3/stores/{store_id}/public/bundle-price-options/{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/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/orders/{secret_slug}/transfer-proof-upload
POST /v3/stores/{store_id}/public/discount-codes/check

POST /v3/stores/{store_id}/public/analytics/meta/events
POST /v3/stores/{store_id}/public/analytics/tiktok/events
POST /v3/stores/{store_id}/public/analytics/snackvideo/events
```

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/items`, `GET /public/categories`, dan route detail.
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`. Direct `items` bertipe menjadi sumber item jika dikirim; jika tidak, gunakan `X-Scalev-Guest-Token` untuk guest cart.
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 checkout.
7. Opsional, validasi kode diskon dengan `POST /public/discount-codes/check`. Kirim `{ "code": "..." }` di body request, bersama konteks checkout opsional (`items`, `payment_method`, `destination`, `courier_service_id`, `warehouse_unique_id`, `courier_aggregator_code`, `net_product_price`, `gross_revenue`, `shipping_cost`). 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/checkout` memakai direct `items` bertipe, guest cart token, atau keduanya.
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. Untuk manual `bank_transfer`, minta URL upload bukti transfer dengan `POST /public/orders/{secret_slug}/transfer-proof-upload`, upload image, lalu patch order dengan `file_url` yang dikembalikan.
11. 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.
12. Untuk akun customer, mulai dari `/public/auth/login`, lalu panggil `/customers/me/*` dengan customer JWT.

Lihat [Checkout dan Payment](/id/storefront-api-id/checkout-payments) untuk panduan shipping option, summary, dan rendering payment per metode.

## Analytics Conversion API

Gunakan Scalev sebagai server-side relay untuk event konversi Meta, TikTok, dan SnackVideo dari storefront browser. Panggilan ini memakai pixel yang sama dengan konfigurasi Storefront analytics bawaan, tetapi route Storefront API memilih toko dari `/v3/stores/{store_id}` dan `X-Scalev-Storefront-Api-Key`; jangan mengirim custom domain untuk mengidentifikasi toko.

```text theme={null}
POST /v3/stores/{store_id}/public/analytics/meta/events
POST /v3/stores/{store_id}/public/analytics/tiktok/events
POST /v3/stores/{store_id}/public/analytics/snackvideo/events
```

Endpoint mengembalikan `204 No Content` setelah menerima payload untuk dikirim secara asynchronous. Lihat [Event konversi iklan](/id/storefront-api-id/advertising-conversion-events) untuk setup client pixel, cookie atribusi, penamaan event, contoh payload, dan deduplikasi Meta/TikTok.

## Response payment

Setelah guest checkout, membaca public order, atau membuat instruksi payment, response berisi data order ringkas yang dibutuhkan storefront untuk menampilkan langkah berikutnya ke pembeli: identity order, `public_order_url`, `payment_url`, status, total, object map `variants` dan `bundle_price_options` yang sudah ada, line item, detail pengiriman, dan field payment seperti `payment_method`, `sub_payment_method`, `payment_account_holder`, `payment_account_number`, `transferproof_url`, dan `pg_payment_info`. Response ini sengaja tidak mengembalikan ID order internal, revenue khusus dashboard, platform fee, payment-status history, dan atribusi affiliate. Di v3, field tersebut ada langsung di object JSON, bukan di dalam envelope `data` lama.

Route order akun customer mengembalikan data order yang lebih kecil dan aman untuk customer yang sedang login. Response ini mempertahankan data order yang terlihat oleh pembeli dan menghapus detail khusus dashboard seperti analytics bisnis, fee internal, provider internals, riwayat CRM, data affiliate, dan raw metadata.

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.

```text theme={null}
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}
```