# API

<figure><img src="/files/03cda734592eb50becbe1177dd02fdfe43f2c34f" alt=""><figcaption></figcaption></figure>

***

## **Rujukan API**

Untuk dokumentasi titik akhir yang terperinci, sila lawati: <https://rest.boxhero.io/docs/api>

***

## Titik Akhir

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

## **Pengesahan**

Semua permintaan API mesti mengandungi **Authorization** **header** dengan **Bearer** **token**:

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

Untuk mendapatkan token API:

1. Log masuk ke akaun BoxHero anda pada Desktop (Web).
2. Pergi ke <mark style="color:biru;">`Tetapan`</mark> > <mark style="color:biru;">`Integrasi`</mark>.
3. Hasilkan token API baharu.

## **Membuat Permintaan**

Berikut ialah contoh permintaan API untuk mendapatkan 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'
```

## Had Kadar

Untuk memastikan kestabilan sistem, kami mengenakan had kadar berikut:

* 5 pertanyaan sesaat bagi setiap titik akhir.

Setelah anda dihadkan oleh kadar, anda akan melihat mesej ralat dengan perkara berikut:

* `X-Ratelimit-Limit` - Maksimum pertanyaan per minit
* `X-Ratelimit-Remaining` - Pertanyaan yang tinggal
* `X-Ratelimit-Reset` - Masa (dalam saat) yang tinggal sehingga kiraan pertanyaan diset semula

***

## Respons

### Berjaya

Respons dengan kod status HTTP dalam julat 200 menunjukkan pemprosesan API berjaya.

### Ralat

Kod status dalam julat 400 atau 500 menunjukkan kegagalan permintaan API:

* Julat 400: Ralat sisi klien daripada maklumat yang diberikan dengan permintaan (cth., parameter wajib yang hilang).
* Julat 500: Ralat sisi pelayan.

**Contoh Respons Ralat:**

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

* **id :** ID unik untuk mengenal pasti ralat.
* **type :** Kod dalam bentuk URL yang mengenal pasti jenis ralat.
* **title :** Sediakan kandungan ralat dalam bentuk yang boleh dibaca oleh manusia.
* **correlation\_id :** Merujuk kepada ID permintaan yang dikaitkan dengan ralat.
* **lain-lain :** Medan tambahan boleh disertakan untuk memberikan maklumat tambahan, seperti "*given*" dalam contoh.

### Jenis Ralat Lazim

<table><thead><tr><th width="252">Jenis</th><th>Huraian</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Sumber yang diminta tidak ditemui (cth., item dengan ID tertentu tidak wujud).</td></tr><tr><td>/errors/invalid-request</td><td>Parameter tidak sah dalam permintaan.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Pertanyaan yang diminta tidak dapat diproses dalam mod pasukan semasa (cth., menggunakan API carian <em>location</em> dalam <em>Mod Asas</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Token API tiada.</td></tr><tr><td>/errors/tokens/invalid</td><td>Token API tidak sah (cth., token API telah tamat tempoh).</td></tr><tr><td>/errors/too-many-requests</td><td>Melebihi had kadar.</td></tr><tr><td>/errors/unhandled</td><td>Ralat sisi pelayan yang tidak dapat diselesaikan.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Mencapai had penggunaan. Naik taraf pelan diperlukan.</td></tr></tbody></table>

## Paginasi

Untuk titik akhir yang mengembalikan set data yang besar (cth., senarai item, senarai transaksi), API paparan senarai mengehadkan bilangan item yang dikembalikan dalam satu permintaan melalui paginasi. Kami menggunakan paginasi berasaskan kursor:

{% hint style="info" %}
Untuk menentukan sama ada paginasi diperlukan, semak sama ada parameter berkaitan paginasi hadir dalam badan permintaan bagi titik akhir dalam dokumentasi API.
{% endhint %}

#### **Parameter Paginasi**

* `has_more` : Nilai boolean yang menunjukkan sama ada terdapat lebih banyak data di luar halaman semasa.
* `cursor` : Menyediakan nilai kursor untuk mendapatkan halaman seterusnya.

#### **Mendapatkan Halaman Seterusnya**

* Semak sama ada `has_more` ialah `true`. Ini bermaksud ada halaman lain yang tersedia.
* Jika `true`, hantar permintaan lain termasuk `cursor={received cursor value}` dalam parameter. Ini akan mengembalikan data seterusnya.
* Ulang sehingga `has_more` ialah `false` untuk mendapatkan senarai penuh.

***

## Sokongan dan Maklum Balas

Jika anda menghadapi masalah atau memerlukan fungsi API tambahan, sila hubungi [pasukan sokongan](https://docs-en.boxhero.io/etc/contact). Kami mengalu-alukan maklum balas anda untuk penambahbaikan API dan permintaan ciri baharu.

{% 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/ms/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.