API

API BoxHero memungkinkan pengembang mengintegrasikan kemampuan manajemen inventaris kami dengan aplikasi eksternal untuk pengambilan dan interaksi data yang efisien.

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

---

Referensi API

Untuk dokumentasi endpoint yang lebih detail, silakan kunjungi: https://rest.boxhero-app.com/docs/api

---

Endpoint

Semua permintaan API harus diarahkan ke URL dasar berikut: https://rest.boxhero-app.com

Autentikasi

Semua permintaan API harus menyertakan sebuah Authorization header dengan Bearer token:

Authorization: Bearer {API_TOKEN}

Untuk mendapatkan token API:

1. Masuk ke akun BoxHero Anda di Desktop (Web).

2. Buka ke Pengaturan > Integrasi.

3. Hasilkan token API baru.

Mengirim Permintaan

Berikut contoh permintaan API untuk mengambil 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'

Batas Laju

Untuk memastikan stabilitas sistem, kami menerapkan batas laju berikut:

• 5 kueri per detik untuk setiap endpoint.

Setelah Anda mencapai batas laju, Anda akan melihat pesan error dengan hal berikut:

• X-Ratelimit-Limit - Maksimum kueri per menit

• X-Ratelimit-Remaining - Kueri yang tersisa

• X-Ratelimit-Reset - Waktu (dalam detik) yang tersisa hingga penghitungan kueri direset

---

Respons

Berhasil

Respons dengan kode status HTTP dalam rentang 200 menunjukkan pemrosesan API berhasil.

Error

Kode status dalam rentang 400 atau 500 menunjukkan kegagalan permintaan API:

• Rentang 400: kesalahan sisi klien dari informasi yang diberikan bersama permintaan (misalnya, parameter wajib yang hilang).

• Rentang 500: kesalahan sisi server.

Contoh Respons Error:

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

• id : ID unik untuk mengidentifikasi error.

• type : Kode dalam bentuk URL yang mengidentifikasi jenis error.

• title : Berikan isi error dalam bentuk yang mudah dibaca manusia.

• correlation_id : Menunjuk ke ID permintaan yang terkait dengan error.

• lainnya : Bidang tambahan dapat disertakan untuk memberikan informasi tambahan, seperti "given" dalam contoh.

Jenis Error Umum

Tipe	Deskripsi
/errors/not-found	Sumber daya yang diminta tidak ditemukan (misalnya, item dengan ID tertentu tidak ada).
/errors/invalid-request	Parameter tidak valid dalam permintaan.
/errors/invalid-team-mode	Kueri yang diminta tidak dapat diproses dalam mode tim saat ini (misalnya, menggunakan lokasi lookup API di Mode Dasar).
/errors/tokens/required	Token API hilang.
/errors/tokens/invalid	Token API tidak valid (misalnya, token API telah kedaluwarsa).
/errors/too-many-requests	Melebihi batas laju.
/errors/unhandled	Kesalahan sisi server yang belum terselesaikan.
/errors/core/usage-limit-exceeded	Batas penggunaan telah tercapai. Diperlukan peningkatan paket.

Paginasi

Untuk endpoint yang mengembalikan dataset besar (misalnya, daftar item, daftar transaksi), API tampilan daftar membatasi jumlah item yang dikembalikan dalam satu permintaan melalui paginasi. Kami menggunakan paginasi berbasis cursor:

Untuk menentukan apakah paginasi diperlukan, periksa apakah parameter terkait paginasi hadir di body permintaan endpoint dalam dokumentasi API.

Parameter Paginasi

• has_more : Nilai boolean yang menunjukkan apakah masih ada data setelah halaman saat ini.

• cursor : Menyediakan nilai cursor untuk mengambil halaman berikutnya.

Mengambil Halaman Berikutnya

• Periksa apakah has_more adalah true. Itu berarti ada halaman lain yang tersedia.

• Jika true, kirim permintaan lain dengan menyertakan cursor={nilai cursor yang diterima} di parameter. Ini akan mengembalikan data berikutnya.

• Ulangi hingga has_more adalah false untuk mengambil daftar lengkap.

---

Dukungan dan Masukan

Jika Anda mengalami masalah atau membutuhkan fungsionalitas API tambahan, silakan hubungi tim dukungan. Kami menyambut masukan Anda untuk peningkatan API dan permintaan fitur baru.