更新部门所有信息

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

注意事项

调用该接口更新部门信息时，所涉及的所有部门需要在应用的通讯录权限范围内，否则会调用失败，并报无权限错误。了解权限范围，参见权限范围资源介绍。
本接口是全量更新接口，没有传值的请求参数默认会被置为空值（部门排序 order 参数除外）。如果你只需要更新部门的部分信息，可参见修改部门部分信息。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/departments/:department_id
HTTP Method	PUT
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用	`contact:contact` 更新通讯录
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 `contact:department.base:readonly` 获取部门基础信息 `contact:department.organize:readonly` 获取通讯录部门组织架构信息 `contact:user.employee_id:readonly` 获取用户 user ID `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 值重复。 - 不传值表示不修改部门原有的 order 值。示例值："100"
`create_group_chat`	`boolean`	否	是否创建部门群。可选值有： - true：创建。 - false：不创建。说明： - 如果部门之前没有部门群，则取值为 true 会创建部门群，创建时，群名默认为部门名，群主默认为部门主负责人。 - 如果部门之前已创建了部门群，则该参数无论是否传值均不会影响原有部门群。示例值：false
`leaders`	`departmentLeader\[\]`	否	部门负责人信息。注意： - 配置该参数时，必须指定一名主负责人。 - 设置多名负责人时，仅支持将某一负责人设置为主负责人。 - 部门主管（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]

请求体示例

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
    ]
}

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.NewUpdateDepartmentReqBuilder().
		DepartmentId(`D096`).
		Department(larkcontact.NewDepartmentBuilder().
			Name(`DemoName`).
			ParentDepartmentId(`D067`).
			Build()).
		Build()

	// 发起请求
	resp, err := client.Contact.Department.Update(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();

        // 创建请求对象
        UpdateDepartmentReq req = UpdateDepartmentReq.newBuilder()
                .departmentId("D096")
                .department(Department.newBuilder()
                        .name("DemoName")
                        .parentDepartmentId("D067")
                        .build())
                .build();

        // 发起请求
        UpdateDepartmentResp resp = client.contact().department().update(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）对应的自定义人员类型信息。
└ `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
                }
            ],
        }
    }
}

错误码

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	部门的信息不能为空。
400	40010	chat id is invalid error	部门群 ID 格式错误。
403	40014	no parent dept authority error	没有父部门权限。传入的父部门需要在应用的通讯录权限范围内。如何设置通讯录权限范围，参见权限范围资源介绍。
401	42008	tenant id is invalid error	请检查请求租户是否为合法租户。
400	40016	dept name can not be nul error	部门名不能为空。
400	40017	parent id can not be null in updateRequest	父部门 ID 不能为空。请求时必须传入 parent_department_id 参数值。
400	40018	param error	参数错误。请检查传入的参数值是否有误。例如，是否符合参数数据类型、是否符合参数描述的要求等。
400	43004	illegal unit error	单位 ID 无效。你可以调用获取单位列表接口获取单位 ID 信息，并修改 unit_ids 参数值。
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	无法编辑来自外部数据源的数据。

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

事件

事件

事件

事件

事件

更新部门所有信息

注意事项

请求

请求头

路径参数

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码

更新部门所有信息 ​

注意事项 ​

请求 ​

请求头 ​

路径参数 ​

查询参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

更新部门所有信息

注意事项

请求

请求头

路径参数

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码