# 更新部门
本接口用于更新部门信息。仅更新显式传参的部分。
**注意事项**：- 只能在当前应用的通讯录授权范围内（可通过管理后台>应用权限>通讯录授权页面查看）更新部门信息。
- 变更部门的父部门，需要有变更前后的部门权限，才能变更成功。
- 变更部门的负责人，需要有变更前后的人员权限，才能变更成功。
- 本接口中支持的user_access_token 默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可更新部门时，管理员管理范围取最大集。管理员权限可查看帮助中心文档： [管理员创建管理员角色及分配权限](https://www.feishu.cn/hc/zh-CN/articles/360043495213-%E7%AE%A1%E7%90%86%E5%91%98%E5%88%9B%E5%BB%BA%E7%AE%A1%E7%90%86%E5%91%98%E8%A7%92%E8%89%B2%E5%8F%8A%E5%88%86%E9%85%8D%E6%9D%83%E9%99%90#tabs0|lineguid-dU31C)
- 修改部门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 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 更新部门(directory:department.update:write)
创建、更新、删除部门(directory:department:write)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
查看员工自定义 ID(directory:employee.base.external_id:read)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
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](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- employee_id：企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。
获取employee_id的方式：
- 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID
- 通过 [批量获取员工列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/directory-v1/employee/filter) 的接口，通过手机号或邮箱查询员工ID。
**默认值**：`open_id`
**当值为 `employee_id`，字段权限要求**：
查看员工自定义 ID(directory:employee.base.external_id:read)
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 | 该部门的父部门为停用，无法进行相关操作，请启用父部门后重新尝试。