# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **Referensi API**

Untuk dokumentasi endpoint yang lebih rinci, silakan kunjungi: <https://rest.boxhero.io/docs/api>

***

## Endpoint

Semua permintaan API harus diarahkan ke URL dasar berikut:\ <mark style="color:biru;"><https://rest.boxhero-app.com></mark>

## **Autentikasi**

Semua permintaan API harus menyertakan <mark style="color:biru;">**Authorization**</mark> header dengan <mark style="color:biru;">**token Bearer**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

Untuk mendapatkan token API:

1. Masuk ke akun BoxHero Anda di Desktop (Web).
2. Buka ke <mark style="color:biru;">**`Pengaturan`**</mark> > <mark style="color:biru;">**`Integrasi`**</mark>.
3. Buat token API baru.

## **Membuat Permintaan**

Berikut contoh permintaan API untuk mengambil produk.

```bash
curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'
```

## Batas Laju

Untuk memastikan stabilitas sistem, kami memberlakukan batas laju berikut:

* 5 kueri per detik untuk setiap endpoint.

Setelah Anda terkena batas laju, Anda akan melihat pesan error dengan berikut ini:

* `X-Ratelimit-Limit` - Jumlah kueri maksimum per menit
* `X-Ratelimit-Remaining` - Kueri yang tersisa
* `X-Ratelimit-Reset` - Waktu (dalam detik) yang tersisa hingga jumlah kueri direset

***

## Respons

### Berhasil

Respons dengan kode status HTTP dalam rentang 200 menunjukkan pemrosesan API berhasil.

### Error

Kode status dalam rentang 400 atau 500 menunjukkan kegagalan permintaan API:

* Rentang 400: Kesalahan sisi klien dari informasi yang diberikan bersama permintaan (misalnya, parameter wajib tidak ada).
* Rentang 500: Kesalahan sisi server.

**Contoh Respons Error:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Token autentikasi tidak valid. Silakan berikan token yang valid.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** ID unik untuk mengidentifikasi error.
* **type :** Kode dalam bentuk URL yang mengidentifikasi jenis error.
* **title :** Berikan isi error dalam bentuk yang mudah dibaca manusia.
* **correlation\_id :** Menunjuk ke ID permintaan yang terkait dengan error.
* **lainnya :** Bidang tambahan dapat disertakan untuk memberikan informasi tambahan, seperti "*given*" pada contoh.

### Jenis Error Umum

<table><thead><tr><th width="252">Jenis</th><th>Deskripsi</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Sumber daya yang diminta tidak ditemukan (misalnya, item dengan ID tertentu tidak ada).</td></tr><tr><td>/errors/invalid-request</td><td>Parameter tidak valid dalam permintaan.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Kueri yang diminta tidak dapat diproses dalam mode tim saat ini (misalnya, menggunakan API pencarian <em>location</em> dalam <em>Mode Dasar</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Token API tidak ada.</td></tr><tr><td>/errors/tokens/invalid</td><td>Token API tidak valid (misalnya, token API telah kedaluwarsa).</td></tr><tr><td>/errors/too-many-requests</td><td>Melebihi batas laju.</td></tr><tr><td>/errors/unhandled</td><td>Kesalahan sisi server yang belum terselesaikan.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Batas penggunaan telah tercapai. Diperlukan peningkatan paket.</td></tr></tbody></table>

## Paginasi

Untuk endpoint yang mengembalikan dataset besar (misalnya, daftar item, daftar transaksi), API tampilan daftar membatasi jumlah item yang dikembalikan dalam satu permintaan melalui paginasi. Kami menggunakan paginasi berbasis cursor:

{% hint style="info" %}
Untuk menentukan apakah paginasi diperlukan, periksa apakah parameter terkait paginasi ada di body permintaan endpoint dalam dokumentasi API.
{% endhint %}

#### **Parameter Paginasi**

* `has_more` : Nilai boolean yang menunjukkan apakah masih ada data di luar halaman saat ini.
* `cursor` : Menyediakan nilai cursor untuk mengambil halaman berikutnya.

#### **Mengambil Halaman Berikutnya**

* Periksa apakah `has_more` adalah `true`. Artinya ada halaman lain yang tersedia.
* Jika `true`, kirim permintaan lain yang menyertakan `cursor={nilai cursor yang diterima}` dalam parameter. Ini akan mengembalikan data berikutnya.
* Ulangi hingga `has_more` adalah `false` untuk mengambil seluruh daftar.

***

## Dukungan dan Masukan

Jika Anda mengalami masalah atau memerlukan fungsionalitas API tambahan, silakan hubungi [tim dukungan](https://docs-en.boxhero.io/etc/contact). Kami menyambut masukan Anda untuk perbaikan API dan permintaan fitur baru.