Đăng ký tài khoản

Quy trình đăng ký tài khoản mới được chia làm 2 giai đoạn: Khởi tạo (gửi OTP) và Hoàn tất (xác thực OTP + tạo tài khoản).

Headers

Key	Value	Bắt buộc	Mô tả
`SiteTenantId`	`{tenant_id}`	Có	ID của công ty/tenant.

Bước 1: Khởi tạo đăng ký

POST /site/customers/registerinit

Dùng để kiểm tra thông tin ban đầu và gửi mã OTP xác thực số điện thoại.

Logic xử lý

Kiểm tra full_name không rỗng, phone chỉ gồm chữ số và chưa được đăng ký trong shop hiện tại.
Kiểm tra định dạng email (nếu có).
Kiểm tra mật khẩu có ít nhất 7 ký tự.
Kiểm tra group hợp lệ. Với nhóm Nhà phân phối (group = 5) bắt buộc có representative_name, representative_id và representative_file_id_list (file đã tải lên shop này trong vòng 3 phút).
Tạo mã OTP (6 số) và lưu tạm với thời hạn 5 phút.
Gửi OTP qua tin nhắn (ZNS/SMS) theo nhà cung cấp shop đã cấu hình. Nếu shop bật chế độ thử nghiệm ZNS, OTP là mã cố định do shop cấu hình (mặc định 123456).
Trả về passport_id để Frontend sử dụng ở bước sau.

Request Body

{
  "full_name": "Nguyễn Văn B",
  "phone": "0912345678",
  "password": "password123",
  "email": "[email protected]",
  "group": 0, // 0: Khách lẻ, 1: VIP, 3: Khách sỉ, 5: Nhà phân phối, 7: Cộng tác viên
  "social_links": ["https://facebook.com/nguyenvanb"] // Không bắt buộc
}

Trường	Kiểu	Bắt buộc	Mô tả
`full_name`	`string`	Có	Họ tên khách hàng.
`phone`	`string`	Có	Số điện thoại (chỉ gồm chữ số), dùng làm tên đăng nhập.
`password`	`string`	Có	Mật khẩu, tối thiểu 7 ký tự.
`email`	`string`	Không	Email.
`group`	`integer`	Không	Nhóm khách hàng (mặc định `0`). Xem Customer Group.
`representative_name`	`string`	Với `group = 5`	Tên người đại diện.
`representative_id`	`string`	Với `group = 5`	Số CCCD/MST người đại diện.
`representative_file_id_list`	`array`	Với `group = 5`	Danh sách ID file ảnh giấy tờ (tải lên qua API upload file của storefront).
`social_links`	`array` hoặc `string`	Không	Danh sách link mạng xã hội (mảng hoặc chuỗi cách nhau dấu phẩy). Hệ thống tự nhận diện Facebook, TikTok, Instagram, Zalo, Shopee, Telegram.

Response Schema (200)

{
  "id": "uuid-string",
  "company_id": 123,
  "passport_id": "passport-id-string",
  "full_name": "Nguyễn Văn B",
  "phone": "0912345678",
  "otp_length": 6,
  "date_created": 1734924700,
  "date_expired": 1734925000,
  "metadata": {
    "action": "register"
  }
}

Bước 2: Hoàn tất đăng ký

POST /site/customers/registerfinish

Xác thực mã OTP và chính thức tạo tài khoản.

Logic xử lý

Kiểm tra lại toàn bộ thông tin như Bước 1 (để tránh race condition).
Xác thực mã OTP thông qua phone và passport_id. OTP chỉ dùng được một lần.
Nếu khách hàng đăng ký nhóm Distributor hoặc Collaborator, trạng thái nhóm (group_status) sẽ là 1 (Chờ duyệt). Các nhóm còn lại có trạng thái 0.
Băm mật khẩu và lưu tài khoản (hoặc tạo tài khoản trên hệ thống tài khoản riêng của shop nếu shop dùng chế độ remote_api).
Trả về thông tin khách hàng vừa tạo. API này không tự đăng nhập, Frontend cần gọi Đăng nhập để lấy token.

Request Body

{
  "full_name": "Nguyễn Văn B",
  "phone": "0912345678",
  "password": "password123",
  "email": "[email protected]",
  "passport_id": "passport-id-string",
  "otp": "123456",
  "group": 0,
  "representative_name": "", // Nếu là NPP/CTV
  "representative_id": "", // CCCD/MST
  "representative_file_id_list": [], // Ảnh CCCD/GPKD
  "social_links": []
}

Gửi lại đầy đủ các trường của Bước 1, kèm passport_id và otp.

Response Schema (200)

Trả về Customer Object.

Các lỗi thường gặp (422)

Mã lỗi	Mô tả
`error_fullname_required`	Chưa nhập họ tên.
`error_phone_required`	Chưa nhập số điện thoại.
`error_phone_invalid`	Số điện thoại sai định dạng (chỉ được chứa chữ số).
`error_phone_existed`	Số điện thoại đã được đăng ký.
`error_email_invalid`	Email sai định dạng.
`error_password_empty`	Chưa nhập mật khẩu.
`error_password_length_invalid`	Mật khẩu ngắn hơn 7 ký tự.
`error_group_invalid`	Giá trị `group` không hợp lệ.
`error_representative_name_required`	Thiếu tên người đại diện (nhóm Nhà phân phối).
`error_representative_id_required`	Thiếu CCCD/MST người đại diện (nhóm Nhà phân phối).
`error_representative_file_id_list_required`	Thiếu ảnh giấy tờ (nhóm Nhà phân phối).
`error_representative_file_id_invalid`	ID file không hợp lệ.
`error_representative_file_not_found`	File không tồn tại hoặc không thuộc shop.
`error_representative_file_id_expired`	File được tải lên quá 3 phút trước.
`error_passport_id_required`	(Bước 2) Thiếu `passport_id`.
`error_otp_required`	(Bước 2) Thiếu `otp`.
`error_passport_otp_not_found`	(Bước 2) Phiên OTP không tồn tại hoặc đã hết hạn (quá 5 phút).
`error_otp_invalid`	(Bước 2) Mã OTP không chính xác.

Các lỗi hệ thống (500)

Mã lỗi	Mô tả
`error_save_passport`	Không lưu được phiên OTP.
`error_create_customer_memo`	Không tạo được yêu cầu gửi tin nhắn OTP.
`error_provider_not_supported`	Nhà cung cấp gửi tin nhắn shop cấu hình không được hỗ trợ.
`error_provider_response_invalid_no_error_msg`, `error_provider_request_failed_unknown_reason`	Gửi tin nhắn OTP thất bại.

Đăng ký tài khoản

HeadersCopy Anchor Link

Bước 1: Khởi tạo đăng kýCopy Anchor Link

Logic xử lýCopy Anchor Link

Request BodyCopy Anchor Link

Response Schema (200)Copy Anchor Link

Bước 2: Hoàn tất đăng kýCopy Anchor Link

Logic xử lýCopy Anchor Link

Request BodyCopy Anchor Link

Response Schema (200)Copy Anchor Link

Các lỗi thường gặp (422)Copy Anchor Link

Các lỗi hệ thống (500)Copy Anchor Link

On this page

Headers

Bước 1: Khởi tạo đăng ký

Logic xử lý

Request Body

Response Schema (200)

Bước 2: Hoàn tất đăng ký

Logic xử lý

Request Body

Response Schema (200)

Các lỗi thường gặp (422)

Các lỗi hệ thống (500)