HRMNhân viên
Đổi công ty đang làm việc
Chuyển phiên đăng nhập sang một công ty khác của cùng tài khoản mà không cần đăng nhập lại.
Một tài khoản có thể là nhân viên của nhiều công ty (cửa hàng). Mỗi JWT Token chỉ gắn với một công ty, vì vậy để làm việc với công ty khác, gọi API này để nhận JWT Token mới cho công ty đích. Danh sách công ty có thể đổi sang lấy từ Danh sách công ty của tôi (các phần tử có switchable = true).
Endpoint
POST /v1/usersessions/switchcompany
Headers
| Tên | Giá trị | Bắt buộc | Mô tả |
|---|---|---|---|
Authorization | <JWT> | Có | User Login Token hiện tại. API này không dùng được với API Key. |
Content-Type | application/json | Có |
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
target_company_id | int | Có | ID của công ty muốn chuyển sang |
Dùng target_company_id, không dùng company_id (tham số company_id nếu có trong body sẽ được hiểu là công ty hiện tại và bị bỏ qua).
Response Schema
HTTP 200 - JSON Object
Giống response của Đăng nhập - Bước 2, kèm thêm switched_from_company_id:
{
"jwt": "0123456789abcdef0123456789abcdef",
"refresh_token": "a1b2c3d4e5f6...",
"id": 1,
"email": "user@example.com",
"full_name": "Nguyễn Văn A",
"role": "1,100,102,103,110",
"company": { "id": 10500, "name": "Chi nhánh Hà Nội", ... },
"employee": { "id": 205, "company_id": 10500, "user_id": 1, ... },
"company_list": [
{ "id": 101, "user_id": 1, "company": { ... }, "employee": { ... }, "access": "full" },
{ "id": 205, "user_id": 1, "company": { ... }, "employee": { ... }, "access": "full" }
],
"access": "full",
"access_state": "trial",
"switched_from_company_id": 10311
}| Field | Mô tả |
|---|---|
jwt | JWT Token mới, gắn với công ty đích |
refresh_token | Refresh token của phiên mới |
company, employee | Thông tin công ty đích và nhân viên trong công ty đích |
role | Danh sách mã quyền của nhân viên trong công ty đích |
company_list | Danh sách công ty của tài khoản |
access, access_state | (Chỉ có trên Hubport SaaS) Trạng thái truy cập của công ty đích, xem Đăng nhập |
switched_from_company_id | ID công ty trước khi đổi |
Workflow & Logic
- Kiểm tra request dùng JWT của người dùng (không phải API Key).
- Kiểm tra
target_company_idkhác công ty hiện tại. - Kiểm tra giới hạn: tối đa 10 lần đổi công ty / 60 giây cho mỗi tài khoản.
- Kiểm tra tài khoản là nhân viên (chưa bị xoá, đang hoạt động) của công ty đích, công ty đích đang hoạt động và (trên Hubport SaaS) không bị khoá.
- Tạo phiên đăng nhập mới cho công ty đích và trả về JWT mới.
- Phiên cũ bị vô hiệu ngay: JWT cũ không dùng được nữa (trả lỗi
error_jwt_blacklisted). Ứng dụng phải thay JWT cũ bằng JWT mới cho các request tiếp theo.
API này vẫn gọi được khi công ty hiện tại đang bị khoá (error_company_locked), để người dùng chuyển sang công ty khác.
Error Codes
| HTTP | Code | Mô tả |
|---|---|---|
| 401 | error_session_not_found | Không tìm thấy phiên đăng nhập hiện tại |
| 401 | error_user_not_found | Không tìm thấy tài khoản |
| 403 | error_switch_company_session_required | Request không dùng JWT của người dùng (ví dụ dùng API Key) |
| 403 | error_impersonation_switch_company_denied | Phiên hỗ trợ chỉ đọc của nhân viên Hubport không được đổi công ty |
| 403 | error_employee_disabled | Tài khoản đang bị vô hiệu hoá trong công ty đích |
| 403 | error_company_disabled | Công ty đích đang bị vô hiệu hoá |
| 403 | error_target_company_locked | Công ty đích đang bị khoá. Response có thêm detail.reason, detail.state |
| 403 | error_two_factor_session_required | Tài khoản đã bật xác thực 2 lớp hoặc công ty đích bắt buộc 2FA, mà phiên hiện tại chưa đăng nhập bằng 2FA: đăng nhập lại vào công ty đích (bước 2 và 3 của Đăng nhập) |
| 404 | error_company_not_found | Không tìm thấy công ty đích hoặc tài khoản không thuộc công ty đó |
| 422 | error_target_company_id_required | Thiếu target_company_id |
| 422 | error_switch_company_same | Công ty đích trùng với công ty hiện tại |
| 429 | error_rate_limit_exceed | Đổi công ty quá nhiều lần (tối đa 10 lần / 60 giây) |
| 500 | error_session_can_not_be_saved | Lỗi tạo phiên làm việc mới |
Ví dụ
curl -X POST https://api.hubport.vn/v1/usersessions/switchcompany \
-H "Authorization: <JWT>" \
-H "Content-Type: application/json" \
-d '{"target_company_id": 10500}'Ví dụ lỗi khi công ty đích bị khoá:
{
"error": ["error_target_company_locked"],
"detail": { "reason": "suspended", "state": "suspended" }
}