Positions

5/8/2026

blog.summarize

blog.share_blog

Positions API

API dùng để xem danh sách, xem chi tiết, tạo, cập nhật và xóa vị trí công việc trong workspace.

Xác thực

Authorization: Bearer {tokenId}-{secretToken}
Content-Type: application/json

1. Xem danh sách vị trí

Endpoint: POST /bapi/v1/positions/list

{
  "id": "POSDAFMQSEKUID",
  "idOperator": "IN",
  "page": 1,
  "limit": 20,
  "order": "name",
  "sort": "asc"
}

Trường	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Số trang, mặc định `1`
`limit`	Integer	Không	Số kết quả mỗi trang, mặc định `20`
`id` / `ids`	String/Array	Không	Lọc theo ID vị trí
`idOperator` / `id_operator`	String	Không	Toán tử cho `id`, ví dụ `IN`
`name`	String	Không	Lọc theo tên vị trí
`is_active`	Integer/String	Không	`1` đang hoạt động, `0` ngừng hoạt động
`department_ids`	String/Array	Không	Lọc theo phòng ban
`is_department_only`	Integer	Không	`1` chỉ dùng trong các phòng ban được chọn, `0` dùng toàn workspace
`could_manager_position`	Integer	Không	`1` nếu vị trí có thể là vị trí quản lý
`created_start` / `created_end`	Long	Không	Khoảng thời gian tạo, timestamp mili giây
`updated_start` / `updated_end`	Long	Không	Khoảng thời gian cập nhật, timestamp mili giây
`total_personnel_start` / `total_personnel_end`	Integer	Không	Khoảng số lượng nhân sự
`order`	String	Không	Trường sắp xếp, mặc định `updated`
`sort`	String	Không	`asc` hoặc `desc`, mặc định `desc`

curl --location 'https://{workspace-domain}/bapi/v1/positions/list' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{"id":"POSDAFMQSEKUID","idOperator":"IN","page":1,"limit":20}'

Response thành công trả danh sách trong data và thông tin phân trang trong meta.

2. Xem chi tiết vị trí

Endpoint: POST /bapi/v1/positions/view

{"id":"POSDAFMQSEKUID"}

id là ID vị trí và là trường bắt buộc. Response trả một vị trí trong data.

3. Tạo vị trí

Endpoint: POST /bapi/v1/positions

{
  "name": [
    {"key": "vi", "value": "Trưởng phòng kinh doanh"},
    {"key": "en", "value": "Sales Manager"}
  ],
  "is_department_only": 1,
  "could_manager_position": 1,
  "department_ids": ["XSGDAFMQXEKUIV"]
}

Trường	Kiểu	Bắt buộc	Mô tả
`name`	Array	Có	Tên theo ngôn ngữ
`name[].key`	String	Có	Mã ngôn ngữ, ví dụ `vi`, `en`
`name[].value`	String	Có	Tên vị trí, tối đa 100 ký tự
`is_department_only`	Integer	Có	`1` giới hạn theo phòng ban, `0` dùng toàn workspace
`department_ids`	Array[String]	Có khi `is_department_only=1`	Các phòng ban được dùng vị trí
`could_manager_position`	Integer	Không	`1` có thể là vị trí quản lý, `0` không
`is_active`	Integer	Không	`1` đang hoạt động, `0` ngừng hoạt động

Response thành công có HTTP status 201 và thông tin vị trí mới trong data.

4. Cập nhật vị trí

Endpoint: PUT /bapi/v1/positions/{id}

{
  "name": [{"key":"vi","value":"Giám đốc kinh doanh"}],
  "could_manager_position": 1
}

Chỉ cần gửi các trường muốn thay đổi.

5. Xóa vị trí

Endpoint: POST /bapi/v1/positions/delete

{
  "data": [
    {
      "id": "POSDAFMQSEKUID",
      "departments": [
        {
          "id": "XSGDAFMQXEKUIV",
          "position_id": "POSDAFMQSEKUID",
          "newPosition_id": "POSREPLACEMENT01"
        }
      ]
    }
  ]
}

data là mảng bắt buộc. Mỗi phần tử cần id. Nếu vị trí đang được sử dụng, departments chỉ định vị trí thay thế cho nhân sự trong từng phòng ban.

Lỗi thường gặp

Các mã thường gặp: 400 cho lỗi nghiệp vụ hoặc dữ liệu không hợp lệ, 401 khi xác thực thất bại, 429 khi vượt giới hạn request và 500 cho lỗi không mong muốn.

blog.blogs_related