# 查询编制规划明细信息（支持自定义组织）

查询编制规划明细，包括维度信息、编制数、预估在职人数、在职人数和预增/预减人数。
**注意事项**：该接口会按照应用拥有的「部门数据」的权限范围返回数据，请确定在「开发者后台 - 权限管理 - 数据权限」中有申请「部门资源」权限范围
- 本接口可查询编制规划或集中填报明细信息。
- 请求体入参如果没有特殊说明，不填写默认为空，不参与筛选。
- 所有筛选项可一起使用，之间为 AND 关系。如部门 + 人员类型，则返回同时满足部门及人员类型的编制规划明细数据。
**注意事项**：延迟说明：搜索同步延迟 10s 以内，即：直接创建编制明细后 10s 内调用此接口可能查询不到数据。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/corehr/v2/workforce_plan_details/batch_v2
HTTP Method | POST
接口频率限制 | [5 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查看编制规划明细信息(corehr:workforce_detail:read)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 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"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果<br>**示例值**：["123456"]
page_size | int | 否 | 分页大小<br>**示例值**：100<br>**默认值**：`100`<br>**数据校验规则**：<br>- 取值范围：`1` ～ `100`

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
workforce_plan_id | string | 否 | 编制规划方案ID，ID及详细信息可通过[获取编制规划方案列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/workforce_plan/list)接口查询获得。查询编制规划明细信息时，编制规划方案ID必填，是否为集中填报项目设置为false，不填写集中填报项目ID（是否填写不影响返回结果）<br>**示例值**："781234834512"
is_centralized_reporting_project | boolean | 否 | 是否为集中填报项目。如果租户未使用集中填报功能，将此参数置空即可。如果查询集中填报明细，将此参数设置为true。<br>**字段权限要求**：获取编制规划集中填报明细信息(corehr:workforce_plan_centralized_reporting_project_detail:read)<br>**示例值**：false<br>**默认值**：`false`
centralized_reporting_project_id | string | 否 | 编制规划集中填报项目ID，ID可通过访问集中填报页面，从URL中提取report_id参数。如果租户未使用集中填报功能，将此参数置空即可。查询集中填报信息时，集中填报项目ID必填，是否为集中填报项目设置为true，不填写编制规划方案ID（是否填写不影响返回结果）<br>**字段权限要求**：获取编制规划集中填报明细信息(corehr:workforce_plan_centralized_reporting_project_detail:read)<br>**示例值**："7140964208476371111"
dimension_id_in_datas | dimension_id_in_data\[\] | 否 | 维度筛选<br>**数据校验规则**：<br>- 长度范围：`0` ～ `100`
dimension_key | string | 否 | 维度key，可从下面列表中进行选择：<br>- "department"：部门。<br>- "employee_type" ：人员类型。<br>- "location"：地点。<br>- "position" ：岗位。<br>- "cost_center" ：成本中心/业务线。<br>- "job_family" ：序列。<br>- "job_level" ：职级。<br>- "job" ：职务。<br>- "pathway"：通道。<br>自定义组织：<br>- "custom_org_01" <br>- "custom_org_02"<br>- "custom_org_03"<br>- "custom_org_04" <br>- "custom_org_05"<br>**示例值**："department"
dimension_ids | string\[\] | 否 | 维度value。<br>- department_id：可从[查询部门](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/department/batch_get)获得。<br>- location_id：可从[查询地点](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/location/list)获得。<br>- cost_center_id：可从[查询成本中心](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/cost_center/search)获得。<br>- job_id：可从[查询职务](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/job/list)获得。<br>- job_level_id：可从[查询职级](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_level/list)获得。<br>- job_family_id：可从[查询序列](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_family/list)获得。<br>- employee_type_id：可从[查询人员类型](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/employee_type/list)获得。<br>- position_id：可从[查询岗位](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/position/query)获得。<br>-  pathway_id: 可从[查询通道](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/pathway/batch_get)获得。<br>- custom_org_01_id：可从[查询自定义组织](https://open.feishu.cn/document/corehr-v1/organization-management/custom_org/query)获得。<br>- custom_org_02_id：可从[查询自定义组织](https://open.feishu.cn/document/corehr-v1/organization-management/custom_org/query)获得。<br>- custom_org_03_id：可从[查询自定义组织](https://open.feishu.cn/document/corehr-v1/organization-management/custom_org/query)获得。<br>- custom_org_04_id：可从[查询自定义组织](https://open.feishu.cn/document/corehr-v1/organization-management/custom_org/query)获得。<br>- custom_org_05_id：可从[查询自定义组织](https://open.feishu.cn/document/corehr-v1/organization-management/custom_org/query)获得。<br>**示例值**：["7210266650427033132"]<br>**数据校验规则**：<br>- 长度范围：`0` ～ `1000`
include_missing_dimension_rows | boolean | 否 | 是否包含缺维度的明细行数据，true为包含缺维度明细行数据，false为仅获取所有维度都有值的明细行数据，默认为 false<br>**示例值**：false
filter_all_zero_value_rows | boolean | 否 | 是否过滤在职、预增/预减人员、编制数、预估在职人数都为0的明细行，true为过滤在职、预增/预减人员、编制数、预估在职人数都为0的明细行，false为不过滤在职、预增/预减人员、编制数、预估在职人数都为0的明细行，默认为 false<br>**示例值**：false

### 请求体示例
```json
{
    "workforce_plan_id": "781234834512",
    "is_centralized_reporting_project": false,
    "centralized_reporting_project_id": "7140964208476371111",
    "dimension_id_in_datas": [
        {
            "dimension_key": "department",
            "dimension_ids": [
                "7210266650427033132"
            ]
        }
    ],
    "include_missing_dimension_rows": false,
    "filter_all_zero_value_rows": false
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
workforce_plan_id | string | 编制规划方案 ID
centralized_reporting_project_id | string | 集中填报项目 ID
items | workforce_plan_detail_v2\[\] | 编制规划明细信息
workforce_plan_detail_id | string | 编制规划明细 ID
dimension_info_datas | dimension_info_data\[\] | 维度信息
dimension_key | string | 维度 key<br>- "department"：部门。<br>- "employee_type" ：人员类型。<br>- "location"：地点。<br>- "position" ：岗位。<br>- "cost_center" ：成本中心/业务线。<br>- "job_family" ：序列。<br>- "job_level" ：职级。<br>- "job" ：职务。<br>- "pathway"：通道。<br>自定义组织：<br>- "custom_org_01" <br>- "custom_org_02"<br>- "custom_org_03"<br>- "custom_org_04" <br>- "custom_org_05"
dimension_info | dimension_info | 维度信息
id | string | 维度id<br>- department_id：可从[查询部门](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/department/batch_get)获得。<br>- location_id：可从[查询地点](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/location/list)获得。<br>- cost_center_id：可从[查询成本中心](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/cost_center/search)获得。<br>- job_id：可从[查询职务](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/job/list)获得。<br>- job_level_id：可从[查询职级](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_level/list)获得。<br>- job_family_id：可从[查询序列](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/job_family/list)获得。<br>- employee_type_id：可从[查询人员类型](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/employee_type/list)获得。<br>- position_id：可从[查询岗位](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/position/query)获得。<br>-  pathway_id: 可从[查询通道](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/pathway/batch_get)获得。<br>- custom_org_01_id：自定义组织，功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)<br>- custom_org_02_id：自定义组织，功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)<br>- custom_org_03_id：自定义组织，功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)<br>- custom_org_04_id：自定义组织，功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)<br>- custom_org_05_id：自定义组织，功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
name | i18n\[\] | 维度名称
lang | string | 语言编码（IETF BCP 47）
value | string | 文本内容
workforce_plan | string | 编制规划值
active_individuals | string | 在职人数
individuals_to_be_added | string | 预增员数量
individuals_to_be_removed | string | 预减员数量
estimated_active_individuals_details | workforce_plan_eai_detail\[\] | 预估在职人数明细
date | string | 预估月份
estimated_active_individuals | string | 预估在职人数
multi_period_values | workforce_plan_multi_period_value\[\] | 自然周期的编制规划信息。功能灰度中，有需要请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
period_date | string | 自然周期的最后一天
workforce_plan | string | 对应自然周期的编制规划值
individuals_to_be_added | string | 对应自然周期的预增员数量
individuals_to_be_removed | string | 对应自然周期的预减员数量
is_missing_dimension | boolean | 是否为缺维度的明细行，true为缺维度明细行，false为非缺维度明细行
is_all_zero_value | boolean | 是否在职、预增/预减人员、编制数、预估在职人数都为0的明细行，true代表在职、预增/预减人员、编制数、预估在职人数都为0的明细行，false代表在职、预增/预减人员、编制数、预估在职人数不全为0的明细行
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
has_more | boolean | 是否还有更多项

### 响应体示例
```json
{"code":0,
"msg":"success",
"data":{"workforce_plan_id":"7128319234123",
"centralized_reporting_project_id":"7128319234123",
"items":[{"workforce_plan_detail_id":""123456"",
"dimension_info_datas":[{"dimension_key":""department"",
"dimension_info":{"id":"“123456”",
"name":[{
    "lang": "zh-CN",
    "value": "中文示例"
}]}}],
"workforce_plan":"10.00",
"active_individuals":"10.00",
"individuals_to_be_added":"10.00",
"individuals_to_be_removed":"10.00",
"estimated_active_individuals_details":[{
    "date": "“2020-10-31”",
    "estimated_active_individuals": "“10.00”"
}],
"multi_period_values":[{
    "period_date": "2022-10-31",
    "workforce_plan": "12.00",
    "individuals_to_be_added": "10.00",
    "individuals_to_be_removed": "10.00"
}],
"is_missing_dimension":false,
"is_all_zero_value":false}],
"page_token":"34523459",
"has_more":true}}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
503 | 1161204 | Requset timeout | 请求超时，请稍后重试。如无法解决可[飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW)。
429 | 1161604 | QPS over limit | 请求量过大，请稍后访问。如无法解决可联系 [飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW) 。
400 | 1160109 | param is invalid | 请检查是否传入了无效参数。如无法解决可联系[飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW)。
400 | 1161009 | programme not found | 请检查是否传入了无效编制规划方案信息。如无法解决可联系[飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW)。
403 | 1160100 | no permission | 请检查是否申请对应权限。如无法解决可联系[飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW)。
400 | 1161008 | lack APP ID | 系统错误。如无法解决可联系 [飞书开放平台技术支持](https://applink.feishu.cn/TLJpeNdW)。