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

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

<Columns cols={2}>
  <Card title="Pilih metode autentikasi" icon="key" href="/id/autentikasi-dengan-api-key">
    Gunakan API key untuk integrasi server-side, atau OAuth saat Anda membutuhkan alur otorisasi merchant.
  </Card>

  <Card title="Otorisasi dengan OAuth" icon="shield-check" href="/id/otorisasi-dengan-o-auth">
    Hubungkan akun bisnis Scalev ke aplikasi Anda dengan alur otorisasi OAuth.
  </Card>

  <Card title="Hubungkan asisten AI" icon="sparkles" href="/id/konektor-scalev-mcp">
    Gunakan konektor Scalev MCP untuk memberi asisten AI yang didukung akses Scalev melalui OAuth.
  </Card>
</Columns>

## Bangun integrasi Anda

<Columns cols={2}>
  <Card title="Buat pesanan" icon="shopping-cart" href="/id/membuat-pesanan">
    Buat pesanan produk digital atau fisik dan arahkan pelanggan ke halaman pembayaran.
  </Card>

  <Card title="Terima webhook" icon="webhook" href="/id/ringkasan-webhooks">
    Subscribe ke event dan verifikasi request webhook sebelum Anda memprosesnya.
  </Card>

  <Card title="Buka Referensi API" icon="code" href="https://api-openapi.scalev.com/specs/v3/openapi.json">
    Periksa endpoint, parameter, request body, dan schema respons dari referensi OpenAPI.
  </Card>

  <Card title="Baca changelog" icon="newspaper" href="/id/changelog">
    Ikuti pembaruan produk dan perubahan dokumentasi saat API berkembang.
  </Card>
</Columns>

## Base URL

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

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

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

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "id": "ord_123",
  "status": "paid"
}
```

### Respons Sukses untuk Koleksi Tanpa Paginasi

```json theme={null}
{
  "data": [
    {
      "id": "prod_123"
    }
  ],
  "is_paginated": false
}
```

### Respons Sukses untuk Koleksi dengan Paginasi

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

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

```json theme={null}
{
  "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.