API
API của BoxHero cho phép các nhà phát triển tích hợp các khả năng quản lý tồn kho của chúng tôi với các ứng dụng bên ngoài để truy xuất và tương tác dữ liệu hiệu quả.
Tham khảo API
Để xem tài liệu chi tiết về các endpoint, vui lòng truy cập: https://rest.boxhero-app.com/docs/api
Endpoint
Tất cả các yêu cầu API nên được gửi đến URL gốc sau: https://rest.boxhero-app.com
Xác thực
Tất cả các yêu cầu API phải bao gồm một Authorization tiêu đề với một Bearer token:
Để lấy một API token:
Đăng nhập vào tài khoản BoxHero của bạn trên Desktop (Web).
Điều hướng đến
Cài đặt>Tích hợp.Tạo một API token mới.
Thực hiện yêu cầu
Đây là một yêu cầu API mẫu để truy xuất sản phẩm.
Giới hạn tốc độ
Để đảm bảo tính ổn định của hệ thống, chúng tôi áp dụng các giới hạn tốc độ sau:
5 truy vấn mỗi giây cho mỗi endpoint.
Khi bạn bị giới hạn tốc độ, bạn sẽ thấy một thông báo lỗi với nội dung sau:
X-Ratelimit-Limit- Số truy vấn tối đa mỗi phútX-Ratelimit-Remaining- Số truy vấn còn lạiX-Ratelimit-Reset- Thời gian (tính bằng giây) còn lại cho đến khi số lượng truy vấn được đặt lại
Phản hồi
Thành công
Các phản hồi có mã trạng thái HTTP trong khoảng 200 cho biết API đã xử lý thành công.
Lỗi
Các mã trạng thái trong khoảng 400 hoặc 500 cho biết yêu cầu API đã thất bại:
Khoảng 400: Lỗi phía client do thông tin được cung cấp cùng yêu cầu (ví dụ: thiếu tham số bắt buộc).
Khoảng 500: Lỗi phía máy chủ.
Ví dụ phản hồi lỗi:
id : Một ID duy nhất để xác định lỗi.
type : Một mã ở dạng URL dùng để xác định loại lỗi.
title : Cung cấp nội dung của lỗi dưới dạng dễ hiểu cho con người.
correlation_id : Trỏ đến ID của yêu cầu liên quan đến lỗi.
khác : Có thể bao gồm các trường bổ sung để cung cấp thêm thông tin, chẳng hạn như "given" trong ví dụ.
Các loại lỗi phổ biến
/errors/not-found
Tài nguyên được yêu cầu không được tìm thấy (ví dụ: mục có ID cụ thể không tồn tại).
/errors/invalid-request
Tham số không hợp lệ trong yêu cầu.
/errors/invalid-team-mode
Yêu cầu truy vấn không thể được xử lý trong chế độ nhóm hiện tại (ví dụ: sử dụng địa điểm API tra cứu trong Chế độ Cơ bản).
/errors/tokens/required
Thiếu API token.
/errors/tokens/invalid
API token không hợp lệ (ví dụ: API token đã hết hạn).
/errors/too-many-requests
Đã vượt quá giới hạn tốc độ.
/errors/unhandled
Lỗi phía máy chủ chưa được xử lý.
/errors/core/usage-limit-exceeded
Đã đạt đến giới hạn sử dụng. Cần nâng cấp gói.
Phân trang
Đối với các endpoint trả về tập dữ liệu lớn (ví dụ: danh sách mặt hàng, danh sách giao dịch), API dạng danh sách giới hạn số lượng mục trả về trong một yêu cầu duy nhất thông qua phân trang. Chúng tôi sử dụng phân trang dựa trên cursor:
Để xác định xem có cần phân trang hay không, hãy kiểm tra xem các tham số liên quan đến phân trang có xuất hiện trong phần thân yêu cầu của endpoint trong tài liệu API hay không.
Các tham số phân trang
has_more: Một giá trị boolean cho biết có còn dữ liệu nào khác ngoài trang hiện tại hay không.cursor: Cung cấp giá trị cursor để truy xuất trang tiếp theo.
Truy xuất trang tiếp theo
Kiểm tra xem
has_morecóđúng. Điều đó có nghĩa là còn một trang khác khả dụng.Nếu
đúng, hãy gửi một yêu cầu khác bao gồmcursor={giá trị cursor đã nhận}trong các tham số. Điều này sẽ trả về dữ liệu tiếp theo.Lặp lại cho đến khi
has_morecósaiđể truy xuất danh sách đầy đủ.
Hỗ trợ và phản hồi
Nếu bạn gặp sự cố hoặc cần thêm chức năng API, vui lòng liên hệ với đội ngũ hỗ trợ. Chúng tôi hoan nghênh phản hồi của bạn để cải thiện API và các yêu cầu tính năng mới.
Last updated