API

API ของ BoxHero ช่วยให้นักพัฒนาสามารถผสานความสามารถด้านการจัดการสินค้าคงคลังของเรากับแอปพลิเคชันภายนอก เพื่อการดึงข้อมูลและการโต้ตอบที่มีประสิทธิภาพ

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

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

สำหรับเอกสารรายละเอียดของแต่ละ endpoint โปรดไปที่: https://rest.boxhero-app.com/docs/api

---

Endpoint

คำขอ API ทั้งหมดควรถูกส่งไปยัง Base URL ต่อไปนี้: https://rest.boxhero-app.com

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

คำขอ API ทั้งหมดต้องมี Authorization header พร้อมด้วย Bearer token:

Authorization: Bearer {API_TOKEN}

หากต้องการรับ API token:

1. เข้าสู่ระบบบัญชี BoxHero ของคุณบน Desktop (Web)

2. ไปที่ การตั้งค่า > การเชื่อมต่อ.

3. สร้าง API token ใหม่

การส่งคำขอ

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

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: ข้อผิดพลาดฝั่งเซิร์ฟเวอร์

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

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

• id : รหัสเฉพาะเพื่อระบุข้อผิดพลาด

• type : รหัสในรูปแบบ URL ที่ระบุประเภทของข้อผิดพลาด

• title : แสดงเนื้อหาของข้อผิดพลาดในรูปแบบที่มนุษย์อ่านเข้าใจได้

• correlation_id : ชี้ไปยังรหัสของคำขอที่เกี่ยวข้องกับข้อผิดพลาด

• อื่น ๆ : อาจมีฟิลด์เพิ่มเติมเพื่อให้ข้อมูลเพิ่มเติม เช่น "given" ในตัวอย่าง

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

ประเภท	คำอธิบาย
/errors/not-found	ไม่พบทรัพยากรที่ร้องขอ (เช่น ไม่มีรายการที่มี ID เฉพาะดังกล่าว)
/errors/invalid-request	พารามิเตอร์ในคำขอไม่ถูกต้อง
/errors/invalid-team-mode	ไม่สามารถประมวลผลคำขอที่ร้องขอได้ในโหมดทีมปัจจุบัน (เช่น การใช้ สถานที่ lookup API ใน Basic Mode).
/errors/tokens/required	ขาด API token
/errors/tokens/invalid	API token ไม่ถูกต้อง (เช่น API token หมดอายุแล้ว)
/errors/too-many-requests	เกินขีดจำกัดอัตรา
/errors/unhandled	ข้อผิดพลาดฝั่งเซิร์ฟเวอร์ที่ยังไม่ได้รับการแก้ไข
/errors/core/usage-limit-exceeded	ถึงขีดจำกัดการใช้งานแล้ว ต้องอัปเกรดแผน

การแบ่งหน้า

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

หากต้องการทราบว่าจำเป็นต้องใช้การแบ่งหน้าหรือไม่ ให้ตรวจสอบว่ามีพารามิเตอร์ที่เกี่ยวข้องกับการแบ่งหน้าอยู่ใน request body ของ endpoint ในเอกสาร API หรือไม่

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

• has_more : ค่าบูลีนที่ระบุว่ายังมีข้อมูลเพิ่มเติมนอกเหนือจากหน้าปัจจุบันหรือไม่

• cursor : ให้ค่าคอร์เซอร์สำหรับดึงหน้าถัดไป

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

• ตรวจสอบว่า has_more เป็น trueหรือไม่ ซึ่งหมายความว่ายังมีหน้าอื่นให้ใช้งาน

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

• ทำซ้ำจนกว่า has_more เป็น false เพื่อดึงรายการทั้งหมด

---

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

หากคุณพบปัญหาหรือต้องการฟังก์ชัน API เพิ่มเติม โปรดติดต่อ ทีมสนับสนุนของเรา เรายินดีรับฟังข้อเสนอแนะของคุณเพื่อปรับปรุง API และคำขอฟีเจอร์ใหม่ๆ