跳到主要内容

获取企业部门信息列表

1. 接口描述

接口请求域名: ess.tencentcloudapi.com 。

此接口(DescribeIntegrationDepartments)用于查询企业的部门信息列表,支持查询单个部门节点或单个部门节点及一级子节点部门列表。

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称必选类型描述
ActionString公共参数,本接口取值:DescribeIntegrationDepartments。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息。
注: 在调用此接口时,请确保指定的员工已获得组织架构管理权限,并具备接口传入的相应资源的数据权限。
QueryTypeInteger查询类型,支持以下类型:
  • 0:查询单个部门节点列表,不包含子节点部门信息
  • 1:查询单个部门节点级一级子节点部门信息列表
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
DeptIdString查询的部门ID。
注:如果同时指定了DeptId与DeptOpenId参数,系统将优先使用DeptId参数进行查询。当二者都未指定时,系统将返回根节点部门数据。
DeptOpenIdString查询的客户系统部门ID。
注:如果同时指定了DeptId与DeptOpenId参数,系统将优先使用DeptId参数进行查询。当二者都未指定时,系统将返回根节点部门数据。

3. 输出参数

参数名称类型描述
DepartmentsArray of IntegrationDepartment部门信息列表。部门信息根据部门排序号OrderNo降序排列,根据部门创建时间升序排列。
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 查询单个部门信息

适用于需要查询指定部门信息,且不需要子部门信息的场景。

  1. 设置查询类型QueryType为0表示查询单个部门节点;
  2. 设置DeptId表示通过部门ID查询相关部门信息。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUcX******XQZDRuD"
},
"QueryType": 0,
"DeptId": "yDwgIUUckp1g******E8xOm12b9"
}

输出示例

{
"Response": {
"Departments": [
{
"DeptId": "yDwgIUUckp1g*****E8xOm12b9",
"DeptName": "测试企业",
"DeptOpenId": "open_dept1",
"OrderNo": 2,
"ParentDeptId": "yDwgIUUckp1g******E8xOm1221"
}
],
"RequestId": "s168603******44722"
}
}

示例2 错误示例-部门查询类型不存在

设置了非法的部门查询类型QueryType,查询失败。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUcX******XQZDRuD"
},
"QueryType": 2
}

输出示例

{
"Response": {
"Error": {
"Code": "InvalidParameter.ParamError",
"Message": "部门查询类型不存在,请核对参数"
},
"RequestId": "s168603******44722"
}
}

示例3 查询当前部门和一级子部门信息

适用于需要查询指定部门及其一级子部门信息的场景。

  1. 设置查询类型QueryType为1表示查询部门节点及一级子部门节点;
  2. 设置DeptId表示通过部门ID查询相关部门信息。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUc********QZDRuD"
},
"QueryType": 1,
"DeptId": "yDwgIUUckp1g******E8xOm12b9"
}

输出示例

{
"Response": {
"Departments": [
{
"DeptId": "yDwgIUUckp1g********E8xOm12b9",
"DeptName": "测试企业",
"DeptOpenId": "open_dept1",
"OrderNo": 2,
"ParentDeptId": "yDwgIUUckp1g********E8xOm1221"
},
{
"DeptId": "yDwgIUUckp1g********E8xOm5679",
"DeptName": "子部门 1",
"DeptOpenId": "open_dept_12",
"OrderNo": 3,
"ParentDeptId": "yDwgIUUckp1g*******E8xOm12b9"
},
{
"DeptId": "yDwgIU2331g********E8xOm12n9",
"DeptName": "测试部门 2",
"DeptOpenId": "open_dept_13",
"OrderNo": 2,
"ParentDeptId": "yDwgIUUckp1g********E8xOm12b9"
}
],
"RequestId": "s168603******44722"
}
}

示例4 查询部门信息(根据客户系统部门ID)

适用于调用方已获取客户系统部门ID的场景。通过设置DeptOpenId参数查询部门信息。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUcX******XQZDRuD"
},
"QueryType": 0,
"DeptOpenId": "open_dept1"
}

输出示例

{
"Response": {
"Departments": [
{
"DeptId": "yDwgIUUckp1g*****E8xOm12b9",
"DeptName": "测试企业",
"DeptOpenId": "open_dept1",
"OrderNo": 2,
"ParentDeptId": "yDwgIUUckp1g******E8xOm1221"
}
],
"RequestId": "s168603******44722"
}
}

示例5 查询部门信息(系统优先使用部门ID查询)

当调用方同时设置了部门DeptId和客户系统部门DeptOpenId时,系统优先使用DeptId查询部门信息,DeptOpenId不生效。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUcX******XQZDRuD"
},
"QueryType": 0,
"DeptId": "yDwgIUUckp1g*****E8xOm12b9",
"DeptOpenId": "open_dept2"
}

输出示例

{
"Response": {
"Departments": [
{
"DeptId": "yDwgIUUckp1g*****E8xOm12b9",
"DeptName": "测试企业",
"DeptOpenId": "open_dept1",
"OrderNo": 2,
"ParentDeptId": "yDwgIUUckp1g******E8xOm1221"
}
],
"RequestId": "s168603******44722"
}
}

示例6 查询部门信息(系统默认返回根部门节点信息)

当部门DeptId和客户系统部门DeptOpenId都未设置时,系统默认返回根部门节点信息。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationDepartments
<公共请求参数>

{
"Operator": {
"UserId": "yDwgKUUcX******XQZDRuD"
},
"QueryType": 0
}

输出示例

{
"Response": {
"Departments": [
{
"DeptId": "yDwgIUUckp1g*****E8xOm12b9",
"DeptName": "测试企业",
"DeptOpenId": "open_dept1",
"OrderNo": 0,
"ParentDeptId": "0"
}
],
"RequestId": "s168603******44722"
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
FailedOperation操作失败。
InvalidParameter.DataNotFound数据不存在。
InvalidParameter.ParamError参数错误。
OperationDenied操作被拒绝。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062