修改部门部分信息

调用该接口更新指定部门的部分信息，包括名称、父部门、排序以及负责人等。

注意事项

调用该接口更新部门信息时，所涉及的所有部门需要在应用的通讯录权限范围内，否则会调用失败，并报无权限错误。了解权限范围，参见权限范围资源介绍。
本接口不是全量更新接口，如果某一请求参数不传值，则默认不会修改对应的部门信息（注意：leaders、department_hrbps 如果传入空数组，则会把原有值清空）。如果你需要使用全量更新接口，可参见更新部门所有信息。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/departments/:department_id
HTTP Method	PATCH
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用	`contact:contact` 更新通讯录
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:department.base:readonly` 获取部门基础信息 `contact:user.employee_id:readonly` 获取用户 user ID `contact:department.hrbp:readonly` 查询部门 HRBP 信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录

请求头

名称	类型	必填	描述
Authorization	string	是	`tenant_access_token` 值格式："Bearer `access_token`" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
`department_id`	`string`	部门 ID，ID 类型需要与查询参数 department_id_type 的取值保持一致。ID 获取方式说明： - 调用创建部门接口后，可从返回结果中获取到部门 ID 信息。 - 部门 API 提供了多种获取其他部门 ID 的方式，如获取子部门列表、获取父部门信息、搜索部门，你可以选择合适的 API 进行查询。示例值："D096" 数据校验规则： - 最大长度：`64` 字符 - 正则校验：`^[a-zA-Z0-9][a-zA-Z0-9_\-@.]{0,63}$`

查询参数

名称	类型	必填	描述
`user_id_type`	`string`	否	用户 ID 类型示例值：open_id 可选值有： - `open_id`: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - `union_id`: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - `user_id`: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？默认值：`open_id` 当值为 `user_id`，字段权限要求： `contact:user.employee_id:readonly` 获取用户 user ID
`department_id_type`	`string`	否	此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。示例值：open_department_id 可选值有： - `department_id`: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - `open_department_id`: 由系统自动生成的部门 ID，ID 前缀固定为 `od-`，在租户内全局唯一。默认值：`open_department_id`

请求体

名称	类型	必填	描述
`name`	`string`	否	部门名称。注意： - 不可包含斜杠（`/`）。 - 不能与存量部门名称重复。默认值：空，表示不修改。示例值："DemoName" 数据校验规则： - 最小长度：`1` 字符
`i18n_name`	`department_i18n_name`	否	部门名称的国际化配置。注意： - 不可包含斜杠（`/`）。 - 不能与存量部门名称的国际化配置重复。默认值：空，表示不修改。
└ `zh_cn`	`string`	否	部门的中文名。示例值："Demo名称"
└ `ja_jp`	`string`	否	部门的日文名。示例值："デモ名"
└ `en_us`	`string`	否	部门的英文名。示例值："Demo Name"
`parent_department_id`	`string`	否	父部门的 ID。部门 ID 获取方式： - 如果需要将部门的父部门设置为根部门，则该参数取值 `0`。 - 你可以调用搜索部门接口获取所需的部门 ID。默认值：空，表示不修改。示例值："D067"
`leader_user_id`	`string`	否	部门主管的用户 ID。ID 类型与查询参数 user_id_type 的取值保持一致。用户 ID 获取方式可参见如何获取不同的用户 ID。注意：部门主管（leader_user_id）和部门主负责人（leaderType 取值为 1 所对应的 leaderID）取值始终一致。因此： - 如果同时设置了部门主负责人（leaderType 取值为 1 所对应的 leaderID），则此处设置的部门主管必须与部门主负责人为同一个人。 - 仅修改部门主管，会同步修改部门主负责人（leaderType 取值为 1 所对应的 leaderID）。默认值：空，表示不修改。示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
`order`	`string`	否	部门的排序，即部门在其同级部门的展示顺序。取值格式为 String 类型的非负整数，数值越小，排序越靠前。注意：order 值唯一，即传入的值不能与存量部门的 order 值重复。默认值：空，表示不修改。示例值："100"
`create_group_chat`	`boolean`	否	是否创建部门群。可选值有： - true：创建。 - false：不创建。如果之前已创建了部门群，则即便设置为 false 群也会继续存在。说明：创建部门群时，群名默认为部门名，群主默认为部门主负责人。默认值：空，表示不修改。示例值：false
`leaders`	`departmentLeader\[\]`	否	部门负责人信息。注意： - leaders 如果传空数组，则会把原有值清空。 - 配置该参数时，必须指定一名主负责人。 - 设置多名负责人时，仅支持将某一负责人设置为主负责人。 - 部门主管（leader_user_id）和部门主负责人（leaderType 取值为 1 所对应的 leaderID）取值始终一致。因此： - 如果同时设置了部门主管（leader_user_id），则此处设置的部门主负责人必须与部门主管为同一个人。 - 仅修改部门主负责人，会同步修改部门主管（leader_user_id）。
└ `leaderType`	`int`	是	负责人类型。示例值：1 可选值有： - `1`: 主负责人 - `2`: 副负责人
└ `leaderID`	`string`	是	负责人的用户 ID，ID 类型与查询参数 user_id_type 的取值保持一致。用户 ID 获取方式可参见如何获取不同的用户 ID。示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
`group_chat_employee_types`	`int\[\]`	否	部门群的人员类型限制。人员类型的取值范围如下。该参数支持设置多个类型值，若有多个，用英文 `,` 分隔： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问该参数支持传入自定义人员类型对应的编号。你可以调用查询人员类型接口获取相应编号（enum_value）。默认值：空示例值：[1]
`department_hrbps`	`string\[\]`	否	部门 HRBP 的用户 ID 列表。 ID 类型与查询参数 user_id_type 的取值保持一致。用户 ID 获取方式可参见如何获取不同的用户 ID。注意：department_hrbps 如果传空数组，则会把原有值清空。示例值：["ou_7dab8a3d3cdcc9da365777c7ad535d62"] 数据校验规则： - 最大长度：`500`

请求体示例

json

{
    "name": "DemoName",
    "i18n_name": {
        "zh_cn": "Demo名称",
        "ja_jp": "デモ名",
        "en_us": "Demo Name"
    },
    "parent_department_id": "D067",
    "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "order": "100",
    "create_group_chat": false,
    "leaders": [
        {
            "leaderType": 1,
            "leaderID": "ou_7dab8a3d3cdcc9da365777c7ad535d62"
        }
    ],
    "group_chat_employee_types": [
        1
    ],
    "department_hrbps": [
        "ou_7dab8a3d3cdcc9da365777c7ad535d62"
    ]
}

Go 请求示例

import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewPatchDepartmentReqBuilder().
		DepartmentId(`D096`).
		Department(larkcontact.NewDepartmentBuilder().
			Name(`DemoName`).
			I18nName(larkcontact.NewDepartmentI18nNameBuilder().
				ZhCn(`Demo名称`).
				EnUs(`Demo Name`).
				Build()).
			ParentDepartmentId(`D067`).
			Build()).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Patch(context.Background(), req)
}

Java 请求示例

java

import com.lark.oapi.Client;
import com.lark.oapi.service.contact.v3.model.*;
import com.lark.oapi.core.request.RequestOptions;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        PatchDepartmentReq req = PatchDepartmentReq.newBuilder()
                .departmentId("D096")
                .department(Department.newBuilder()
                        .name("DemoName")
                        .i18nName(DepartmentI18nName.newBuilder()
                                .zhCn("Demo名称")
                                .enUs("Demo Name")
                                .build())
                        .parentDepartmentId("D067")
                        .build())
                .build();

        // 发起请求
        PatchDepartmentResp resp = client.contact().department().patch(req, RequestOptions.newBuilder().build());
    }
}

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `department`	`department`	部门信息。
└ `name`	`string`	部门名称。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `i18n_name`	`department_i18n_name`	部门名称的国际化配置。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `zh_cn`	`string`	部门的中文名。
└ `ja_jp`	`string`	部门的日文名。
└ `en_us`	`string`	部门的英文名。
└ `parent_department_id`	`string`	父部门的部门 ID。 - ID 类型与查询参数的 department_id_type 取值保持一致。 - 当父部门为根部门时，该参数值为 `0`。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `department_id`	`string`	自定义部门 ID。后续可以使用该 ID 删除、修改、查询部门信息。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `open_department_id`	`string`	部门的 open_department_id，由系统自动生成。后续可以使用该 ID 删除、修改、查询部门信息。
└ `leader_user_id`	`string`	部门主管的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `chat_id`	`string`	部门群的群 ID。后续可以使用获取群信息，获取群的详细信息。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `order`	`string`	部门的排序，即部门在其同级部门的展示顺序。取值越小排序越靠前。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `unit_ids`	`string\[\]`	部门绑定的单位自定义 ID 列表，当前只支持一个。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `member_count`	`int`	当前部门及其下属部门的用户（包含部门负责人）个数。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `status`	`department_status`	部门状态。字段权限要求（满足任一）： `contact:department.base:readonly` 获取部门基础信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `is_deleted`	`boolean`	是否被删除。可能值有： - true：是 - false：否
└ `leaders`	`departmentLeader\[\]`	部门负责人信息。
└ `leaderType`	`int`	负责人类型。可选值有： - `1`: 主负责人 - `2`: 副负责人
└ `leaderID`	`string`	负责人的用户 ID，ID 类型与查询参数的 user_id_type 取值保持一致。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录
└ `group_chat_employee_types`	`int\[\]`	部门群的人员类型限制。人员类型的可能值如下： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问如果是自定义人员类型，则会返回对应的编号。你可以调用查询人员类型接口，获取相应编号（enum_value）对应的自定义人员类型信息。
└ `department_hrbps`	`string\[\]`	部门 HRBP 的用户 ID 列表。 ID 类型与查询参数 user_id_type 的取值保持一致。字段权限要求： `contact:department.hrbp:readonly` 查询部门 HRBP 信息
└ `primary_member_count`	`int`	当前部门及其下属部门的主属成员（即成员的主部门为当前部门）的数量。字段权限要求（满足任一）： `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:contact:access_as_app` 以应用身份访问通讯录 `contact:contact:readonly` 读取通讯录 `contact:contact:readonly_as_app` 以应用身份读取通讯录

响应体示例

json

{
    "code":0,
    "msg":"success",
    "data":{
        "department":{
            "name":"DemoName",
            "i18n_name":{
                "zh_cn":"Demo名称",
                "ja_jp":"デモ名",
                "en_us":"Demo Name"
            },
            "parent_department_id":"D067",
            "department_id":"D096",
            "open_department_id":"od-4e6ac4d14bcd5071a37a39de902c7141",
            "leader_user_id":"ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "chat_id":"oc_5ad11d72b830411d72b836c20",
            "order":"100",
            "unit_ids":[
                "custom_unit_id"
            ],
            "member_count":100,
            "status":{
                "is_deleted":false
            },
            "leaders":[
                {
                    "leaderID":"ou_357368f98775f04bea02afc6b1d33478",
                    "leaderType":1
                }
            ],
            "department_hrbps":[
                "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "ou_7dab8a3d3cdcc9da365777c7ad535d63"
            ]
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	43005	duplicate order error	order 取值重复。部门的 order 参数值必须唯一，不能与存量部门的 order 值相同，你可以更新 order 取值后重试。
400	40002	process root dept error	不支持对根部门进行操作。请检查是否在请求参数部门 ID 中传入了根部门 ID `0`。
400	40003	internal error	内部错误，请获取请求的 X-Request-Id，并向技术支持进行反馈。
403	40004	no dept authority error	当前操作涉及的部门，需在应用通讯录权限范围中，了解更多可参见权限范围资源介绍。
400	40008	dept Info is null error	部门的信息不能为空。
403	40014	no parent dept authority error	没有父部门权限。传入的父部门需要在应用的通讯录权限范围内。如何设置通讯录权限范围，参见权限范围资源介绍。
401	42008	tenant id is invalid error	租户身份无效。请求时，请求头 Authorization 对应的租户身份，需要是当前操作中的资源的所属租户。
400	43016	leaders is repeat	部门负责人重复。请检查传入的部门负责人是否有误。
400	43017	relate dept over limit	指定的单位已关联 1000 个部门，无法继续关联部门。如果必须将当前部门关联至该单位，请先调用解除部门与单位的绑定关系接口，将该单位中其他某一部门解除绑定关系，然后重试。
400	43018	duplicate i18n name	部门名称的国际化配置重复。你需要修改 i18n_name 参数配置后重试。
400	43019	exceed dept max level	部门层级深度已达到 25 层，不能继续创建子部门。
400	43021	department chat not exist	部门群不存在。
400	43022	department name duplicate	部门名重复。你需要修改传入的 name 参数值，并重试。
400	43023	dept structure no permissione	没有部门权限。部门需要在应用的通讯录权限范围内。如何设置通讯录权限范围，参见权限范围资源介绍。
400	43024	dept structure tenant lock fail	部门结构变动获取租户锁失败。由并发请求产生的冲突，请稍后重试。
400	43025	top department leader unjoined	用户未加入，不能成为部门负责人。你需要将部门负责人修改为通讯录内包含的在职员工。
400	43026	employee type is not valid	人员类型无效。你需要参考接口文档中 group_chat_employee_types 的参数描述，设置正确的人员类型。
400	43028	invalid department hrbps	部门的 HRBP 不合法。请求时，部门 HRBP 的用户 ID 可设置多个，你需要检查设置的用户 ID 类型是否与查询参数 user_id_type 设置的类型保持一致，并检查用户 ID 取值是否正确。用户 ID 获取方式可参见如何获取不同的用户 ID。
400	43029	dept name not contain separator	部门名称不能包含斜杠（`/`）。
400	43030	update department lock error,wait some seconds and retry	并发受限，请等待几秒后重试。
400	43013	dept too many children error	子部门数量过多。部门的直属子部门数量不能超过 1000。
400	43031	Unable to edit data from external data sources	无法编辑来自外部数据源的数据。

更多错误码信息，参见通用错误码。

事件

事件

事件

事件

事件

修改部门部分信息

注意事项

请求

请求头

路径参数

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码

修改部门部分信息 ​

注意事项 ​

请求 ​

请求头 ​

路径参数 ​

查询参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

修改部门部分信息

注意事项

请求

请求头

路径参数

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码