# API

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

***

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

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

***

## Endpoint

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

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

คำขอ API ทั้งหมดต้องมี <mark style="color:blue;">**Authorization**</mark> header พร้อม <mark style="color:blue;">**Bearer token**</mark>:

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

เพื่อรับ API token:

1. เข้าสู่ระบบบัญชี BoxHero ของคุณบน Desktop (Web)
2. ไปที่ <mark style="color:blue;">**`Settings`**</mark> > <mark style="color:blue;">**`Integrations`**</mark>.
3. สร้าง API token ใหม่

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

นี่คือตัวอย่างคำขอ 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>Basic Mode</em>).</td></tr><tr><td>/errors/tokens/required</td><td>ไม่มี API token</td></tr><tr><td>/errors/tokens/invalid</td><td>API token ไม่ถูกต้อง (เช่น API token หมดอายุแล้ว)</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" %}
เพื่อดูว่าจำเป็นต้องใช้การแบ่งหน้าหรือไม่ ให้ตรวจสอบว่ามีพารามิเตอร์ที่เกี่ยวข้องกับการแบ่งหน้าอยู่ใน body ของคำขอของ 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 และคำขอฟีเจอร์ใหม่ๆ