Gói dịch vụ & thanh toán
Đăng ký cửa hàng - Bước 1: Gửi OTP
Endpoint công khai bắt đầu đăng ký cửa hàng mới trên Hubport SaaS, gửi mã OTP tới email
Chỉ có trên Hubport SaaS
Đây là endpoint công khai phục vụ trang đăng ký cửa hàng của 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/platformsignups/init
Không cần đăng nhập. Luồng đăng ký gồm 2 bước:
- Bước 1 (trang này): gửi thông tin đăng ký, hệ thống gửi mã OTP 6 chữ số tới email, hiệu lực 15 phút.
- Bước 2: Xác minh OTP & tạo cửa hàng bằng
signup_id, mã OTP và mật khẩu.
Trước khi gọi, nên gọi Trạng thái nền tảng để biết đăng ký có đang mở (signup_enabled) và loại captcha cần hiển thị (signup_captcha_provider).
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
full_name | string | Có | Họ tên chủ cửa hàng (tối đa 255 ký tự, thẻ HTML bị loại bỏ) |
email | string | Có | Email đăng nhập, nhận mã OTP (tối đa 191 ký tự, không phân biệt hoa thường). Email đã có tài khoản Hubport vẫn đăng ký được thêm cửa hàng (xem Bước 2) |
phone | string | Có | Số điện thoại: 8–15 chữ số, có thể có dấu + ở đầu (các ký tự khác như khoảng trắng, dấu chấm bị bỏ qua) |
company_name | string | Có | Tên cửa hàng (tối đa 255 ký tự) |
screenname | string | Có | Mã định danh cửa hàng, dùng làm tên miền con. 3–50 ký tự gồm chữ thường a-z, số và dấu -, không bắt đầu/kết thúc bằng -; không trùng cửa hàng khác và không thuộc danh sách tên dành riêng của hệ thống |
captcha_token | string | Tuỳ cấu hình | Token captcha lấy từ widget captcha (hiển thị bằng signup_captcha_site_key, với Turnstile đặt action là signup). Bắt buộc khi signup_captcha_provider khác none. Mỗi token chỉ dùng một lần, kể cả khi gửi lại mã OTP |
source | string | Không | Nguồn đăng ký (tối đa 64 ký tự). Mặc định: web |
nonce | string | Không | Chuỗi ngẫu nhiên khác nhau cho mỗi lần gọi. Nên gửi để thao tác "Gửi lại mã" với cùng thông tin không bị chặn bởi cơ chế chống gửi trùng (HTTP 409 error_idempotent_check_duplicate_found) |
{
"full_name": "Nguyễn Văn A",
"email": "[email protected]",
"phone": "0901234567",
"company_name": "Shop ABC",
"screenname": "shopabc",
"captcha_token": "<CAPTCHA_TOKEN>",
"nonce": "a1b2c3d4"
}Response Schema
HTTP 201 - Created
| Trường | Kiểu | Mô tả |
|---|---|---|
signup_id | string | Mã phiên đăng ký, dùng ở Bước 2 |
otp_length | int | Độ dài mã OTP (6) |
expires_at | int | Thời điểm mã OTP hết hạn (Unix timestamp) |
{
"signup_id": "6f1c2a7e-3b9d-4c51-9a8e-2f0b7d4e1c33",
"otp_length": 6,
"expires_at": 1760318100
}Workflow & Logic
- Kiểm dữ liệu cơ bản (họ tên, email, số điện thoại, tên cửa hàng, screenname).
- Kiểm đăng ký đang mở, tên miền email không bị chặn, giới hạn số lần đăng ký theo IP và theo email, captcha.
- Kiểm trước dữ liệu tạo cửa hàng (screenname đã tồn tại / không hợp lệ...). Kết quả bước này như nhau dù email đã có tài khoản Hubport hay chưa; giới hạn số cửa hàng của tài khoản được kiểm ở Bước 2.
- Tạo phiên đăng ký chờ xác minh và gửi mã OTP qua email. Phiên đăng ký chờ trước đó của cùng email (nếu có) bị thay thế, mã OTP cũ hết hiệu lực.
Error Codes
| HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 403 | error_signup_disabled | Hubport đang tạm ngừng nhận đăng ký mới |
| 403 | error_signup_max_companies_reached | Nền tảng tạm thời không nhận thêm cửa hàng mới |
| 404 | error_saas_mode_inactive | Không phải Hubport SaaS |
| 409 | error_idempotent_check_duplicate_found | Gửi trùng nội dung request trong thời gian ngắn (dùng nonce khác nhau) |
| 422 | error_fullname_required | Thiếu họ tên |
| 422 | error_email_required | Thiếu email |
| 422 | error_email_invalid | Email không hợp lệ |
| 422 | error_phone_invalid | Số điện thoại không hợp lệ |
| 422 | error_company_name_required | Thiếu tên cửa hàng |
| 422 | error_screenname_required | Thiếu screenname |
| 422 | error_screenname_too_short | Screenname quá ngắn |
| 422 | error_screenname_invalid | Screenname sai định dạng |
| 422 | error_screenname_reserved | Screenname thuộc danh sách tên dành riêng |
| 422 | error_screenname_existed | Screenname đã được cửa hàng khác sử dụng |
| 422 | error_email_domain_blocked | Tên miền email không được phép đăng ký |
| 422 | error_captcha_required | Thiếu captcha_token |
| 422 | error_captcha_invalid | Captcha không hợp lệ, đã hết hạn hoặc đã được dùng. Mỗi token captcha chỉ dùng được một lần: lấy token mới (reset widget) trước khi gửi lại |
| 429 | error_too_many_requests | Vượt giới hạn số lần đăng ký. detail.scope là phạm vi bị giới hạn (ip_hour, ip_day, email_day), detail.limit là số lần tối đa, detail.retry_after là số giây cần chờ |
| 500 | error_signup_save | Không lưu được phiên đăng ký |
| 502 | error_identity_unavailable | Hệ thống tài khoản tạm thời không phản hồi, vui lòng thử lại |
| 502 | error_email_send_failed | Không gửi được email OTP, vui lòng thử lại |
| 503 | error_captcha_not_configured | Hệ thống bật captcha nhưng chưa cấu hình xong, tạm thời không nhận đăng ký |
| 503 | error_captcha_unavailable | Không kiểm được captcha lúc này (dịch vụ captcha không phản hồi), vui lòng thử lại |
Ví dụ lỗi giới hạn tần suất:
{
"error": ["error_too_many_requests"],
"detail": {
"scope": "email_day",
"limit": 3,
"retry_after": 41230
}
}Ví dụ
curl -X POST "https://api.hubport.vn/v1/platformsignups/init" \
-H "Content-Type: application/json" \
-d '{"full_name":"Nguyễn Văn A","email":"[email protected]","phone":"0901234567","company_name":"Shop ABC","screenname":"shopabc","captcha_token":"<CAPTCHA_TOKEN>","nonce":"a1b2c3d4"}'