API (lama)

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

---

Referensi API

Untuk dokumentasi endpoint yang lebih detail, silakan kunjungi: https://rest.boxhero.io/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.

Melakukan 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 memberlakukan batas laju berikut:

• 5 kueri per detik untuk setiap endpoint.

Setelah Anda terkena batas laju, Anda akan melihat pesan kesalahan dengan berikut:

• X-Ratelimit-Limit - Maksimum kueri per menit

• X-Ratelimit-Remaining - Sisa kueri

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

---

Respons

Sukses

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

Kesalahan

Kode status dalam rentang 400 atau 500 menandakan 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 Kesalahan:

{
  "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 kesalahan.

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

• title : Menjelaskan isi kesalahan dalam bentuk yang mudah dibaca manusia.

• correlation_id : Mengarah ke ID permintaan yang terkait dengan kesalahan.

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

Jenis Kesalahan Umum

Jenis	Deskripsi
/errors/not-found	Sumber daya yang diminta tidak ditemukan (misalnya, item dengan ID tertentu tidak ada).
/errors/invalid-request	Parameter dalam permintaan tidak valid.
/errors/invalid-team-mode	Kueri yang diminta tidak dapat diproses dalam mode tim saat ini (misalnya, menggunakan API pencarian location 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 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 मौजूद dalam body permintaan endpoint pada dokumentasi API.

Parameter Paginasi

• has_more : Sebuah nilai boolean yang menunjukkan apakah ada data lain di luar halaman saat ini.

• cursor : Menyediakan nilai cursor untuk mengambil halaman berikutnya.

Mengambil Halaman Berikutnya

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

• Jika true, kirim permintaan lain dengan menyertakan cursor={received cursor value} dalam 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 fungsi API tambahan, silakan hubungi tim dukungan kami. Kami menyambut masukan Anda untuk peningkatan API dan permintaan fitur baru.

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