# API

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

***

## **Tài liệu tham khảo API**

Để xem tài liệu chi tiết về endpoint, vui lòng truy cập: <https://rest.boxhero.io/docs/api>

***

## Endpoint

Tất cả các yêu cầu API nên được gửi đến URL gốc sau:\ <mark style="color:xanh dương;"><https://rest.boxhero-app.com></mark>

## **Xác thực**

Tất cả các yêu cầu API phải bao gồm một <mark style="color:xanh dương;">**Authorization**</mark> trong header cùng với một <mark style="color:xanh dương;">**mã Bearer**</mark>:

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

Để lấy mã API token:

1. Đăng nhập vào tài khoản BoxHero của bạn trên Desktop (Web).
2. Đi tới <mark style="color:xanh dương;">**`Cài đặt`**</mark> > <mark style="color:xanh dương;">**`Tích hợp`**</mark>.
3. Tạo một mã API token mới.

## **Thực hiện yêu cầu**

Đây là một yêu cầu API mẫu để lấy sản phẩm.

```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'
```

## Giới hạn tần suất

Để đảm bảo hệ thống ổn định, chúng tôi áp dụng các giới hạn tần suất sau:

* 5 truy vấn mỗi giây cho mỗi endpoint.

Khi bạn bị giới hạn tần suất, bạn sẽ thấy một thông báo lỗi với các nội dung sau:

* `X-Ratelimit-Limit` - Số truy vấn tối đa mỗi phút
* `X-Ratelimit-Remaining` - Số truy vấn còn lại
* `X-Ratelimit-Reset` - Thời gian (tính bằng giây) còn lại cho đến khi bộ đếm truy vấn được đặt lại

***

## Phản hồi

### Thành công

Các phản hồi có mã trạng thái HTTP trong khoảng 200 cho biết API đã xử lý thành công.

### Lỗi

Các mã trạng thái trong khoảng 400 hoặc 500 cho biết yêu cầu API thất bại:

* Khoảng 400: Lỗi phía client do thông tin được cung cấp trong yêu cầu (ví dụ: thiếu tham số bắt buộc).
* Khoảng 500: Lỗi phía máy chủ.

**Ví dụ phản hồi lỗi:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Mã xác thực không hợp lệ. Vui lòng cung cấp một mã hợp lệ.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** Một ID duy nhất để xác định lỗi.
* **type :** Một mã ở dạng URL dùng để xác định loại lỗi.
* **title :** Cung cấp nội dung lỗi dưới dạng dễ đọc đối với con người.
* **correlation\_id :** Trỏ tới ID của yêu cầu liên quan đến lỗi.
* **khác :** Có thể bao gồm các trường bổ sung để cung cấp thêm thông tin, chẳng hạn như "*given*" trong ví dụ.

### Các loại lỗi phổ biến

<table><thead><tr><th width="252">Loại</th><th>Mô tả</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Không tìm thấy tài nguyên được yêu cầu (ví dụ: mục có ID cụ thể không tồn tại).</td></tr><tr><td>/errors/invalid-request</td><td>Tham số không hợp lệ trong yêu cầu.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Truy vấn được yêu cầu không thể được xử lý trong chế độ nhóm hiện tại (ví dụ: sử dụng API tra cứu <em>location</em> trong <em>Chế độ cơ bản</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Thiếu mã API token.</td></tr><tr><td>/errors/tokens/invalid</td><td>Mã API token không hợp lệ (ví dụ: mã API token đã hết hạn).</td></tr><tr><td>/errors/too-many-requests</td><td>Đã vượt quá giới hạn tần suất.</td></tr><tr><td>/errors/unhandled</td><td>Lỗi phía máy chủ chưa được xử lý.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Đã đạt đến giới hạn sử dụng. Cần nâng cấp gói.</td></tr></tbody></table>

## Phân trang

Đối với các endpoint trả về bộ dữ liệu lớn (ví dụ: danh sách mặt hàng, danh sách giao dịch), API chế độ xem danh sách giới hạn số lượng mục được trả về trong một yêu cầu duy nhất thông qua phân trang. Chúng tôi sử dụng phân trang dựa trên con trỏ:

{% hint style="info" %}
Để xác định liệu có cần phân trang hay không, hãy kiểm tra xem các tham số liên quan đến phân trang có xuất hiện trong phần thân yêu cầu của endpoint trong tài liệu API hay không.
{% endhint %}

#### **Tham số phân trang**

* `has_more` : Một giá trị boolean cho biết liệu có thêm dữ liệu ngoài trang hiện tại hay không.
* `cursor` : Cung cấp giá trị con trỏ để lấy trang tiếp theo.

#### **Lấy trang tiếp theo**

* Kiểm tra xem `has_more` có phải là `true`. Điều đó có nghĩa là còn một trang khác có sẵn.
* Nếu `true`, hãy gửi một yêu cầu khác bao gồm `cursor={received cursor value}` trong các tham số. Điều này sẽ trả về dữ liệu tiếp theo.
* Lặp lại cho đến khi `has_more` có phải là `false` để lấy toàn bộ danh sách.

***

## Hỗ trợ và phản hồi

Nếu bạn gặp sự cố hoặc cần thêm chức năng API, vui lòng liên hệ với [đội ngũ hỗ trợ](https://docs-en.boxhero.io/etc/contact). Chúng tôi hoan nghênh phản hồi của bạn để cải tiến API và đề xuất tính năng mới.