API

API BoxHero membolehkan pembangun menyepadukan keupayaan pengurusan inventori kami dengan aplikasi luaran untuk mendapatkan semula dan berinteraksi dengan data secara cekap.

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

---

Rujukan API

Untuk dokumentasi titik akhir yang terperinci, sila lawati: https://rest.boxhero-app.com/docs/api

---

Titik Akhir

Semua permintaan API hendaklah dihantar ke URL asas berikut: https://rest.boxhero-app.com

Pengesahan

Semua permintaan API mesti menyertakan Authorization header dengan token Bearer:

Authorization: Bearer {API_TOKEN}

Untuk mendapatkan token API:

1. Log masuk ke akaun BoxHero anda pada Desktop (Web).

2. Navigasi ke Tetapan > Integrasi.

3. Hasilkan token API baharu.

Menghantar Permintaan

Berikut ialah contoh permintaan API untuk mendapatkan produk.

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'

Had Kadar

Untuk memastikan kestabilan sistem, kami mengenakan had kadar berikut:

• 5 pertanyaan sesaat untuk setiap titik akhir.

Apabila anda mencapai had kadar, anda akan melihat mesej ralat dengan yang berikut:

• X-Ratelimit-Limit - Pertanyaan maksimum seminit

• X-Ratelimit-Remaining - Pertanyaan yang masih tinggal

• X-Ratelimit-Reset - Masa (dalam saat) yang tinggal sehingga kiraan pertanyaan diset semula

---

Respons

Berjaya

Respons dengan kod status HTTP dalam julat 200 menunjukkan pemprosesan API berjaya.

Ralat

Kod status dalam julat 400 atau 500 menunjukkan kegagalan permintaan API:

• Julat 400: Ralat pihak klien akibat maklumat yang diberikan bersama permintaan (cth., parameter wajib tiada).

• Julat 500: Ralat pihak pelayan.

Contoh Respons Ralat:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Token pengesahan tidak sah. Sila berikan token yang sah.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id : ID unik untuk mengenal pasti ralat.

• type : Kod dalam bentuk URL yang mengenal pasti jenis ralat.

• title : Berikan kandungan ralat dalam bentuk yang boleh dibaca oleh manusia.

• correlation_id : Merujuk kepada ID permintaan yang dikaitkan dengan ralat.

• lain-lain : Medan tambahan mungkin disertakan untuk memberikan maklumat tambahan, seperti "given" dalam contoh.

Jenis Ralat Lazim

Jenis	Perihalan
/errors/not-found	Sumber yang diminta tidak ditemui (cth., item dengan ID tertentu tidak wujud).
/errors/invalid-request	Parameter tidak sah dalam permintaan.
/errors/invalid-team-mode	Pertanyaan yang diminta tidak dapat diproses dalam mod pasukan semasa (cth., menggunakan lokasi lookup API dalam Mod Asas).
/errors/tokens/required	Token API tiada.
/errors/tokens/invalid	Token API tidak sah (cth., token API telah tamat tempoh).
/errors/too-many-requests	Melebihi had kadar.
/errors/unhandled	Ralat pihak pelayan yang belum diselesaikan.
/errors/core/usage-limit-exceeded	Had penggunaan telah dicapai. Peningkatan pelan diperlukan.

Penomboran

Untuk titik akhir yang mengembalikan set data besar (cth., senarai item, senarai transaksi), API paparan senarai mengehadkan bilangan item yang dikembalikan dalam satu permintaan melalui penomboran. Kami menggunakan penomboran berasaskan cursor:

Untuk menentukan sama ada penomboran diperlukan, semak sama ada parameter berkaitan penomboran hadir dalam badan permintaan titik akhir dalam dokumentasi API.

Parameter Penomboran

• has_more : Nilai boolean yang menunjukkan sama ada terdapat data tambahan melepasi halaman semasa.

• cursor : Menyediakan nilai cursor untuk mendapatkan halaman seterusnya.

Mendapatkan Halaman Seterusnya

• Semak sama ada has_more ialah benar. Ini bermakna terdapat satu lagi halaman tersedia.

• Jika benar, hantar satu lagi permintaan termasuk cursor={nilai cursor yang diterima} dalam parameter. Ini akan mengembalikan data seterusnya.

• Ulang sehingga has_more ialah palsu untuk mendapatkan senarai penuh.

---

Sokongan dan Maklum Balas

Jika anda menghadapi masalah atau memerlukan fungsi API tambahan, sila hubungi pasukan sokongan. Kami mengalu-alukan maklum balas anda untuk penambahbaikan API dan permintaan ciri baharu.