飞书开放平台 Server API 文档

主题

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

查询编制规划明细，包括维度信息、编制数和预估在职人数

Tip: 该接口会按照应用拥有的「部门数据」的权限范围返回数据，请确定在「开发者后台 - 权限管理 - 数据权限」中有申请「部门资源」权限范围

  • 本接口可查询编制规划或集中填报明细信息。
  • 请求体入参如果没有特殊说明，不填写默认为空，不参与筛选。
  • 所有筛选项可一起使用，之间为 AND 关系。如部门 + 人员类型，则返回同时满足部门及人员类型的编制规划明细数据。
  • 本接口不支持自定义组织，如需使用自定义组织，可调用查询编制规划明细信息（支持自定义组织）。

Warning: 延迟说明：搜索同步延迟 10s 以内，即：直接创建编制明细后 10s 内调用此接口可能查询不到数据。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/workforce_plan_details/batch
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:workforce_detail:read 查看编制规划明细信息

请求头 ​

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

查询参数 ​

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

请求体 ​

名称类型必填描述
workforce_plan_idstring否编制规划方案 ID， ID及详细信息可通过获取编制规划方案列表接口查询获得。查询编制规划明细信息时，编制规划方案 ID 必填。
示例值："781234834512"
is_centralized_reporting_projectboolean否是否为集中填报项目。如果租户未使用集中填报功能，将此参数置空即可。
字段权限要求：获取编制规划集中填报明细信息(corehr:workforce_plan_centralized_reporting_project_detail:read)
示例值：false
默认值：false
centralized_reporting_project_idstring否编制规划集中填报项目 ID。ID可根据集中填报链接获取。如果租户未使用集中填报功能，将此参数置空即可。查询集中填报信息时，将以集中填报ID为准，无需填写编制规划方案 ID。
字段权限要求：获取编制规划集中填报明细信息(corehr:workforce_plan_centralized_reporting_project_detail:read)
示例值："7140964208476371111"
数据校验规则：
- 长度范围：0 ～ 1000 字符
department_idsstring\[\]否部门ID列表。ID获取方式： - 调用【创建部门】【搜索部门】等接口可以返回部门ID - 也可以通过【事件】创建部门【事件】更新部门 获取部门ID信息
示例值：["7210266650427033132"]
数据校验规则：
- 长度范围：0 ～ 1000
employee_type_idsstring\[\]否人员类型 ID 列表 - 可通过查询人员类型获取详情。
示例值：["7210608972695520812"]
数据校验规则：
- 长度范围：0 ～ 1000
work_location_idsstring\[\]否工作地点 ID 列表。ID获取方式： - 调用【创建地点】【批量分页查询地点】等接口可以返回地点ID
示例值：["7210608972695520813"]
数据校验规则：
- 长度范围：0 ～ 1000
job_family_idsstring\[\]否序列 ID 列表。ID获取方式： - 调用【新建序列】【查询租户的序列信息】等接口可以返回序列ID
示例值：["7210608972695520814"]
数据校验规则：
- 长度范围：0 ～ 1000
job_level_idsstring\[\]否职级ID。ID获取方式： - 调用【新建职级】【查询租户的职级信息】等接口可以返回职级ID
示例值：["7210608972695520815"]
数据校验规则：
- 长度范围：0 ～ 1000
job_idsstring\[\]否职务ID。ID获取方式： - 调用【创建职务】【批量查询职务】等可以返回职务ID - 也可以通过【事件】创建职务 【事件】更新职务 获取ID
示例值：["7210608972695520816"]
数据校验规则：
- 长度范围：0 ～ 1000
cost_center_idsstring\[\]否成本中心 ID 列表。ID获取方式： - 调用【创建成本中心】【搜索成本中心】等接口可以返回成本中心ID
示例值：["7210608972695520817"]
数据校验规则：
- 长度范围：0 ～ 1000
include_missing_dimension_rowsboolean否是否包含缺维度明细行数据，true为包含缺维度明细行数据，false为仅获取所有维度都有值的明细行数据，默认为 false
示例值：false

请求体示例 ​

json
{
    "workforce_plan_id": "781234834512",
    "is_centralized_reporting_project": false,
    "centralized_reporting_project_id": "7140964208476371111",
    "department_ids": [
        "7210266650427033132"
    ],
    "employee_type_ids": [
        "7210608972695520812"
    ],
    "work_location_ids": [
        "7210608972695520813"
    ],
    "job_family_ids": [
        "7210608972695520814"
    ],
    "job_level_ids": [
        "7210608972695520815"
    ],
    "job_ids": [
        "7210608972695520816"
    ],
    "cost_center_ids": [
        "7210608972695520817"
    ],
    "include_missing_dimension_rows": false
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ workforce_plan_idstring编制规划方案 ID
  └ centralized_reporting_project_idstring集中填报项目 ID
  └ itemsworkforce_plan_detail\[\]编制规划明细信息
    └ workforce_plan_detail_idstring编制规划明细 ID
    └ departmentdimension_info部门信息
      └ idstring部门ID。可通过批量查询部门V2 或者搜索部门信息 获取详情
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ employee_typedimension_info人员类型信息
      └ idstring人员类型 ID - 可通过查询人员类型获取详情。
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ work_locationdimension_info工作地点信息
      └ idstring地点ID - 可通过查询单个地点获取详情。
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ job_familydimension_info序列信息
      └ idstring序列ID - 可通过批量查询序列获取详情
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ job_leveldimension_info职级信息
      └ idstring职级ID - 可通过批量查询职级获取详情
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ jobdimension_info职务信息
      └ idstring职务 ID - 可通过查询单个职务获取详情。
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ cost_centerdimension_info成本中心信息
      └ idstring成本中心ID - 可通过搜索成本中心信息获取详情。
      └ namei18n\[\]维度名称
        └ langstring语言信息，中文是 zh-CN，英文是 en-US
        └ valuestring文本内容
    └ workforce_planstring编制规划值
    └ estimated_active_individuals_detailworkforce_plan_eai_detail\[\]预估在职人数明细
      └ datestring预估月份
      └ estimated_active_individualsstring预估在职人数
    └ is_missing_dimensionboolean是否为缺维度的明细行，true为缺维度明细行，false为非缺维度明细行
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "workforce_plan_id": "7128319234123",
        "centralized_reporting_project_id": "7128319234123",
        "items": [
            {
                "workforce_plan_detail_id": "123456",
                "department": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "employee_type": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "work_location": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "job_family": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "job_level": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "job": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "cost_center": {
                    "id": "123456",
                    "name": [
                        {
                            "lang": "zh-CN",
                            "value": "中文示例"
                        }
                    ]
                },
                "workforce_plan": "10.00",
                "estimated_active_individuals_detail": [
                    {
                        "date": "2020-10-31",
                        "estimated_active_individuals": "10.00"
                    }
                ],
                "is_missing_dimension": false
            }
        ],
        "page_token": "34523459",
        "has_more": true
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5031161204Requset timeout请求超时，请稍后重试。如无法解决可飞书开放平台技术支持。
4291161604QPS over limit请求量过大，请稍后访问。如无法解决可联系 飞书开放平台技术支持 。
4001160109param is invalid请检查是否传入了无效参数。如无法解决可联系飞书开放平台技术支持。
4031160100no permission请检查是否申请对应权限。如无法解决可联系飞书开放平台技术支持。
4001161008lack APP ID系统错误。如无法解决可联系 飞书开放平台技术支持。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有