Giới thiệu Store-front API

Các public API để xây dựng Website Ecommerce hoặc Mobile App.

Đường dẫn APICopy Anchor Link

Các API đều kết nối tới 1 url gọi là BASE_URL:

• Shop dùng Hubport SaaS: BASE_URL là https://api.hubport.vn.
• Shop dùng bản cài đặt riêng (dedicated server): BASE_URL là tên miền API riêng của shop (thường có dạng https://ws.mydomain.com). Liên hệ bộ phận hỗ trợ của Hubport để lấy BASE_URL của công ty bạn.

Mọi Store-front API đều có đường dẫn bắt đầu bằng /site/, ví dụ: GET https://api.hubport.vn/site/settings/setting.

Cách xác thực khi kết nốiCopy Anchor Link

Mọi request gửi tới Store-front API đều yêu cầu cung cấp các headers sau:

SiteTenantIdCopy Anchor Link

• Shop (tenant) của request được xác định chỉ qua header SiteTenantId, không dựa vào tên miền gọi API. Mọi dữ liệu trả về (sản phẩm, khách hàng, giỏ hàng, đơn hàng...) đều thuộc shop này.
• Nếu SiteTenantId không hợp lệ, không tồn tại hoặc shop đang bị khóa, API trả HTTP 404 với mã lỗi error_company_not_found_from_site_tenant_id.
• Nếu website của shop đang tạm ngưng (shop không dùng module Cửa hàng online), mọi API trả HTTP 403 với mã lỗi error_module_disabled và detail.module = "storefront". Website nên hiện trang "Website tạm ngưng".
• Nếu shop không dùng một module (ví dụ Khuyến mãi, Tiếp thị liên kết, Website & nội dung), các API của module đó trả HTTP 403 error_module_disabled (detail.module là mã module), riêng các API đọc dùng khi duyệt web và thanh toán trả 200 với danh sách rỗng và field module_disabled: danh sách khuyến mãi và flash sale, ghi nhận click cộng tác viên, menu, banner, khối trang. Bộ tính khuyến mãi (/site/promotionengines/*) trả "không có khuyến mãi" như bình thường, giỏ hàng và thanh toán vẫn chạy với giá gốc.
• Storefront chạy trên tên miền riêng của shop có thể tra SiteTenantId theo tên miền đã cấu hình trong cài đặt website (website_domain):

curl "https://api.hubport.vn/v1/settings/findtenantidfromwebsitedomain?website_domain=shop.mydomain.com"

{
  "tenant_id": 123,
  "website_domain": "shop.mydomain.com",
  "ts": 1740300000
}

tenant_id = 0 nghĩa là không tìm thấy shop nào ứng với tên miền.

Giá trị website_domain là cấu hình của shop, không được xác minh quyền sở hữu tên miền. Website bán hàng do Hubport SaaS chạy nhận shop theo tên miền con hoặc tên miền riêng đã xác minh ở Tên miền website, không theo website_domain.

SiteAuthorizationCopy Anchor Link

• Token khách hàng lấy từ trường jwt trong response của API Đăng nhập. Gửi nguyên giá trị này (không thêm tiền tố Bearer) trong header SiteAuthorization.
• Token có hiệu lực 7 ngày kể từ khi đăng nhập, và mất hiệu lực ngay khi gọi API Đăng xuất.
• Token gắn với đúng shop đã đăng nhập. Gửi token của khách hàng shop A khi gọi API với SiteTenantId của shop B:
  • API yêu cầu đăng nhập trả HTTP 401 với mã lỗi error_customer_company_mismatch.
  • API công khai (không yêu cầu đăng nhập) vẫn trả dữ liệu nhưng coi như khách chưa đăng nhập.

Gọi từ trình duyệt (CORS)Copy Anchor Link

Store-front API cho phép gọi trực tiếp từ trình duyệt trên tên miền bất kỳ (response có Access-Control-Allow-Origin: *). Xác thực chỉ qua header SiteTenantId / SiteAuthorization, API không dùng cookie: không đặt credentials: "include" (hoặc withCredentials: true) cho request, nếu không trình duyệt sẽ chặn response.

Định dạng responseCopy Anchor Link

• Response thành công trả trực tiếp đối tượng JSON (không bọc thêm), HTTP status 200 (hoặc 201 khi tạo mới, 204 khi xóa).
• Response lỗi có dạng sau, kèm HTTP status tương ứng (401, 404, 422, 500...):

{
  "error": ["error_not_found"]
}

• Lỗi phía máy chủ khi truy vấn dữ liệu trả HTTP 500 với {"error": ["error_database"]}; nên thử lại sau.

Ví dụCopy Anchor Link

curl -X GET "https://api.hubport.vn/site/customers/getdetail" \
  -H "SiteTenantId: <SITE_TENANT_ID>" \
  -H "SiteAuthorization: <CUSTOMER_TOKEN>"