# API

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

***

## **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 menyertakan sebuah <mark style="color:biru;">**Authorization**</mark> pengepala dengan <mark style="color:biru;">**token Bearer**</mark>:

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

Untuk mendapatkan token API:

1. Log masuk ke akaun BoxHero anda di Desktop (Web).
2. Pergi ke <mark style="color:biru;">**`Tetapan`**</mark> > <mark style="color:biru;">**`Integrasi`**</mark>.
3. Jana 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 untuk setiap titik akhir.

Setelah anda dikenakan had kadar, anda akan melihat mesej ralat dengan yang 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 pihak klien daripada maklumat yang disediakan dengan permintaan (cth., parameter yang diperlukan tiada).
* Julat 500: Ralat pihak 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 :** Berikan kandungan ralat dalam bentuk yang mudah dibaca oleh manusia.
* **correlation\_id :** Menunjuk kepada ID permintaan yang berkaitan dengan ralat.
* **lain-lain :** Medan tambahan mungkin disertakan untuk memberikan maklumat tambahan, seperti "*given*" dalam contoh.

### Jenis Ralat Lazim

<table><thead><tr><th width="252">Jenis</th><th>Penerangan</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 pihak pelayan yang tidak diselesaikan.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Had penggunaan telah dicapai. Naik taraf pelan diperlukan.</td></tr></tbody></table>

## Paginasi

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

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

#### **Parameter Paginasi**

* `has_more` : Nilai boolean yang menunjukkan sama ada masih ada data selepas halaman semasa.
* `cursor` : Menyediakan nilai cursor untuk mendapatkan halaman seterusnya.

#### **Mendapatkan Halaman Seterusnya**

* Semak jika `has_more` ialah `benar`. Ini bermaksud terdapat halaman lain yang tersedia.
* Jika `benar`, hantar satu lagi permintaan termasuk `cursor={received cursor value}` dalam parameter. Ini akan mengembalikan data seterusnya.
* Ulang sehingga `has_more` ialah `palsu` 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.