更新部门
本接口用于更新部门信息。仅更新显式传参的部分。
Tip: - 只能在当前应用的通讯录授权范围内（可通过管理后台>应用权限>通讯录授权页面查看）更新部门信息。
变更部门的父部门，需要有变更前后的部门权限，才能变更成功。
变更部门的负责人，需要有变更前后的人员权限，才能变更成功。 > - 本接口中支持的user_access_token 默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可更新部门时，管理员管理范围取最大集。管理员权限可查看帮助中心文档： 管理员创建管理员角色及分配权限
修改部门ID（department_id）需要悉知以下影响：
- 部门ID（department_id）是部门在企业内的唯一ID，可能会被应用引用来实现各种内部逻辑，唯一ID修改之后可能会导致引用失败，导致所有引用且保存了‘被修改 ID 部门’的业务全部受影响。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/directory/v1/departments/:department_id |
| HTTP Method | PATCH |
| 接口频率限制 | 10 次/秒 |
| 支持的应用类型 | custom |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可 | directory:department.update:write 更新部门 directory:department:write 创建、更新、删除部门 |
| 字段权限要求 | > Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:employee.base.external_id:read 查看员工自定义 ID |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
department_id | string | 部门ID，与department_id_type类型保持一致 示例值："h12921" 数据校验规则： - 最大长度： 64 字符 |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
employee_id_type | string | 否 | 用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - employee_id: 企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。默认值： open_id当值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID |
department_id_type | string | 否 | 此次调用中使用的部门ID的类型 示例值：open_department_id 可选值有： - open_department_id: 用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 不相同。 - department_id: 用来标识租户内一个唯一的部门默认值： open_department_id |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
department | update_department | 是 | 更新部门信息 |
└ custom_department_id | string | 否 | 自定义部门ID。注意： 1. 除需要满足正则规则外，同时不能以od-开头 2. 正则校验：^[a-zA-Z0-9][a-zA-Z0-9_-@.]{0,63}$ 数据校验规则： 长度范围：1-64字符 示例值："eedasqwA" |
└ name | i18n_text | 否 | 部门名称 |
└ default_value | string | 是 | 默认值 示例值："张三 长度范围：1-100" |
└ i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 示例值： {"zh_cn":"张三"} |
└ parent_department_id | string | 否 | 父部门ID,与department_id_type类型保持一致 示例值："100" |
└ leaders | department_leader\[\] | 否 | 部门负责人 数据校验规则： - 长度范围： 0 ～ 20 |
└ leader_type | int | 是 | 部门负责人类型 示例值：1 可选值有： - 1: 主 - 2: 副 |
└ leader_id | string | 是 | 部门负责人ID,与employee_id_type类型保持一致 示例值："u273y71" |
└ order_weight | string | 否 | 在上级部门下的排序权重，返回结果将按照order_weight的值进行升序排列。 示例值："100" |
└ enabled_status | boolean | 否 | 是否启用 示例值：true |
└ custom_field_values | custom_field_value\[\] | 否 | 部门自定义字段值 数据校验规则： - 长度范围： 0 ～ 100 |
└ field_type | string | 否 | 自定义字段类型 示例值："1" 可选值有： - 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表 |
└ text_value | i18n_text | 否 | 文本字段值 |
└ default_value | string | 是 | 默认值 示例值："张三" |
└ i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 示例值： { "zh_cn": "中文","ja_jp": "ja_jp_name","en_us": "en_us_name"} |
└ url_value | url_value | 否 | 网页链接字段值 |
└ link_text | i18n_text | 是 | 网页标题 |
└ default_value | string | 是 | 默认值 示例值："张三" |
└ i18n_value | map<string, string> | 否 | 国际化值，key为zh_cn, ja_jp, en_us, value为对应的值 示例值： { "zh_cn": "中文","ja_jp": "ja_jp_name","en_us": "en_us_name"} |
└ url | string | 是 | 移动端网页链接 示例值："https://m.bytedance.com/afnasjfna" |
└ pcurl | string | 是 | 桌面端网页链接 示例值："http://www.fs.cn" |
└ enum_value | enum_value | 否 | 枚举字段值 |
└ enum_ids | string\[\] | 是 | 选项结果ID 示例值：["1"] 数据校验规则： - 长度范围： 0 ～ 100 |
└ enum_type | string | 是 | 选项类型 示例值："1" 可选值有： - 1: 文本 - 2: 图片 |
└ user_values | user_value\[\] | 否 | 人员字段值 数据校验规则： - 长度范围： 0 ～ 100 |
└ ids | string\[\] | 是 | 人员ID，与employee_id_type类型保持一致 示例值：["1"] 数据校验规则： - 长度范围： 0 ～ 100 |
└ phone_value | phone_value | 否 | 电话字段值 |
└ phone_number | string | 是 | 电话号 示例值："18812345678" |
└ extension_number | string | 否 | 分机号 长度范围：0-99字符 示例值："234234234" |
└ field_key | string | 否 | 自定义字段key 示例值："C-1000001" |
请求体示例
json
{"department":{"custom_department_id":"eedasqwA",
"name":{"default_value":"张三
长度范围：1-100",
"i18n_value":{"zh_cn":"张三"}},
"parent_department_id":"100",
"leaders":[{
"leader_type": 1,
"leader_id": "u273y71"
}],
"order_weight":"100",
"enabled_status":true,
"custom_field_values":[{
"field_type": "1",
"text_value": {
"default_value": "张三",
"i18n_value": {
"zh_cn": "中文",
"ja_jp": "ja_jp_name",
"en_us": "en_us_name"
}
},
"url_value": {
"link_text": {
"default_value": "张三",
"i18n_value": {
"zh_cn": "中文",
"ja_jp": "ja_jp_name",
"en_us": "en_us_name"
}
},
"url": "https://m.bytedance.com/afnasjfna",
"pcurl": "http://www.fs.cn"
},
"enum_value": {
"enum_ids": [
"1"
],
"enum_type": "1"
},
"user_values": [
{
"ids": [
"1"
]
}
],
"phone_value": {
"phone_number": "18812345678",
"extension_number": "234234234"
},
"field_key": "C-1000001"
}]}}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
响应体示例
json
{
"code": 0,
"msg": "success",
"data": {}
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 400 | 2221305 | Request parameter error | 请求参数错误，具体参照错误信息。 |
| 400 | 2221306 | ExternalID repeat | 租户内自定义ID重复，请更换自定义ID后重新尝试。 |
| 400 | 2221307 | Exceed department limit | 部门数量超限，请减少部门数量至限制内后重新尝试。 |
| 400 | 2221309 | Department does not exist | 更新部门不存在、父部门不存在 |
| 400 | 2221311 | Internationalized name duplication | 多语言名称和现存部门重复，请修改多语言名称为未使用的名称后重新尝试。 |
| 400 | 2221312 | Exceed department level depth | 部门层级过深，部门层级上限为25，请将部门层级调整至25级以内。 |
| 400 | 2221313 | ExternalID invalid | 自定义id长度不可超过 64 个字符，请将自定义id长度调整至64个字符以内。 |
| 400 | 2221317 | Department direct sub departments exceed limits | 部门直属子部门数上限为1000，请将部门直属子部门数调整至1000以内。 |
| 400 | 2221319 | Department name duplicate when creating and updating | 创建和更新时，部门名重复，XX（部门名字）已存在，请使用其他名称 |
| 400 | 2221328 | Description invalid | 默认值或多语言值超过100字，请检查默认值和多语言值。 |
| 400 | 2221329 | Department type invalid | 非法部门类型，请使用合法的部门类型后重新尝试。 |
| 400 | 2221330 | HRBP invalid | HRBP为非同一租户的未离职、未冻结雇员，请确定HRBP为同一租户的未离职、未冻结雇员后重新尝试 |
| 400 | 2221331 | Custom field value invalid | 自定义字段值不合法，具体参照错误信息 |
| 400 | 2221332 | Department has members, can not delete department | 部门下还有在职、待入职雇员，不能删除部门，请先移除部门下的在职、待入职雇员，再删除部门。 |
| 400 | 2221333 | Department name can not contain '/' | 部门名称不能包含"/" |
| 400 | 2221334 | Department ID duplicate | 部门ID已被使用，请更换部门ID后重新尝试。 |
| 400 | 2224001 | No permission to operate | 无接口权限，请为应用申请接口权限后重新尝试，具体操作参见相关文档。 |
| 400 | 2224002 | No permission to operate record | 没有行记录权限，请联系管理员授予行记录权限后重新尝试。 |
| 400 | 2224003 | No permission to operate dependent object | 没有依赖对象权限，请为应用申请依赖对象权限后重新尝试，具体操作参见相关文档。 |
| 400 | 2221349 | Department has member, can not disable department | 部门下还有成员，无法停用，请先移除部门下的成员，再停用部门。 |
| 400 | 2221350 | Department has child, can not disable department | 部门下还有子部门，无法停用，请先移除部门下的子部门，再停用部门。 |
| 400 | 2221351 | Department parent is disabled, can not enable | 该部门的父部门已停用，无法启用该部门，请先启用父部门，再启用该部门。 |
| 400 | 2221352 | Department parent is disabled | 该部门的父部门为停用，无法进行相关操作，请启用父部门后重新尝试。 |