Xác thực

Tất cả request Public API đều cần Bearer token. Thông tin xác thực kênh và mã kho được quản lý trong developer portal — đừng bao giờ nhúng chúng vào client app của bạn.

API keys {#api-keys}

Tạo key trong Developer Portal → API Keys sau khi app của bạn được duyệt.

Mục	Mô tả
Format	`Authorization: Bearer hio_live_…` (production) hoặc test key do portal cấp
Scope	Một key cho mỗi app. Quota và quyền truy cập kênh đi theo subscription plan của app.
Rotation	Thu hồi key bị lộ ngay lập tức; tạo key thay thế trước khi thu hồi trong production.
Storage	Chỉ lưu phía server. Không để lộ key trong mobile app, browser JS hoặc repo công khai.

Request ví dụ

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }'

Ủy quyền kênh (điều kiện bắt buộc) {#channel-authorization}

Chỉ API key là chưa đủ. Mỗi app phải hoàn tất ủy quyền kênh trước khi gọi API sản phẩm hoặc đơn hàng cho marketplace đó.

Chế độ	Bạn cấu hình gì	Gateway sử dụng gì
Self fulfillment	OAuth theo từng kênh hoặc token JSON trong portal	Token lưu theo app + kênh
Kho HIOBuy	Một mã developer kho	Mã + token được quản lý phía server; mua hộ/fulfillment chuyển tiếp đến HIOBuy

Xem Portal authorization. Nếu một kênh chưa được ủy quyền, cuộc gọi trả về 401 CHANNEL_NOT_AUTHORIZED (Errors).

Những gì bạn không bao giờ gửi {#what-not-to-send}

Access token hoặc refresh token của Taobao / 1688 / Weidian
Mã developer kho (Gateway tự gắn mã này cho fulfillment routes)
Portal session JWT trong các cuộc gọi Public API

Truy vết request {#tracing}

Mỗi response bao gồm:

Header x-request-id — đối chiếu với request_id trong JSON body
Header quota tùy chọn trên các route tính phí — xem Rate limits

Hãy cung cấp x-request-id khi liên hệ hỗ trợ HIOBuy.

Lỗi xác thực thường gặp {#auth-errors}

HTTP	Code	Ý nghĩa
401	`INVALID_API_KEY`	Bearer token bị thiếu, đã thu hồi hoặc sai định dạng
401	`CHANNEL_NOT_AUTHORIZED`	App chưa ủy quyền kênh được yêu cầu trong portal
403	`INSUFFICIENT_SCOPE`	Key hoặc app thiếu quyền cho thao tác
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	Gọi Fulfillment API khi app đang ở chế độ self-fulfillment