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.

Scalev API v3 adalah API commerce headless untuk integrasi storefront, pelanggan, dan bisnis terautentikasi. Anda dapat menggunakannya untuk menjalankan katalog, keranjang, checkout, pesanan, langganan, akses produk digital, dan alur kerja commerce terkait di aplikasi atau sistem Anda sendiri. Pendahuluan ini mencakup base URL, keluarga autentikasi, format respons, kode status, rate limit, dan model paginasi.

​
Mulai di sini

Pilih metode autentikasi

Gunakan API key untuk integrasi server-side, atau OAuth saat Anda membutuhkan alur otorisasi merchant.

Otorisasi dengan OAuth

Hubungkan akun bisnis Scalev ke aplikasi Anda dengan alur otorisasi OAuth.

​
Bangun integrasi Anda

Buat pesanan

Buat pesanan produk digital atau fisik dan arahkan pelanggan ke halaman pembayaran.

Terima webhook

Subscribe ke event dan verifikasi request webhook sebelum Anda memprosesnya.

Buka Referensi API

Periksa endpoint, parameter, request body, dan schema respons dari referensi OpenAPI.

Baca changelog

Ikuti pembaruan produk dan perubahan dokumentasi saat API berkembang.

​
Base URL

https://api.scalev.com
Semua endpoint yang didokumentasikan dalam referensi ini berada di bawah namespace /v3.

​
Autentikasi

Autentikasi bergantung pada kelompok rute:

​
Rute storefront publik

Rute storefront publik berbasis toko di bawah /v3/stores/{store_id}/public/* memerlukan kunci API storefront yang dapat dipublikasikan: 
X-Scalev-Storefront-Api-Key: sfpk_...
Gunakan unique_id store sebagai {store_id} untuk integrasi Storefront API baru. Pengaturan Storefront API terpisah dari pengaturan Storefront bawaan; bagian ini mengatur public Store ID, API key publishable, dan origin CORS yang diizinkan.

​
Rute pelanggan terautentikasi

Rute pelanggan menggunakan autentikasi bearer: 
Authorization: Bearer CUSTOMER_ACCESS_TOKEN
Token akses pelanggan diterbitkan oleh alur autentikasi pelanggan storefront. Login pelanggan yang sukses (saat OTP tidak diperlukan), verifikasi OTP, atau refresh JWT mengembalikan CustomerAuthTokenResponse: 
{
  "access": "CUSTOMER_ACCESS_TOKEN",
  "refresh": "CUSTOMER_REFRESH_TOKEN",
  "store_unique_id": "store_..."
}
Kirim access sebagai Authorization: Bearer <token> ke /v3/stores/{store_id}/customers/me/*. Gunakan refresh dengan POST /v3/stores/{store_id}/public/auth/jwt/refresh untuk mendapatkan token akses baru. store_unique_id dikembalikan oleh beberapa respons verifikasi OTP. Jika OTP diperlukan, POST /v3/stores/{store_id}/public/auth/login mengirim kode sekali pakai dan mengembalikan { "message": "..." }; pemanggil harus menampilkan input OTP lalu melakukan verifikasi OTP untuk menerima token.

​
Rute bisnis terautentikasi

Rute bisnis terautentikasi menggunakan autentikasi bearer dengan token akses atau kunci API bisnis: 
Authorization: Bearer YOUR_TOKEN_HERE

​
Format Respons Umum

Scalev API v3 tidak menggunakan envelope respons lama code / status / data.

​
Respons Sukses untuk Satu Sumber Daya

Respons sukses untuk satu sumber daya mengembalikan sumber daya secara langsung: 
{
  "id": "ord_123",
  "status": "paid"
}

​
Respons Sukses untuk Koleksi Tanpa Paginasi

{
  "data": [
    {
      "id": "prod_123"
    }
  ],
  "is_paginated": false
}

​
Respons Sukses untuk Koleksi dengan Paginasi

{
  "data": [
    {
      "id": "prod_123"
    }
  ],
  "is_paginated": true,
  "has_next": true,
  "has_previous": false,
  "next_cursor": "opaque-token",
  "previous_cursor": null,
  "page_size": 25
}

​
Respons Error

{
  "error": "Pesan error",
  "error_code": "kode_error_opsional"
}

​
Kode Status HTTP

API menggunakan kode status HTTP standar:
  • 200 OK - Permintaan baca, pembaruan, atau aksi berhasil
  • 201 Created - Permintaan pembuatan berhasil
  • 204 No Content - Permintaan berhasil tanpa body respons
  • 400 Bad Request - Format permintaan, parameter, atau kursor tidak valid
  • 401 Unauthorized - Autentikasi diperlukan atau token tidak valid
  • 403 Forbidden - Terautentikasi tetapi tidak diizinkan
  • 404 Not Found - Sumber daya tidak ditemukan
  • 409 Conflict - Konflik sumber daya
  • 422 Unprocessable Entity - Error validasi
  • 429 Too Many Requests - Rate limit terlampaui
  • 5xx - Error server tidak terduga

​
Rate Limiting

Permintaan API dapat terkena rate limit. Bucket-nya bergantung pada cara autentikasi:
  • Permintaan storefront publik yang menggunakan X-Scalev-Storefront-Api-Key atau X-Scalev-Guest-Token diperlakukan sebagai trafik browser/klien langsung dan menggunakan rate limiter berbasis klien/IP.
  • Permintaan bisnis terautentikasi mesin (API Key dan OAuth access token) menggunakan bucket berbasis kredensial: 10.000 permintaan per jam plus 100 permintaan per 10 detik untuk burst pendek per key atau instalasi OAuth.
Ketika rate limit diterapkan, informasi limit dikembalikan dalam header respons seperti:
  • X-Ratelimit-Limit
  • X-Ratelimit-Remaining
  • X-Ratelimit-Reset
Beberapa limit khusus endpoint lebih ketat. Respons rate-limit dapat berupa plain text, bukan bentuk error JSON normal.

​
Paginasi

Endpoint /v3 yang menggunakan paginasi memakai paginasi berbasis kursor opaque.

​
Parameter Permintaan

  • page_size - Jumlah item yang dikembalikan
  • next_cursor - Kursor untuk halaman berikutnya
  • previous_cursor - Kursor untuk halaman sebelumnya

​
Field Respons

  • data - Array item pada halaman saat ini
  • is_paginated - Selalu true untuk respons dengan paginasi
  • has_next - Apakah halaman berikutnya tersedia
  • has_previous - Apakah halaman sebelumnya tersedia
  • next_cursor - Kursor opaque untuk halaman berikutnya
  • previous_cursor - Kursor opaque untuk halaman sebelumnya
  • page_size - Jumlah item yang dikembalikan per halaman
{
  "data": [
    {
      "id": "prod_123"
    }
  ],
  "is_paginated": true,
  "has_next": true,
  "has_previous": false,
  "next_cursor": "opaque-token",
  "previous_cursor": null,
  "page_size": 25
}

​
Dukungan

Jika Anda mengalami masalah, hubungi tim dukungan Scalev.
Dokumentasi ini dapat berubah seiring perkembangan Scalev API.