获取部门列表

该接口用于获取当前公司下的部门列表信息

请求方法

GET /departments

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
departments 数组 详情见下

departments的结构

参数名 类型 说明
id 整型 部门id
name 字符串 部门名称
sub_department 数组 子部门

示例

请求

curl https://demo.udesk.cn/open_api_v1/departments?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X GET \
-H 'content-type: appliacation/json' \

返回

{
    "code": 1000,
    "departments": [
        {
            "id": 1,
            "name": "部门1",
            "sub_department": [
                {
                    "id": 10,
                    "name": "子部门1",
                    "sub_department": [ {"id": 11, "name": "子部门2", "sub_department": []} ]
                },
                {
                    "id": 11,
                    "name": "子部门2",
                    "sub_department": []
                }
            ]
        },
        {
            "id": 2,
            "name": "部门2",
            "sub_department": []
        },
        {
            "id": 3,
            "name": "部门3",
            "sub_department": []
        }
    ]   
}

创建部门

该接口用于创建部门

请求方法

POST /departments

请求参数(request body)

参数 必填 类型 说明 限制 默认
name 字符串 部门名称 不超过255个字符
parent_id 整型 上级部门id 0

注意: parent_id是上级部门的id,如果不传入默认为0。parent_id为0时意味着上级部门不存在

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
id 整型 创建成功的部门id

示例

请求

curl https://demo.udesk.cn/open_api_v1/departments?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X POST \
-H 'content-type: appliacation/json' \
-d '
{
  "name": "部门12",
  "parent_id": 1
}'

返回

{
    "code": 1000,
    "id": 5
}

编辑部门

该接口用于编辑已有部门的基本信息

请求方法

PUT /departments/:id

请求参数(url)

参数名 类型 必填 说明 限制
id 整型 部门id

请求参数(request body)

参数 必填 类型 说明 限制 默认
name 字符串 部门名称 不超过255个字符

注意:该接口只能根据id修改部门的name,不能修改部门的parent_id,即无法改变部门的层级关系。
即使在请求参数中增加了parent_id,也不会生效,并且无报错信息

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
department 对象 部门信息,结构如下

department的结构

参数名 类型 说明
id 整型 部门id
name 字符串 部门名称
parent_id 整型 上级部门id

示例

请求

curl https://demo.udesk.cn/open_api_v1/departments/5?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X PUT \
-H 'content-type: appliacation/json' \
-d '{"name": "新部门12"}'

返回

{
    "code": 1000,
    "department": {
      "id": 5,
      "name": "新部门12",
      "parent_id": 1
    }
}

删除部门

该接口用于删除已有部门的

请求方法

DELETE /departments/:id

请求参数(url)

参数名 类型 必填 说明 限制
id 整型 部门id

请求参数(request body)

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 执行结果说明

示例

请求

curl https://demo.udesk.cn/open_api_v1/departments/5?email=admin@udesk.cn&timestamp=1503298812&sign=4a38e71a044e4dccb6069418abd2153e905a31cb \
-X DELETE \
-H 'content-type: application/json' \

返回

{
    "code": 1000,
    "message": "id为5的部门删除成功"
}

Code错误码

错误码 message信息 exception:message信息 描述
2000 未知错误 验证失败: Name已经被使用 Name已经被使用
不存在parent_id为xxx的上级部门 不存在parent_id为xxx的上级部门
传入的parent_id不是非负整数 传入的parent_id格式不对,不是非负整数
没有找到该资源 根据传入的id,找不到待编辑的部门,可能是id不存在或id格式有误
2015 非管理员不可以操作 非管理员不可以操作 调用接口时的邮箱必须为管理员邮箱,非管理员不可以操作
2059 open api签名不对 open api签名不对 open api签名不对,详细内容参考鉴权部分的文档