# API

<figure><img src="/files/096d4cf2584adbd09aa9011086b9acfacf182869" alt=""><figcaption></figcaption></figure>

***

## **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 **Authorization** **tiêu đề** với một **Bearer** **mã token**:

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

Để lấy mã token API:

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ã token API mới.

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

Đây là một yêu cầu API mẫu để truy xuất 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ốc độ

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

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

Khi bạn bị giới hạn tốc độ, bạn sẽ thấy một thông báo lỗi với 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 số truy vấn được đặt lại

***

## Phản hồi

### Thành công

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

### Lỗi

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

* Phạm vi 400: Lỗi phía khách hàng do thông tin được cung cấp trong yêu cầu (ví dụ: thiếu các tham số bắt buộc).
* Phạm vi 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ã token xác thực không hợp lệ. Vui lòng cung cấp một mã token 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 của lỗi dưới dạng dễ đọc cho con người.
* **correlation\_id :** Chỉ đến ID của yêu cầu liên quan đến lỗi.
* **khác :** Có thể bao gồm thêm các trường để cung cấp thông tin bổ sung, 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>Yêu cầu truy vấn không thể được xử lý ở 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ã token API.</td></tr><tr><td>/errors/tokens/invalid</td><td>Mã token API không hợp lệ (ví dụ: mã token API đã hết hạn).</td></tr><tr><td>/errors/too-many-requests</td><td>Đã vượt quá giới hạn tốc độ.</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 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ề tập dữ liệu lớn (ví dụ: danh sách mục, 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 bằng phân trang. Chúng tôi sử dụng phân trang dựa trên cursor:

{% 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 có còn dữ liệu nào khác ngoài trang hiện tại hay không.
* `cursor` : Cung cấp giá trị cursor để truy xuất trang tiếp theo.

#### **Truy xuất trang tiếp theo**

* Kiểm tra xem `has_more` có `đúng`. Điều đó có nghĩa là còn một trang khác khả dụng.
* Nếu `đúng`thì gửi một yêu cầu khác bao gồm `cursor={received cursor value}` trong các tham số. Việc này sẽ trả về dữ liệu tiếp theo.
* Lặp lại cho đến khi `has_more` có `sai` để truy xuất 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 luôn hoan nghênh phản hồi của bạn để cải thiện API và đề xuất tính năng mới.

{% 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/vi/tich-hop/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.