Hubport LogoHubport APIAPI v1
Thông tin chungXác thực kết nối

API Key

Sử dụng API Key để xác thực khi kết nối với API. API Key không hết hạn (cho đến khi bạn khoá hoặc đổi API Secret).

Yêu cầu gói dịch vụ

Mọi cửa hàng trên Hubport SaaS (kể cả đang dùng thử) đều dùng được API Key. Với bản cài đặt riêng, API Key chỉ dùng được khi công ty đang ở gói có hỗ trợ kết nối API. Nếu gói hiện tại không hỗ trợ, request dùng API Key sẽ bị từ chối với lỗi error_company_plan_not_allow_companyapp, và thao tác tạo / sửa API Key trên trang quản trị trả lỗi error_company_plan_not_allow.

Cách lấy API Key

Để sử dụng các API, bạn cần lấy API Key từ Hubport. Bạn có thể tạo nhiều API Key cho các kết nối khác nhau (số lượng tối đa tuỳ theo gói dịch vụ). Theo hướng dẫn sau:

  1. Vào trang quản trị
  2. Chọn "Cửa hàng" -> "Cài đặt khác" -> Chọn tab "API" và click vào "Tới trang cài đặt API"
  3. Khi đang ở trang danh sách API Key, click vào "Thêm"
  4. Nhập Tên, Mô tả và chọn loại là "Private API"
  5. Click vào "Lưu thông tin" sẽ tạo thành công và trở về danh sách API Key
  6. Ở danh sách API Key, tìm API Key mới vừa tạo và nhấn nút "Sửa" để lấy API Key và API Secret.

Cách kết nối dùng API Key

  • Web Service của Hubport sử dụng cơ chế xác thực thông qua header dựa trên API Key và API Secret.
  • Tất cả các request lên server cần cung cấp thêm Header có tên là "Authorization" và có giá trị theo định dạng "apikey:apisecret". Ví dụ nếu API Key của bạn là "123" và API Secret của bạn là "abc" thì các request của bạn gửi lên server phải có thêm header "Authorization" có giá trị là "123:abc". (Không có Basic hay base64 encode). Không truyền key/secret trên query string: tham số __jwtAuthorization trên URL bị từ chối với lỗi error_jwt_query_not_allowed.
  • Luôn truyền thêm company_id và creator_id trong request param (GET) hoặc body payload (POST, PUT, DELETE) để xác định công ty và người tạo/người thực hiện action.
    • company_id phải đúng là ID của công ty sở hữu API Key. Nếu khác, API sẽ không trả dữ liệu hoặc báo lỗi error_company_id_notfound.
    • creator_id phải là User ID của một nhân viên thuộc công ty đó, nếu không sẽ báo lỗi error_user_id_notfound.
  • Để biết user_id của một nhân viên, vào phần cập nhật thông tin nhân viên, sẽ có thông tin User ID của một nhân viên. User ID sẽ khác với Employee ID.
  • Để biết company_id của một công ty, vào phần thông tin công ty ở menu Profile, sẽ có thông tin Company ID của một công ty.
curl "https://api.hubport.vn/v1/products?company_id=10311&creator_id=1" \
  -H "Authorization: <YOUR_API_KEY>:<YOUR_API_SECRET>"

Một số API gắn với tài khoản người dùng (ví dụ Đổi mật khẩu, Đổi công ty đang làm việc, quản lý phiên đăng nhập) chỉ dùng được với User Login Token, không dùng được với API Key.

Lỗi xác thực API Key

Các lỗi dưới đây trả về HTTP status 400, body dạng {"error": ["..."]}:

CodeMô tả
error_api_invalidGiá trị header không đúng định dạng apikey:apisecret (thiếu key hoặc secret)
error_apikey_invalidKhông tìm thấy cặp API Key / API Secret
error_companyapp_data_invalid_or_not_enableAPI Key không ở trạng thái hoạt động (ví dụ đã bị khoá)
error_company_plan_not_allow_companyappGói dịch vụ của công ty không hỗ trợ kết nối API Key
error_company_not_found_from_companyappKhông tìm thấy công ty sở hữu API Key

User Login Token

Previous Page

Rate Limit

Next Page

On this page

Cách lấy API KeyCách kết nối dùng API KeyLỗi xác thực API Key