# Tham chiếu: Nhân viên và vai trò

Danh sách nhân viên và vai trò để chọn người phụ trách khi tạo đơn hoặc đổi phân công đơn. Mọi đường dẫn dưới `https://danix.vn/api/open/v1`. Đặc tả máy đọc: [openapi.json](/openapi.json).

## Danh sách nhân viên {#listStaff}

`GET /staff`

Các nhân viên đang làm việc trong shop (không gồm tài khoản hệ thống, ứng dụng kết nối hay người bị vô hiệu hoá), chỉ mã và tên. Dùng `id` làm `handlerUserId` khi tạo đơn hay đổi người phụ trách. Người nào chọn được làm người phụ trách còn tuỳ quyền sửa đơn của họ — chọn người không dùng được thì tạo đơn chia theo bậc dưới, đổi người phụ trách thì `validation-failed`.

**Quyền cần có:** khoá có quyền `pos.orders.create`.

**Ví dụ yêu cầu**

```bash
curl -X GET "https://danix.vn/api/open/v1/staff" \
  -H "Authorization: Bearer dnx_live_…"
```

**Phản hồi mẫu (200)**

```json
{
  "data": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000a01",
      "name": "Nguyễn Văn An"
    }
  ]
}
```

**Trường của phản hồi**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `data` | array<object> | có | Các nhân viên. |
| `data[].id` | string (uuid) | có | Mã người dùng — dùng làm `handlerUserId`. |
| `data[].name` | string | có | Tên hiển thị của nhân viên. |

**Lỗi**

| Trạng thái | Mã `code` | Ý nghĩa |
| --- | --- | --- |
| 401 | [`invalid-api-key`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |

Định dạng lỗi và bảng mọi mã `code`: [Lỗi](/developers/errors).

## Danh sách vai trò {#listRoles}

`GET /roles`

Các vai trò của shop (không gồm vai trò của ứng dụng kết nối), chỉ mã và tên. Dùng `id` làm `handlerRoleId` khi tạo đơn: đơn chia lần lượt cho những người của vai trò ấy có quyền sửa đơn.

**Quyền cần có:** khoá có quyền `pos.orders.create`.

**Ví dụ yêu cầu**

```bash
curl -X GET "https://danix.vn/api/open/v1/roles" \
  -H "Authorization: Bearer dnx_live_…"
```

**Phản hồi mẫu (200)**

```json
{
  "data": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000b01",
      "name": "Bán hàng"
    }
  ]
}
```

**Trường của phản hồi**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `data` | array<object> | có | Các vai trò. |
| `data[].id` | string (uuid) | có | Mã vai trò — dùng làm `handlerRoleId`. |
| `data[].name` | string | có | Tên vai trò. |

**Lỗi**

| Trạng thái | Mã `code` | Ý nghĩa |
| --- | --- | --- |
| 401 | [`invalid-api-key`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |

Định dạng lỗi và bảng mọi mã `code`: [Lỗi](/developers/errors).