飞书开放平台 Server API 文档

主题

根据条件批量获取职务 ​

根据传入的职务ID或职务Code批量获取当前生效版本职务信息。

Tip: - 本接口会按照「职务资源」权限范围返回数据，请确定在「开发者后台 - 权限管理 - 数据权限」中已申请此数据权限

  • 申请数据权限后须配置[职务可访问的数据范围]，否则接口无法正常查询数据。可以在「开发者后台 - 权限管理 - 可访问的数据范围」中配置。
  • 职务ID和职务Code可一起使用，之间为 AND 关系

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/jobs/batch_get
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:job.only:read 获取职务信息（仅职务） corehr:job:read 获取职务信息 corehr:job:write 读写职务信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 corehr:job.job_level:read 获取职务中的职级信息 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
user_id_typestring否用户 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？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
job_idsstring\[\]否职务 ID 列表。职务ID列表和职务 Code 列表至少有一项有值，否则接口将调用失败。
示例值：["1522315"]
数据校验规则：
- 长度范围：0 ～ 100
job_codesstring\[\]否职务 Code 列表。职务ID列表和职务 Code 列表至少有一项有值，否则接口将调用失败。
示例值：["1332715"]
数据校验规则：
- 长度范围：0 ～ 100
fieldsstring\[\]否需要查询的字段列表，默认返回id。可选以下预置字段及自定义字段： 可选值有： - "job_name"：名称 - "code"：编码 - "active"：启用状态 - "description"：描述 - "job_title"：职务头衔 - "pathway"：通道ID - "working_hours_type"：工时制度 - "job_level"：关联的职级 - "job_family"：关联的序列 - "effective_date"：当前版本生效日期 - "expiration_date"：当前版本失效日期 - "created_time"：创建时间 - "updated_time"：更新时间 - "created_by"：创建人 - "updated_by"：更新人 - "custom_fields"：自定义字段(需传入具体的"custom_api_name") 详细见获取自定义字段列表 ,比如:"shifouleixing_7795__c"
示例值：["job_name"]
数据校验规则：
- 长度范围：0 ～ 100

请求体示例 ​

json
{
    "job_ids": [
        "1522315"
    ],
    "job_codes": [
        "1332715"
    ],
    "fields": [
        "job_name"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemsjob\[\]查询的职务信息
    └ idstring职务ID
    └ codestring编码
    └ namei18n\[\]名称
      └ langstring语言信息，中文用zh-CN，英文用en-US
      └ valuestring文本内容
    └ descriptioni18n\[\]描述
      └ langstring语言信息，中文用zh-CN，英文用en-US
      └ valuestring文本内容
    └ activeboolean启用状态，true为启用，false为停用
    └ job_titlei18n\[\]职务头衔
      └ langstring语言信息，中文用zh-CN，英文用en-US
      └ valuestring文本内容
    └ pathway_idstring通道ID，详情可以参考【获取通道信息】
    └ job_family_id_liststring\[\]关联的序列ID列表 - 可通过【批量查询序列】获取详情
    └ job_level_id_liststring\[\]关联的职级ID列表 - 可通过【批量查询职级】获取详情
字段权限要求： corehr:job.job_level:read 获取职务中的职级信息
    └ working_hours_type_idstring工时制度 ID，枚举值及详细信息可通过【批量查询工时制度】接口查询获得
    └ effective_timestring当前版本生效日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00
    └ expiration_timestring当前版本失效日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00
    └ custom_fieldsobject_field_data\[\]自定义字段，格式参考：【自定义字段说明】岗位、职务、自定义组织模块
      └ field_namestring字段名
      └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(123, 123.23, true, ["id1","id2], 2006-01-02 15:04:05])
    └ created_bystring创建人，详细信息可通过【搜索员工信息】 或 【批量查询员工】接口获取
    └ created_timestring当前版本创建日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00
    └ updated_bystring更新人，详细信息可通过【搜索员工信息】 或 【批量查询员工】接口获取
    └ updated_timestring当前版本更新日期 - 返回格式：YYYY-MM-DD 00:00:00（最小单位到日） - 日期范围:1900-01-01 00:00:00～9999-12-31 00:00:00

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "id": "4698040628992333549",
                "code": "JP422119",
                "name": [
                    {
                        "lang": "zh-CN",
                        "value": "高级 Java 开发工程师"
                    }
                ],
                "description": [
                    {
                        "lang": "zh-CN",
                        "value": "负责公司核心业务系统的 Java 后端开发，参与架构设计与技术选型，解决复杂技术难题，指导初级开发工程师开展工作"
                    }
                ],
                "active": true,
                "job_title": [
                    {
                        "lang": "zh-CN",
                        "value": "高级工程师"
                    }
                ],
                "pathway_id": "4719519211875096301",
                "job_family_id_list": [
                    "4719519211875096301"
                ],
                "job_level_id_list": [
                    "4719519212005299950"
                ],
                "working_hours_type_id": "6890452208593372679",
                "effective_time": "2020-01-01 00:00:00",
                "expiration_time": "2021-01-01 00:00:00",
                "custom_fields": [
                    {
                        "field_name": "name",
                        "value": "Sandy"
                    }
                ],
                "created_by": "4719519211875096301",
                "created_time": "2021-01-01 00:00:00",
                "updated_by": "2415132452875096301",
                "updated_time": "2021-01-01 00:00:00"
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5031161204Interface timeout接口超时，可尝试重试。如果无法解决可以联系飞书人事 Oncall
4291161604Interface rate limited接口请求次数超过接口频率限制，可尝试降低请求频率

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

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