Cấu hình cửa hàng
Lưu cấu hình
Thêm mới hoặc cập nhật nhiều dòng cấu hình của cửa hàng trong một request
Endpoint
POST /v1/settings
Yêu cầu quyền company.setting (Cài đặt công ty). Mỗi item được xác định bằng cặp group + key: nếu cửa hàng đã có dòng này thì cập nhật, chưa có thì tạo mới. Cấu hình luôn ghi vào công ty đang đăng nhập.
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
items | array | Có | Danh sách cấu hình cần lưu (không được rỗng) |
items[].group | string | Có | Nhóm cấu hình, chỉ gồm a-z, 0-9, _ |
items[].key | string | Có | Tên key, chỉ gồm a-z, 0-9, _ |
items[].value | string | Có (*) | Giá trị cấu hình. Với key chỉ ghi (smtp_password, customer_sso_remote_api_token), gửi *** để giữ nguyên giá trị đang lưu |
items[].value_extra | string | Có (*) | Giá trị mở rộng (nội dung dài) |
(*) Mỗi item phải có ít nhất một trong hai trường value hoặc value_extra.
Các key cấu hình theo công ty (email/SMTP, theme, SSO, URL ứng dụng) được kiểm định dạng theo Danh sách key cấu hình. Giá trị rỗng luôn hợp lệ (= dùng mặc định hệ thống). Giá trị không đổi so với giá trị đang lưu thì không bị kiểm lại.
{
"items": [
{ "group": "email", "key": "email_custom_enable", "value": "1" },
{ "group": "email", "key": "smtp_server", "value": "smtp.shopabc.vn" },
{ "group": "email", "key": "smtp_port", "value": "587" },
{ "group": "email", "key": "smtp_password", "value": "***" },
{ "group": "website", "key": "website_theme", "value": "default" }
]
}Response Schema
HTTP 200 - JSON Object
| Trường | Kiểu | Mô tả |
|---|---|---|
total | int | Số dòng đã lưu |
currentpage | int | Luôn là 1 |
limit | int | Số item đã gửi |
items | array | Mảng Setting Object vừa lưu (giá trị bí mật đã được che) |
Error Codes
HTTP 403
| Mã lỗi | Mô tả |
|---|---|
error_role_not_available | Người dùng không có quyền company.setting. Response có thêm detail.role |
HTTP 422 - Lỗi dữ liệu đầu vào
Trả về {"error": [...]} gồm các mã lỗi:
| Mã lỗi | Mô tả |
|---|---|
error_request_body_property_items_required | Thiếu items hoặc items rỗng |
error_item_properties_invalid | Item thiếu group, key hoặc thiếu cả value và value_extra |
error_item_group_string_contains_invalid_character_or_empty | group rỗng hoặc có ký tự ngoài a-z, 0-9, _ |
error_item_key_string_contains_invalid_character_or_empty | key rỗng hoặc có ký tự ngoài a-z, 0-9, _ |
error_<key>_invalid | Giá trị của key cấu hình không hợp lệ, ví dụ error_smtp_port_invalid, error_email_from_email_invalid, error_smtp_ssl_invalid, error_website_theme_invalid, error_customer_sso_auth_mode_invalid, error_admin_app_url_invalid |
error_smtp_server_not_allowed | (Hubport SaaS) Máy chủ SMTP không phải máy chủ công khai |
error_smtp_port_not_allowed | (Hubport SaaS) Cổng SMTP không thuộc 25, 465, 587, 2525 |
error_customer_sso_remote_api_auth_url_not_allowed | (Hubport SaaS) URL API xác thực không phải https hoặc trỏ tới địa chỉ nội bộ |
error_customer_sso_remote_api_register_url_not_allowed | Tương tự, cho URL đăng ký |
error_customer_sso_remote_api_change_password_url_not_allowed | Tương tự, cho URL đổi mật khẩu |
error_tax_invoice_api_endpoint_not_allowed | (Hubport SaaS) tax_invoice_api_endpoint (URL nhà cung cấp hoá đơn điện tử) không phải https hoặc trỏ tới địa chỉ nội bộ |
error_website_domain_invalid | website_domain không phải tên miền hợp lệ |
error_website_domain_taken | Tên miền đã được cửa hàng khác sử dụng |
error_update_setting(<group> - <key>) | Lỗi khi cập nhật dòng cấu hình |
error_add_setting(<group> - <key>) | Lỗi khi tạo dòng cấu hình |
error_company_id_required | ID công ty không được để trống |
error_company_id_notfound | ID công ty không tìm thấy |
error_user1_id_required | ID người tạo không được để trống |
error_user_id_notfound | ID người tạo không tìm thấy |
Workflow & Logic
- Kiểm quyền
company.setting. - Chuẩn hoá giá trị các key cấu hình theo công ty (bỏ khoảng trắng, chuẩn hoá cờ/method...). Key chỉ ghi gửi
***được thay bằng giá trị đang lưu. - Kiểm định dạng từng item. Trên Hubport SaaS, nếu request có thay đổi
smtp_serverhoặcsmtp_port, hệ thống kiểm cặp máy chủ + cổng (giá trị còn thiếu lấy từ cấu hình đang lưu). - Lưu từng item (cập nhật nếu đã có, tạo mới nếu chưa có).
- Làm mới cache cấu hình và cache storefront của cửa hàng; một số dịch vụ (gửi email, SSO) có thể mất tối đa khoảng 1 phút để nhận cấu hình mới.
Ví dụ
curl -X POST "https://api.hubport.vn/v1/settings" \
-H "Authorization: <JWT>" \
-H "Content-Type: application/json" \
-d '{"items":[{"group":"website","key":"website_theme","value":"hpthree"}]}'