飞书开放平台 Server API 文档

主题

批量查询员工薪资档案 ​

批量查询员工薪资档案

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/compensation/v1/archives/query
HTTP MethodPOST
接口频率限制10 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:compensation_archive_detail:read 获取基础薪酬的薪资档案信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID corehr:compensation_archive_detail.change_description:read 获取薪资档案的调薪说明 corehr:compensation_archive_detail.indicators:read 获取薪资档案的关联薪资指标 corehr:compensation_archive_detail.items:read 获取薪资档案的关联薪资项 corehr:compensation_archive_detail.plan:read 获取薪资档案的关联方案 corehr:compensation_archive_detail.salary_level:read 获取薪资档案的关联薪级薪等

请求头 ​

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

查询参数 ​

名称类型必填描述
page_sizeint是分页大小
示例值：100
默认值：100
数据校验规则：
- 取值范围：1 ～ 500
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：231432433
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: 以people_corehr_id来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
user_id_liststring\[\]是用户ID列表，获取方式可参考查询参数中的「user_id_type」字段
示例值：["7117649868058789407"]
数据校验规则：
- 长度范围：1 ～ 100
tid_liststring\[\]否档案Tid列表
示例值：["141541351"]
数据校验规则：
- 长度范围：1 ～ 100
effective_start_datestring否生效开始时间
示例值："2022-05-10"
effective_end_datestring否生效结束时间
示例值："2023-05-15"

请求体示例 ​

json
{
    "user_id_list": [
        "7117649868058789407"
    ],
    "tid_list": [
        "141541351"
    ],
    "effective_start_date": "2022-05-10",
    "effective_end_date": "2023-05-15"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemsarchive_detail\[\]档案信息列表
    └ user_idstring员工ID，返回的ID类型与查询参数中的「user_id_type」的取值一致
    └ idstring员工薪资档案ID
    └ tidstring员工薪资档案版本ID，薪资档案唯一标识
    └ plan_idstring关联薪资方案ID，详细信息可以通过批量查询薪资方案接口查询获得
字段权限要求： corehr:compensation_archive_detail.plan:read 获取薪资档案的关联方案
    └ plan_tidstring关联薪资方案版本ID，薪资方案唯一标识，详细信息可以通过批量查询薪资方案接口查询获得
字段权限要求： corehr:compensation_archive_detail.plan:read 获取薪资档案的关联方案
    └ currency_idstring档案币种ID，详细信息可以通过查询货币信息v2接口查询获得
    └ change_reason_idstring调薪原因ID，详细信息可以通过批量查询定调薪原因接口查询获得
    └ change_descriptionstring调薪说明
字段权限要求： corehr:compensation_archive_detail.change_description:read 获取薪资档案的调薪说明
    └ effective_datestring生效时间
    └ expiration_datestring失效时间
    └ salary_level_idstring薪级薪等ID
字段权限要求： corehr:compensation_archive_detail.salary_level:read 获取薪资档案的关联薪级薪等
    └ created_timestring创建时间
    └ updated_timestring更新时间
    └ archive_itemsarchive_item\[\]档案关联的薪资项
字段权限要求： corehr:compensation_archive_detail.items:read 获取薪资档案的关联薪资项
      └ item_idstring薪资项ID，详细信息可以通过批量查询薪资项接口查询获得
      └ item_resultstring档案关联薪酬项数值
      └ item_result_regularstring档案关联薪酬项转正后数值
    └ archive_indicatorsarchive_indicator\[\]档案关联的薪资指标
字段权限要求： corehr:compensation_archive_detail.indicators:read 获取薪资档案的关联薪资指标
      └ indicator_idstring薪资统计指标ID，详细信息可以通过批量查询薪资统计指标接口查询获得
      └ indicator_resultstring档案关联薪资统计指标数值
      └ indicator_result_regularstring档案关联薪资统计指标转正后数值
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "user_id": "344325234123",
                "id": "32141234412",
                "tid": "141541351",
                "plan_id": "123412433",
                "plan_tid": "213412343",
                "currency_id": "324167823",
                "change_reason_id": "321414123",
                "change_description": "长期表现优异，产出高，本次给出涨幅",
                "effective_date": "2022-10-23",
                "expiration_date": "2022-10-24",
                "salary_level_id": "12342313",
                "created_time": "2024-01-01 00:00:00",
                "updated_time": "2024-01-01 00:00:00",
                "archive_items": [
                    {
                        "item_id": "213423144",
                        "item_result": "15000",
                        "item_result_regular": "18000"
                    }
                ],
                "archive_indicators": [
                    {
                        "indicator_id": "23141423",
                        "indicator_result": "15000",
                        "indicator_result_regular": "18000"
                    }
                ]
            }
        ],
        "page_token": "1234452132",
        "has_more": true
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5002290001server error服务端异常
4002290002tenantID param invalid租户参数异常
5002290003server error下游服务调用异常
4002290004the format of start_date not match, correct example: "2024-01-01"生效开始时间不合法，正确样式："2024-01-01"
4002290005the format of end_date not match, correct example: "2024-01-01"生效结束时间不合法，正确样式："2024-01-01"
4002290006user_id_type invaliduser_id_type不合法

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

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