Departments

5/8/2026

blog.summarize

blog.share_blog

Departments API

API dùng để xem danh sách, xem chi tiết, tạo, cập nhật và xóa phòng ban trong workspace.

Xác thực

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

1. Xem danh sách phòng ban

Endpoint: POST /bapi/v1/departments/list

{
  "order": "name",
  "sort": "asc",
  "is_active": 1,
  "limit": 1000,
  "type": "tree"
}

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`
`ids`	String/Array	Không	Lọc theo ID phòng ban
`name`	String	Không	Lọc theo tên
`is_active`	Integer/String	Không	`1` đang hoạt động, `0` ngừng hoạt động
`manager_ids`	String/Array	Không	Lọc theo ID người quản lý
`level`	Integer/Array	Không	Lọc theo cấp phòng ban
`level_operator`	String	Không	Toán tử cho `level`, ví dụ `IN`
`hierarchy_id`	String	Không	Lấy phòng ban này và các phòng ban cấp dưới
`sub_level`	Integer	Không	Giới hạn số cấp dưới được trả về
`potential_parent_ids`	String/Array	Không	Tìm các phòng ban có thể làm phòng ban cha
`created_start` / `created_end`	Long	Không	Khoảng thời gian tạo, timestamp mili giây
`total_personnel_start` / `total_personnel_end`	Integer	Không	Khoảng số lượng nhân sự
`type`	String	Không	Kiểu kết quả: `list`, `tree` hoặc `group`; mặc định `list`
`group_by`	String	Không	Trường nhóm khi `type=group`
`order`	String	Không	Trường sắp xếp, mặc định `name`
`sort`	String	Không	`asc` hoặc `desc`, mặc định `asc`

curl --location 'https://{workspace-domain}/bapi/v1/departments/list' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{"order":"name","sort":"asc","is_active":1,"limit":1000,"type":"tree"}'

Khi type=tree, các phòng ban con được trả trong trường children của phòng ban cha.

2. Xem chi tiết phòng ban

Endpoint: POST /bapi/v1/departments/view

{"id":"XSGDAFMQXEKUIV"}

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

3. Tạo phòng ban

Endpoint: POST /bapi/v1/departments

{
  "name": [
    {"key":"vi","value":"Kinh doanh"},
    {"key":"en","value":"Sales"}
  ],
  "parent_id": null,
  "is_active": "1",
  "managers": [
    {
      "personnel_id":"PERXUDUQFEKMEK",
      "position_id":"POSDAFMQ8EKUI4",
      "level":1
    }
  ]
}

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 phòng ban, tối đa 100 ký tự
`parent_id`	String/null	Không	ID phòng ban cha; `null` để tạo ở cấp gốc
`is_active`	String/Integer	Không	`1` đang hoạt động, `0` ngừng hoạt động
`managers`	Array	Không	Danh sách người quản lý
`managers[].personnel_id`	String	Có trong mỗi manager	ID nhân sự
`managers[].position_id`	String	Có trong mỗi manager	ID vị trí
`managers[].level`	Integer	Có trong mỗi manager	Cấp quản lý

Response thành công có HTTP status 201 và thông tin phòng ban mới trong data.

4. Cập nhật phòng ban

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

{
  "name": [{"key":"vi","value":"Kinh doanh toàn quốc"}],
  "parent_id": "DEPPARENT00001",
  "is_active": "1"
}

Chỉ cần gửi các trường muốn thay đổi. Nếu gửi managers, danh sách này là danh sách quản lý mới của phòng ban.

5. Xóa phòng ban

Endpoint: POST /bapi/v1/departments/delete

{
  "ids": ["XSGDAFMQXEKUIV"],
  "type": 1
}

Trường	Kiểu	Bắt buộc	Mô tả
`ids`	Array[String]	Có	Danh sách ID phòng ban cần xóa
`type`	Integer	Có	Cách xử lý dữ liệu liên quan, xem bên dưới
`target_department_id`	String	Khi `type=3`	Phòng ban nhận các phòng ban con và nhân sự được chuyển sang

Giá trị type:

1: xóa các phòng ban đã chọn và các phòng ban con.
2: xóa các phòng ban đã chọn, phòng ban con và nhân sự liên quan.
3: xóa các phòng ban đã chọn, đồng thời chuyển phòng ban con và nhân sự sang target_department_id.

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