Thêm tên miền riêng
Thêm tên miền riêng cho website cửa hàng, nhận bản ghi DNS cần tạo; giành tên miền đang thuộc cửa hàng khác bằng bản ghi TXT
Chỉ có trên Hubport SaaS
Trên bản cài đặt riêng (máy chủ riêng), endpoint trả HTTP 404 error_saas_mode_inactive.
Endpoint
POST /v1/platformdomains
Yêu cầu quyền company.setting (Cài đặt công ty) và tính năng custom_domain của gói. Tên miền luôn được thêm cho cửa hàng
đang đăng nhập. Sau khi thêm, hệ thống kiểm tra DNS ngay một lần và trả kết quả.
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
domain | string | Có | Tên miền đã mua, vd shopcuatoi.vn hoặc www.shopcuatoi.vn (tối đa 300 ký tự; dán cả URL cũng được). Xem quy tắc |
claim | bool | Không | true để giành tên miền đang thuộc cửa hàng khác sau khi đã tạo bản ghi TXT của bạn (mục dưới). Mặc định false |
{
"domain": "shopcuatoi.vn"
}Response Schema
HTTP 201 - Created
| Trường | Kiểu | Mô tả |
|---|---|---|
item | object | Domain Object vừa thêm (thường ở pending, dns.records là các bản ghi cần tạo) |
overview | object | Dữ liệu như Website của cửa hàng sau khi thêm |
Workflow & Logic
- Kiểm quyền, tính năng
custom_domain. - Chuẩn hoá và tách tên miền: nhập tên miền gốc hoặc
wwwthì website chạy ởwww, tên miền gốc chuyển sangwww. - Tên miền (hoặc tên miền gốc của nó) đã thuộc cửa hàng khác: trả 409
error_domain_takenkèm bản ghi TXT của bạn. - Kiểm giới hạn số tên miền mỗi cửa hàng.
- Tạo tên miền ở trạng thái
pending, kiểm DNS ngay. - Tạo các bản ghi trong
item.dns.records, sau đó gọi Kiểm tra tên miền hoặc chờ hệ thống tự kiểm.
Giành tên miền đang thuộc cửa hàng khác
Khi nhận error_domain_taken, detail có:
| Trường | Mô tả |
|---|---|
detail.txt_name | Tên bản ghi TXT, vd _hubport.shopcuatoi.vn |
detail.txt_value | Mã TXT của cửa hàng bạn cho tên miền này |
Nếu bạn là chủ tên miền: đặt bản ghi TXT detail.txt_name = detail.txt_value và xoá mã TXT cũ (của cửa hàng kia), chờ
DNS cập nhật rồi gửi lại cùng domain với "claim": true. Hệ thống chỉ chuyển tên miền khi TXT có mã của bạn và không còn mã
của cửa hàng đang giữ; cửa hàng kia nhận email thông báo đã mất tên miền.
Error Codes
| HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 402 | error_feature_requires_plan | Gói không có tính năng tên miền riêng. detail.feature = "custom_domain" |
| 403 | error_role_not_available | Người dùng không có quyền company.setting |
| 403 | error_impersonation_readonly | Phiên hỗ trợ của Hubport chỉ được xem |
| 404 | error_saas_mode_inactive | Không phải Hubport SaaS |
| 409 | error_domain_taken | Tên miền thuộc cửa hàng khác. detail.txt_name, detail.txt_value |
| 409 | error_domain_already_added | Cửa hàng đã thêm tên miền này. detail.domain_id là ID tên miền đó |
| 409 | error_domain_claim_failed | Gửi claim=true nhưng bản ghi TXT chưa có mã của bạn hoặc vẫn còn mã của cửa hàng kia |
| 422 | error_domain_invalid | Tên miền không hợp lệ (thiếu, sai định dạng, IP, tên miền nội bộ) |
| 422 | error_domain_platform_blocked | Tên miền của Hubport, không dùng được |
| 422 | error_domain_limit_reached | Đã đủ số tên miền tối đa. detail.max là giới hạn |
Lỗi trả dạng {"error": ["<mã lỗi>"], "detail": {...}}.
Ví dụ
curl -X POST "https://api.hubport.vn/v1/platformdomains" \
-H "Authorization: <JWT>" \
-H "Content-Type: application/json" \
-d '{"domain":"shopcuatoi.vn"}'{
"item": {
"id": 1003,
"domain": "www.shopcuatoi.vn",
"apex": "shopcuatoi.vn",
"url": "https://www.shopcuatoi.vn",
"status": "pending",
"source": "shop",
"verified": false,
"redirect_subdomain": true,
"txt_ok": false,
"routing_ok": false,
"apex_ok": false,
"tls_ok": false,
"warnings": [],
"last_error": "txt_not_found",
"verified_at": 0,
"active_at": 0,
"last_check_at": 1760317200,
"next_check_at": 1760317320,
"cert_not_after": 0,
"dns": {
"records": [
{"purpose": "verify", "type": "TXT", "name": "_hubport.shopcuatoi.vn", "host": "_hubport", "value": "hubport-verify=3f9c0a1b2c3d4e5f60718293a4b5c6d7", "ok": false},
{"purpose": "route", "type": "CNAME", "name": "www.shopcuatoi.vn", "host": "www", "value": "shops.hubport.com.vn", "ok": false},
{"purpose": "apex", "type": "A", "name": "shopcuatoi.vn", "host": "@", "value": "203.0.113.10", "ok": false}
],
"cname_target": "shops.hubport.com.vn",
"apex_ips": ["203.0.113.10"],
"registrable": "shopcuatoi.vn"
},
"found": {},
"date_created": 1760317200
},
"overview": {
"company_id": 12,
"primary_url": "https://tencuahang.hubport.com.vn",
"custom_domain_feature": true,
"domains": []
}
}(Ví dụ rút gọn overview.)
Tên miền thuộc cửa hàng khác:
{
"error": ["error_domain_taken"],
"detail": {
"txt_name": "_hubport.shopcuatoi.vn",
"txt_value": "hubport-verify=9a8b7c6d5e4f30211203f4e5d6c7b8a9"
}
}