获取企业部门信息列表
1. 接口描述
接口请求域名： ess.tencentcloudapi.com 。
此接口（DescribeIntegrationDepartments）用于查询企业的部门信息列表，支持查询单个部门节点或单个部门节点及一级子节点部门列表。
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：DescribeIntegrationDepartments。 |
| Version | 是 | String | 公共参数，本接口取值：2020-11-11。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| Operator | 是 | UserInfo | 执行本接口操作的员工信息。 注: 在调用此接口时，请确保指定的员工已获得组织架构管理权限，并具备接口传入的相应资源的数据权限。 |
| QueryType | 是 | Integer | 查询类型，支持以下类型：
|
| Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。 |
| DeptId | 否 | String | 查询的部门ID。 注： 如果同时指定了DeptId与DeptOpenId参数，系统将优先使用DeptId参数进行查询。当二者都未指定时，系统将返回根节点部门数据。 |
| DeptOpenId | 否 | String | 查询的客户系统部门ID。 注： 如果同时指定了DeptId与DeptOpenId参数，系统将优先使用DeptId参数进行查询。当二者都未指定时，系统将返回根节点部门数据。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| Departments | Array of IntegrationDepartment | 部门信息列表。部门信息根据部门排序号OrderNo降序排列，根据部门创建时间升序排列。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 查询单个部门信息
适用于需要查询指定部门信息，且不需要子部门信息的场景。
- 设置查询类型QueryType为0表示查询单个部门节点；
- 设置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 查询当前部门和一级子部门信息
适用于需要查询指定部门及其一级子部门信息的场景。
- 设置查询类型QueryType为1表示查询部门节点及一级子部门节点；
- 设置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 | 操作被拒绝。 |