# API

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

***

## **เอกสารอ้างอิง API**

สำหรับเอกสารประกอบ endpoint แบบละเอียด โปรดไปที่: <https://rest.boxhero.io/docs/api>

***

## Endpoint

คำขอ API ทั้งหมดควรถูกส่งไปยัง URL ฐานต่อไปนี้:\ <mark style="color:สีน้ำเงิน;"><https://rest.boxhero-app.com></mark>

## **การยืนยันตัวตน**

คำขอ API ทั้งหมดต้องมี **Authorization** **ส่วนหัว** พร้อม **Bearer** **โทเค็น**:

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

เพื่อขอรับโทเค็น API:

1. เข้าสู่ระบบบัญชี BoxHero ของคุณบน Desktop (เว็บ)
2. ไปที่ <mark style="color:สีน้ำเงิน;">`การตั้งค่า`</mark> > <mark style="color:สีน้ำเงิน;">`การผสานการทำงาน`</mark>.
3. สร้างโทเค็น API ใหม่

## **การส่งคำขอ**

นี่คือตัวอย่างคำขอ API เพื่อดึงข้อมูลสินค้า

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

## การจำกัดอัตรา

เพื่อให้ระบบมีเสถียรภาพ เรากำหนดข้อจำกัดอัตราดังต่อไปนี้:

* 5 คำขอต่อวินาทีสำหรับแต่ละ endpoint

เมื่อคุณถูกจำกัดอัตรา คุณจะเห็นข้อความแสดงข้อผิดพลาดดังต่อไปนี้:

* `X-Ratelimit-Limit` - จำนวนคำขอสูงสุดต่อนาที
* `X-Ratelimit-Remaining` - จำนวนคำขอที่เหลือ
* `X-Ratelimit-Reset` - เวลาที่เหลือ (เป็นวินาที) จนกว่าจำนวนคำขอจะถูกรีเซ็ต

***

## การตอบกลับ

### สำเร็จ

การตอบกลับที่มีรหัสสถานะ HTTP ในช่วง 200 แสดงว่าการประมวลผล API สำเร็จ

### ข้อผิดพลาด

รหัสสถานะในช่วง 400 หรือ 500 แสดงว่าการร้องขอ API ล้มเหลว:

* ช่วง 400: ข้อผิดพลาดฝั่งไคลเอนต์จากข้อมูลที่ส่งมากับคำขอ (เช่น พารามิเตอร์ที่จำเป็นขาดหายไป)
* ช่วง 500: ข้อผิดพลาดฝั่งเซิร์ฟเวอร์

**ตัวอย่างการตอบกลับข้อผิดพลาด:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "โทเค็นการยืนยันตัวตนไม่ถูกต้อง โปรดระบุโทเค็นที่ถูกต้อง",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** รหัสเฉพาะเพื่อระบุข้อผิดพลาด
* **type :** รหัสในรูปแบบ URL ที่ระบุประเภทของข้อผิดพลาด
* **title :** แสดงเนื้อหาของข้อผิดพลาดในรูปแบบที่อ่านเข้าใจได้
* **correlation\_id :** ชี้ไปยังรหัสของคำขอที่เกี่ยวข้องกับข้อผิดพลาด
* **อื่น ๆ :** อาจมีการรวมฟิลด์เพิ่มเติมเพื่อให้ข้อมูลเพิ่มเติม เช่น "*given*" ในตัวอย่าง

### ประเภทข้อผิดพลาดที่พบบ่อย

<table><thead><tr><th width="252">ประเภท</th><th>คำอธิบาย</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>ไม่พบทรัพยากรที่ร้องขอ (เช่น ไอเท็มที่มี ID เฉพาะไม่มีอยู่)</td></tr><tr><td>/errors/invalid-request</td><td>พารามิเตอร์ในคำขอไม่ถูกต้อง</td></tr><tr><td>/errors/invalid-team-mode</td><td>ไม่สามารถประมวลผลคำขอที่ร้องขอได้ในโหมดทีมปัจจุบัน (เช่น การใช้ <em>location</em> API สำหรับค้นหาใน <em>โหมดพื้นฐาน</em>).</td></tr><tr><td>/errors/tokens/required</td><td>ไม่มีโทเค็น API</td></tr><tr><td>/errors/tokens/invalid</td><td>โทเค็น API ไม่ถูกต้อง (เช่น โทเค็น API หมดอายุแล้ว)</td></tr><tr><td>/errors/too-many-requests</td><td>เกินขีดจำกัดอัตรา</td></tr><tr><td>/errors/unhandled</td><td>ข้อผิดพลาดฝั่งเซิร์ฟเวอร์ที่ยังไม่ได้รับการแก้ไข</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>ใช้ถึงขีดจำกัดการใช้งานแล้ว ต้องอัปเกรดแพ็กเกจ</td></tr></tbody></table>

## การแบ่งหน้า

สำหรับ endpoint ที่ส่งกลับชุดข้อมูลขนาดใหญ่ (เช่น รายการไอเท็ม รายการธุรกรรม) มุมมองรายการ API จะจำกัดจำนวนไอเท็มที่ส่งกลับในคำขอเดียวผ่านการแบ่งหน้า เราใช้การแบ่งหน้าแบบ cursor-based:

{% hint style="info" %}
เพื่อพิจารณาว่าจำเป็นต้องแบ่งหน้าหรือไม่ ให้ตรวจสอบว่ามีพารามิเตอร์ที่เกี่ยวข้องกับการแบ่งหน้าปรากฏอยู่ในเนื้อหาคำขอของ endpoint ในเอกสาร API หรือไม่
{% endhint %}

#### **พารามิเตอร์การแบ่งหน้า**

* `has_more` : ค่าบูลีนที่ระบุว่ามีข้อมูลเพิ่มเติมนอกเหนือจากหน้าปัจจุบันหรือไม่
* `cursor` : ให้ค่าคอร์เซอร์สำหรับการดึงหน้าถัดไป

#### **การดึงหน้าถัดไป**

* ตรวจสอบว่า `has_more` เป็น `true`. หมายความว่ายังมีหน้าอื่นให้ใช้งาน
* หาก `true`ให้ส่งคำขออีกครั้งโดยรวม `cursor={received cursor value}` ในพารามิเตอร์ ซึ่งจะส่งคืนข้อมูลถัดไป
* ทำซ้ำจนกว่า `has_more` เป็น `false` เพื่อดึงรายการทั้งหมด

***

## การสนับสนุนและข้อเสนอแนะ

หากคุณพบปัญหาหรือต้องการฟังก์ชัน API เพิ่มเติม โปรดติดต่อ [ทีมสนับสนุน](https://docs-en.boxhero.io/etc/contact). เรายินดีรับข้อเสนอแนะของคุณเพื่อปรับปรุง API และคำขอฟีเจอร์ใหม่

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