# API

<figure><img src="/files/f830a96ef8977c0b956fc8c99e44a16f46b4c0ed" alt=""><figcaption></figcaption></figure>

***

## **Referensi API**

Untuk dokumentasi endpoint yang lebih detail, 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 sebuah **Authorization** **header** dengan **Bearer** **token**:

```
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. Hasilkan token API baru.

## **Melakukan 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 kesalahan dengan berikut:

* `X-Ratelimit-Limit` - Maksimum kueri per menit
* `X-Ratelimit-Remaining` - Sisa kueri
* `X-Ratelimit-Reset` - Waktu (dalam detik) yang tersisa hingga penghitung kueri direset

***

## Respons

### Sukses

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

### Kesalahan

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

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

**Contoh Respons Kesalahan:**

```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 kesalahan.
* **type :** Kode dalam bentuk URL yang mengidentifikasi jenis kesalahan.
* **title :** Menjelaskan isi kesalahan dalam bentuk yang mudah dibaca manusia.
* **correlation\_id :** Mengarah ke ID permintaan yang terkait dengan kesalahan.
* **lainnya :** Bidang tambahan dapat disertakan untuk memberikan informasi tambahan, seperti "*given*" pada contoh.

### Jenis Kesalahan 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 dalam permintaan tidak valid.</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> di <em>Mode Dasar</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Token API hilang.</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 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 मौजूद dalam body permintaan endpoint pada dokumentasi API.
{% endhint %}

#### **Parameter Paginasi**

* `has_more` : Sebuah nilai boolean yang menunjukkan apakah ada data lain 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 dengan menyertakan `cursor={received cursor value}` dalam parameter. Ini akan mengembalikan data berikutnya.
* Ulangi hingga `has_more` adalah `false` untuk mengambil daftar lengkap.

***

## Dukungan dan Masukan

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/id/integrasi/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.