Chuyển tới nội dung chính

API Xác thực & Quản lý Tài khoản Hội viên

Tài liệu chi tiết toàn bộ các endpoint phục vụ cấu hình xác thực, đăng nhập bằng số điện thoại/email, OTP SMS/Zalo ZNS, đăng ký tài khoản mới, refresh token và quản lý mật khẩu trên ứng dụng zodutcan-user.

1. Cấu hình Cơ chế Đăng nhập & OTP​

Khi mở ứng dụng, zodutcan-user gọi endpoint này đầu tiên để xác định phương thức đăng nhập cho phép (qua Số điện thoại hay Email), trạng thái OTP và nhà cung cấp OTP được kích hoạt trên hệ thống (Firebase, eSMS, Zalo ZNS hoặc chế độ Demo).

  • Method: GET
  • Endpoint: /api/{locale}/v1/common/modules
  • Auth: Không yêu cầu (Public)

Response Thành công​

{
  "success": true,
  "message": "success",
  "otp": {
    "enabled": true,
    "provider": "zalo_zns",
    "fallback_provider": "backend_sms",
    "allow_demo": false,
    "sms_provider": "esms"
  },
  "firebase_otp_enabled": false,
  "enable_owner_login": "0",
  "enable_email_otp": "0",
  "enable_user_referral_earnings": "1",
  "enable_email_login": "0",
  "enable_user_sign_in_email_otp": "0",
  "enable_user_sign_in_email_password": "0",
  "enable_user_sign_in_mobile_otp": "1",
  "enable_user_sign_in_mobile_password": "1",
  "enable_user_email_login": "0",
  "enable_user_mobile_login": "1"
}
Ý nghĩa trường dữ liệu
  • otp.provider: Nhà cung cấp gửi mã OTP chính (zalo_zns: gửi qua Zalo Notification Service, esms: tin nhắn Brandname SMS, firebase: qua Firebase Auth, demo: cho phép OTP cố định khi dev).
  • otp.fallback_provider: Kênh dự phòng khi kênh chính không gửi được (backend_sms).
  • enable_user_mobile_login: Bằng "1" khi hệ thống kích hoạt đăng nhập chính bằng Số điện thoại.

2. Kiểm tra Số điện thoại Tồn tại​

Kiểm tra số điện thoại của người dùng đã có tài khoản trong hệ thống hay chưa để điều hướng đến màn hình Nhập mật khẩu hay Đăng ký mới.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/validate-mobile-for-login
  • Auth: Không yêu cầu (Public)

Request Body​

{
  "mobile": "0901234567"
}

Response Thành công​

{
  "success": true,
  "message": "success",
  "data": {
    "user_exist": true,
    "is_password": true
  }
}

3. Gửi Mã OTP Xác thực​

Gửi mã OTP 6 chữ số đến số điện thoại người dùng. Số điện thoại được ứng dụng tự động chuẩn hóa sang đầu số quốc gia +84.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/otp/send
  • Auth: Không yêu cầu (Public)

Request Body​

{
  "mobile": "901234567",
  "country_code": "+84",
  "purpose": "registration",
  "use_fallback": "0",
  "provider": "zalo_zns"
}
Tham sốBắt buộcMô tả
mobileCóSố điện thoại đã bỏ số 0 ở đầu (VD: 901234567).
country_codeCóMã quốc gia (mặc định: +84).
purposeKhôngMục đích gửi: registration (Đăng ký) hoặc reset_password (Quên mật khẩu).
use_fallbackKhông"1" nếu gửi lại qua kênh SMS dự phòng khi Zalo thất bại.

Response Thành công​

{
  "success": true,
  "message": "Mã xác thực đã được gửi tới số điện thoại của bạn.",
  "data": {
    "channel": "zalo_zns",
    "retry_after": 60
  }
}

4. Xác thực Mã OTP​

Kiểm tra mã OTP người dùng nhập vào.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/otp/verify
  • Auth: Không yêu cầu (Public)

Request Body​

{
  "mobile": "901234567",
  "otp": "839210",
  "purpose": "registration"
}

Response Thành công​

{
  "success": true,
  "message": "Xác thực OTP thành công.",
  "verification_token": "ver_tok_84f938a923bc7491b8d234"
}

5. Đăng nhập Hội viên​

Xác thực bằng số điện thoại / email và mật khẩu để cấp Bearer Access Token.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/login
  • Auth: Không yêu cầu (Public)

Request Body​

{
  "login": "0901234567",
  "password": "userPassword123"
}

Response Thành công​

{
  "token": "12|Xk98dJ28F0xL3298hdsf98234hjkfsd98234h...",
  "refresh_token": "13|Rf8201bndsf8234hjkfsd98234hjkfsd98...",
  "member": {
    "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
    "name": "Nguyễn Văn A",
    "email": "nguyenvana@gmail.com",
    "phone": "0901234567",
    "unique_identifier": "M-882194",
    "is_active": true,
    "created_at": "2026-01-10T10:00:00Z"
  }
}

6. Đăng ký Tài khoản Hội viên Mới​

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/register
  • Auth: Không yêu cầu (Public)

Request Body​

{
  "name": "Trần Thị B",
  "phone": "0909876543",
  "password": "securePassword123",
  "verification_token": "ver_tok_84f938a923bc7491b8d234",
  "referral_code": "REF888",
  "birthday": "1995-10-20"
}

Response Thành công​

{
  "token": "14|MnoPqRsTuVwXyZ1234567890abcdef...",
  "refresh_token": "15|RfTok9876543210abcdef...",
  "member": {
    "id": "019b8e21-34aa-7212-b11c-982341234abc",
    "name": "Trần Thị B",
    "phone": "0909876543",
    "unique_identifier": "M-991204",
    "is_active": true
  }
}

7. Làm mới Token Đăng nhập​

Khi Access Token hết hạn, DioProviderImpl trên ứng dụng tự động gọi endpoint này để xin cấp Access Token và Refresh Token mới mà không làm gián đoạn người dùng.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/refresh
  • Auth: Không yêu cầu Bearer Header (truyền refresh_token trong Body)

Request Body​

{
  "refresh_token": "13|Rf8201bndsf8234hjkfsd98234hjkfsd98..."
}

Response Thành công​

{
  "success": true,
  "token": "16|NewAccessToken123456...",
  "refresh_token": "17|NewRefreshToken654321..."
}

8. Đặt lại Mật khẩu & Đổi Mật khẩu​

8.1 Đặt lại mật khẩu​

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/update-password
  • Body: 
    {
      "phone": "0901234567",
      "verification_token": "ver_tok_84f938a923bc7491b8d234",
      "password": "newPassword2026",
      "password_confirmation": "newPassword2026"
    }

8.2 Đổi mật khẩu trong cài đặt tài khoản​

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/change-password
  • Auth: auth:member_api (Bearer Token)
  • Body: 
    {
      "current_password": "currentPassword123",
      "new_password": "newPassword2026",
      "new_password_confirmation": "newPassword2026"
    }

9. Đăng xuất & Xoá Tài khoản​

9.1 Đăng xuất​

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/logout
  • Auth: auth:member_api (Bearer Token)

9.2 Xoá vĩnh viễn tài khoản​

  • Method: POST
  • Endpoint: /api/{locale}/v1/user/delete-user-account
  • Auth: auth:member_api (Bearer Token)