Đăng nhập

Trên Hubport, một tài khoản (email) có thể là nhân viên của nhiều công ty (cửa hàng). Vì vậy đăng nhập gồm 2 bước: bước 1 xác thực email/mật khẩu và lấy danh sách công ty, bước 2 chọn công ty để nhận JWT Token. Mỗi JWT Token chỉ gắn với một công ty; để chuyển sang công ty khác sau khi đăng nhập, dùng Đổi công ty đang làm việc.

Hai API đăng nhập không cần header Authorization.

Bước 1: Khởi tạo đăng nhập (authenticateInit)Copy Anchor Link

Xác thực email/password và lấy danh sách các công ty mà người dùng tham gia.

Endpoint: POST /v1/users/authenticateinit

Body Parameters:

Response Schema:

{
  "total": 2,
  "limit": 20,
  "currentpage": 1,
  "items": [
    {
      "id": 101,
      "user_id": 1,
      "company": {
        "user_id": 1,
        "id": 10311,
        "name": "Công ty TNHH Phần Mềm Xanh",
        "domain": "phanmemxanh",
        "screenname": "phanmemxanh",
        "status": 1,
        "plan": 2,
        "date_created": 1609459200,
        ...
      },
      "employee": {
        "company_id": 10311,
        "user_id": 1,
        "id": 101,
        "full_name": "Nguyễn Văn A",
        "email": "[email protected]",
        "phone": "0987654321",
        "status": 1,
        ...
      },
      "access": "full"
    },
    {
      "id": 205,
      "user_id": 1,
      "company": {
        "user_id": 9,
        "id": 10500,
        "name": "Chi nhánh Hà Nội",
        "domain": "pmx-hanoi",
        "status": 1,
        ...
      },
      "employee": {
        "company_id": 10500,
        "user_id": 1,
        "id": 205,
        "full_name": "Nguyễn Văn A",
        "status": 1,
        ...
      },
      "access": "blocked"
    }
  ]
}

Response Fields (mỗi phần tử của items):

Lưu ý:

• Danh sách trả về tối đa 20 công ty.
• Chỉ gồm các công ty người dùng đang là nhân viên; công ty đã xoá người dùng khỏi danh sách nhân viên không xuất hiện (và không đăng nhập được ở bước 2).
• Nếu người dùng chỉ thuộc 1 công ty, ứng dụng có thể gọi luôn bước 2 với company_id của công ty đó.
• Email sẽ được chuyển về lowercase trước khi xử lý.

Bước 2: Hoàn tất đăng nhập (authenticateFinish)Copy Anchor Link

Xác thực và lấy JWT token cho công ty đã chọn.

Endpoint: POST /v1/users/authenticatefinish

Body Parameters:

Response Schema:

{
  "jwt": "0123456789abcdef0123456789abcdef",
  "refresh_token": "a1b2c3d4e5f6...",
  "date_expired": 1641920399,
  "id": 1,
  "email": "[email protected]",
  "full_name": "Nguyễn Văn A",
  "role": "1,100,102,103,110",
  "company": {
    "user_id": 1,
    "id": 10311,
    "name": "Công ty TNHH Phần Mềm Xanh",
    "domain": "phanmemxanh",
    "status": 1,
    "plan": 2,
    "date_created": 1609459200,
    ...
  },
  "employee": {
    "company_id": 10311,
    "user_id": 1,
    "id": 101,
    "full_name": "Nguyễn Văn A",
    "email": "[email protected]",
    "phone": "0987654321",
    "status": 1,
    ...
  },
  "company_list": [
    {
      "id": 101,
      "user_id": 1,
      "company": { "id": 10311, "name": "Công ty TNHH Phần Mềm Xanh", ... },
      "employee": { ... }
    }
  ],
  "access": "full",
  "access_state": "paid"
}

Response Fields:

Bước 3 (khi cần): Xác thực 2 lớpCopy Anchor Link

Tài khoản đã bật xác thực 2 lớp (2FA, mã 6 số từ ứng dụng xác thực như Google Authenticator), công ty bắt buộc mọi nhân viên dùng 2FA, hoặc người đăng nhập là chủ shop có kết nối sàn (Shopee / Lazada / TikTok Shop đang hoạt động, Hubport SaaS), thì bước 2 không trả JWT dù mật khẩu đúng. Response là HTTP 401 kèm mã tạm challenge:

{
  "error": ["error_two_factor_required"],
  "detail": {
    "challenge": "Q2hhbGxlbmdlVG9rZW5FeGFtcGxlRXhhbXBsZUFC123",
    "expires_in": 300,
    "purpose": "verify",
    "methods": ["totp", "recovery_code"],
    "company_required": false,
    "marketplace_required": false,
    "required_reason": ""
  }
}

• purpose = "verify" (lỗi error_two_factor_required): gửi mã 6 số đang hiện trong ứng dụng xác thực, hoặc một mã khôi phục (dạng xxxxx-xxxxx, mỗi mã dùng một lần).

  Endpoint: POST /v1/users/twofactorchallenge/verify, body {"challenge": "...", "code": "123456"}.

• purpose = "enroll" (lỗi error_two_factor_enroll_required): công ty bắt buộc 2FA, hoặc chủ shop có kết nối sàn, mà tài khoản chưa bật. Người dùng phải thiết lập trước khi có JWT:

  1. POST /v1/users/twofactorchallenge/enrollinit, body {"challenge": "..."}, trả {"secret", "otpauth_url", "expires_in"}. Hiện otpauth_url dạng mã QR để người dùng quét bằng ứng dụng xác thực.
  2. POST /v1/users/twofactorchallenge/enrollfinish, body {"challenge": "...", "code": "123456"}. Response có thêm recovery_codes (10 mã khôi phục, chỉ trả một lần: ứng dụng phải hiện cho người dùng lưu lại).

Thành công: response giống bước 2 (jwt, refresh_token, company, ...) kèm two_factor_method (totp hoặc recovery_code). Mã challenge hết hạn sau expires_in giây và chỉ dùng được một lần; hết hạn thì gọi lại bước 2. Ba API này không cần header Authorization.

Error CodesCopy Anchor Link

Sử dụng JWT TokenCopy Anchor Link

Sau khi đăng nhập thành công, sử dụng JWT token trong header của các request tiếp theo (gửi nguyên giá trị, không có tiền tố Bearer):

Authorization: 0123456789abcdef0123456789abcdef

Xem thêm User Login Token.