Danh sách key cấu hình
Các key cấu hình theo cửa hàng: email/SMTP, theme storefront, đăng nhập khách hàng (SSO), URL ứng dụng
Các key dưới đây được đọc/ghi qua Danh sách cấu hình và Lưu cấu hình với cặp group + key tương ứng. Mọi giá trị đều là chuỗi.
Giá trị rỗng = dùng mặc định hệ thống
Tất cả các key trong trang này đều không bắt buộc. Nếu chưa lưu hoặc để trống (""), cửa hàng dùng mặc định hệ thống của Hubport (hoặc của máy chủ riêng nếu bạn dùng bản cài đặt riêng). Giá trị rỗng luôn hợp lệ khi lưu.
Khi lưu, hệ thống tự chuẩn hoá giá trị: bỏ khoảng trắng hai đầu (trừ secret), giá trị boolean JSON true/false được lưu thành "1"/"0", các key *_method được viết hoa, smtp_ssl được viết thường. Giá trị không đổi so với giá trị đang lưu thì không bị kiểm lại.
Email gửi đi (group email)
| Key | Kiểu | Giá trị hợp lệ | Mô tả |
|---|---|---|---|
email_custom_enable | string (cờ) | 1/0 (cũng nhận true/false, yes/no, on/off) | Bật cấu hình email riêng của cửa hàng. Tắt hoặc để trống = dùng email hệ thống, mọi key bên dưới bị bỏ qua |
email_from_name | string | Tối đa 255 ký tự, không chứa ký tự xuống dòng/ký tự điều khiển | Tên người gửi hiển thị |
email_from_email | string | Email hợp lệ, tối đa 254 ký tự | Địa chỉ người gửi (From). Chỉ được dùng khi gửi qua SMTP riêng của cửa hàng (xem quy tắc bên dưới) |
email_replyto_email | string | Email hợp lệ, tối đa 254 ký tự | Địa chỉ nhận trả lời (Reply-To) |
smtp_server | string | Tên miền hoặc IP, không kèm scheme/cổng/đường dẫn (vd smtp.example.com) | Máy chủ SMTP riêng. Để trống = gửi qua SMTP của hệ thống |
smtp_port | string | Số 1–65535. Trên Hubport SaaS chỉ chấp nhận 25, 465, 587, 2525 | Cổng SMTP. Để trống: 465 nếu smtp_ssl=ssl, ngược lại 587 |
smtp_ssl | string | ssl, tls hoặc rỗng | ssl: kết nối SMTPS. tls: bắt buộc STARTTLS. Rỗng: cổng 465 dùng SMTPS, cổng khác tự dùng STARTTLS nếu máy chủ hỗ trợ |
smtp_username | string | Tối đa 255 ký tự, không chứa ký tự điều khiển | Tài khoản đăng nhập SMTP |
smtp_password | string | Tối đa 4096 ký tự, không chứa ký tự điều khiển | Mật khẩu SMTP. Chỉ ghi: API luôn trả ***; gửi lại *** = giữ nguyên mật khẩu cũ |
Quy tắc chọn máy chủ gửi và địa chỉ người gửi
| Trường hợp | Máy chủ SMTP | From (email) | From (tên) | Reply-To |
|---|---|---|---|---|
email_custom_enable tắt / trống | Hệ thống | Hệ thống | Hệ thống | (không đặt) |
email_custom_enable=1, smtp_server trống | Hệ thống | Luôn là email hệ thống (không cho gửi bằng tên miền khác qua SMTP hệ thống) | email_from_name (nếu có) | email_replyto_email, nếu trống thì email_from_email |
email_custom_enable=1, có smtp_server | SMTP riêng của cửa hàng | email_from_email → smtp_username (nếu là email) → email hệ thống | email_from_name → tên hệ thống | email_replyto_email |
Hubport SaaS
Trên Hubport SaaS, smtp_server phải là máy chủ công khai trên Internet (không chấp nhận địa chỉ IP nội bộ, loopback, link-local...) và cổng phải thuộc 25, 465, 587, 2525. Sau khi lưu, dùng Gửi email thử để kiểm tra cấu hình.
Website / Storefront (group website)
| Key | Kiểu | Giá trị hợp lệ | Mô tả |
|---|---|---|---|
website_theme | string | Một giá trị trong danh sách của Danh sách theme | Theme của storefront. Để trống = dùng theme mặc định (trường default của danh sách theme) |
website_domain | string | Tên miền hợp lệ, tối đa 253 ký tự | Tên miền storefront của cửa hàng. Hệ thống lưu dạng đã chuẩn hoá (chữ thường, bỏ http:///https://, đường dẫn, cổng, dấu chấm cuối; giữ www.). Mỗi tên miền chỉ thuộc về một cửa hàng. Trên Hubport SaaS, website do Hubport chạy không dùng key này: tên miền riêng được thêm và xác minh ở Tên miền website |
Đăng nhập khách hàng storefront - SSO (group customer_sso)
Cho phép storefront xác thực khách hàng bằng hệ thống tài khoản bên ngoài của bạn (chế độ remote_api) thay vì tài khoản khách hàng của Hubport (chế độ internal).
| Key | Kiểu | Giá trị hợp lệ | Mô tả |
|---|---|---|---|
customer_sso_enabled | string (cờ) | 1/0 (cũng nhận true/false, yes/no, on/off) | Bật SSO khách hàng |
customer_sso_auth_mode | string | internal, remote_api | Chế độ xác thực. Chỉ dùng API bên ngoài khi customer_sso_enabled=1 và customer_sso_auth_mode=remote_api |
customer_sso_remote_api_auth_url | string | URL tuyệt đối http/https, tối đa 2000 ký tự, không chứa user:pass@ | API xác thực (đăng nhập) |
customer_sso_remote_api_auth_method | string | GET, POST, PUT | Method gọi API xác thực. Trống = POST |
customer_sso_remote_api_register_url | string | Như trên | API đăng ký / kiểm tra tài khoản tồn tại |
customer_sso_remote_api_register_method | string | GET, POST, PUT | Trống = POST |
customer_sso_remote_api_change_password_url | string | Như trên | API đổi / đặt lại mật khẩu |
customer_sso_remote_api_change_password_method | string | GET, POST, PUT | Trống = POST |
customer_sso_remote_api_header_name | string | ^[A-Za-z0-9-]{1,64}$; không được là header hệ thống (vd Host, Cookie, Content-Type, User-Agent, X-Forwarded-*, Proxy-*...) | Tên header mang token khi Hubport gọi API của bạn |
customer_sso_remote_api_token | string | Tối đa 4096 ký tự, không chứa ký tự điều khiển | Giá trị header xác thực. Chỉ ghi: API luôn trả ***; gửi lại *** = giữ nguyên giá trị cũ |
Lưu ý
Khi cửa hàng đã lưu key customer_sso_enabled (kể cả giá trị 0), toàn bộ cấu hình SSO được lấy từ cấu hình của cửa hàng, không trộn với mặc định hệ thống. Chưa lưu key này thì dùng mặc định hệ thống. Trên Hubport SaaS, các URL phải là https và trỏ tới máy chủ công khai; lưu URL nội bộ trả lỗi error_<key>_not_allowed.
Hợp đồng API bên ngoài (chế độ remote_api)
Hubport gọi URL đã cấu hình với header Content-Type: application/json, Accept: application/json, header xác thực <customer_sso_remote_api_header_name>: <customer_sso_remote_api_token> (nếu có) và body JSON như sau:
| Hành động | URL dùng | Body gửi đi | Phản hồi thành công mong đợi (HTTP 2xx) |
|---|---|---|---|
| Đăng nhập | ..._auth_url | {"phone", "password", "company_id"} | {"success": true, "data": {"id", "full_name", "phone", "email"}} |
| Đăng ký | ..._register_url | {"phone", "password", "company_id", "fullname", "email"} | {"success": true} |
| Kiểm tra tài khoản tồn tại | ..._register_url | {"action": "check", "phone", "company_id"} | {"success": true, "exists": true/false} |
| Đổi mật khẩu | ..._change_password_url | {"company_id", "phone", "email", "customer_id", "customer_code", "old_password", "new_password"} | {"success": true} |
| Đặt lại mật khẩu | ..._change_password_url | {"phone", "company_id", "new_password"} | {"success": true} |
Khi thất bại, API của bạn có thể trả {"success": false, "message": "..."}; nội dung message (tối đa 255 ký tự, đã bỏ HTML) được trả về trong danh sách lỗi (error) của storefront thay cho mã lỗi mặc định.
URL ứng dụng (group system)
| Key | Kiểu | Giá trị hợp lệ | Mô tả |
|---|---|---|---|
admin_app_url | string | URL tuyệt đối http/https, tối đa 2000 ký tự | Địa chỉ trang quản trị của cửa hàng, dùng để tạo liên kết trong email (vd email mời nhân viên), liên kết đơn hàng, phiếu soạn hàng... Để trống = địa chỉ mặc định của hệ thống |
pos_app_url | string | URL tuyệt đối http/https, tối đa 2000 ký tự | Địa chỉ ứng dụng POS của cửa hàng. Để trống = địa chỉ mặc định của hệ thống |
Ví dụ lưu cấu hình SMTP riêng
{
"items": [
{ "group": "email", "key": "email_custom_enable", "value": "1" },
{ "group": "email", "key": "email_from_name", "value": "Shop ABC" },
{ "group": "email", "key": "email_from_email", "value": "[email protected]" },
{ "group": "email", "key": "email_replyto_email", "value": "[email protected]" },
{ "group": "email", "key": "smtp_server", "value": "smtp.shopabc.vn" },
{ "group": "email", "key": "smtp_port", "value": "587" },
{ "group": "email", "key": "smtp_ssl", "value": "tls" },
{ "group": "email", "key": "smtp_username", "value": "[email protected]" },
{ "group": "email", "key": "smtp_password", "value": "mat-khau-smtp" }
]
}