批量查询发薪明细
根据 发薪活动 ID 列表 、发薪日起止时间 和 飞书人事雇佣 ID 列表 分页查询发薪明细列表和关联的算薪明细分段数据。
Warning: 当前接口仅支持查询某些员工在特定范围内的发薪明细，若需要查询某个发薪活动下的所有发薪明细数据，请使用查询发薪活动明细列表接口。
注意事项
- 批量查询发薪明细接口提供的请求参数中，用户必须填写「发薪日起止时间（pay_period_start_date，pay_period_end_date）」或「发薪活动 ID 列表」，当传入的三个参数均为空时，开放接口将返回 2500006 错误码。
- 每一次调用接口时，系统最多会扫描 50 个发薪活动，当用户传入的查询条件命中的发薪活动个数大于 50 时，开放接口将根据查询参数返回 2500003 或 2500008 错误码，请合理使用查询参数。
- 开放接口中的「员工的飞书人事雇佣 ID 列表（employee_ids）」参数为必填。
- 批量查询发薪明细接口数据取自发薪活动，调用前请先创建发薪活动并完成算薪活动关联。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/payroll/v1/payment_detail/query |
| HTTP Method | POST |
| 接口频率限制 | 1 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 | payroll:payment_details:read 获取发薪明细数据V2 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
page_index | int | 是 | 页码，第一页从 1 开始 示例值：100 数据校验规则： - 取值范围： 1 ～ 100000 |
page_size | int | 是 | 每页大小，范围为：[1, 100] 示例值：10 |
acct_item_ids | string\[\] | 否 | 算薪项 ID 列表，调用批量查询算薪项接口后，可以从返回结果中获取到算薪项 ID。 1. 当前参数传空时，接口会返回发薪明细中所有的算薪项； 2. 当前参数不为空时，接口只返回发薪明细中与 acct_item_ids 存在交集的算薪项。 示例值：["7202076988667019333"] 数据校验规则： - 长度范围： 0 ～ 100000 |
employee_ids | string\[\] | 是 | 员工的飞书人事雇佣 ID 列表，该参数为必填，调用搜索员工信息接口后，可以从返回结果中获取到飞书人事雇佣 ID。 注：调用搜索员工信息接口时，查询入参 user_id_type 应为 people_corehr_id。 示例值：["7202076988667019222"] 数据校验规则： - 长度范围： 1 ～ 100 |
pay_period_start_date | string | 否 | 发薪日开始时间，格式：YYYY-MM-dd，[pay_period_start_date, pay_period_end_date] 是一个左闭右闭区间。 示例值："2024-01-01" |
pay_period_end_date | string | 否 | 发薪日结束时间，格式：YYYY-MM-dd，[pay_period_start_date, pay_period_end_date] 是一个左闭右闭区间。 1. pay_period_start_date 不得晚于 pay_period_end_date 。 2. [pay_period_start_date, pay_period_end_date] 最大间隔为 12 个月。 示例值："2024-01-31" |
activity_ids | string\[\] | 否 | 发薪活动 ID 列表，调用查询发薪活动列表接口后，可以从返回结果中获取到发薪活动 ID。 示例值：["7202076988667019308"] 数据校验规则： - 长度范围： 0 ～ 50 |
include_segment_data | boolean | 否 | 是否需要查询算薪明细的分段信息，如果不传该参数或传 false ，那么只返回发薪活动明细数据；如果该参数传了 true，那么同时返回发薪明细对应的算薪明细分段数据。 示例值：false |
请求体示例
json
{
"page_index": 100,
"page_size": 10,
"acct_item_ids": [
"7202076988667019333"
],
"employee_ids": [
"7202076988667019222"
],
"pay_period_start_date": "2024-01-01",
"pay_period_end_date": "2024-01-31",
"activity_ids": [
"7202076988667019308"
],
"include_segment_data": false
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
└ payment_details | payment_detail\[\] | 发薪明细列表 |
└ employee_id | string | 员工的飞书人事雇佣 ID，调用搜索员工信息接口后，可以从返回结果中获取到飞书人事雇佣 ID。 注：调用搜索员工信息接口时，查询入参 user_id_type 应为 people_corehr_id。 |
└ activity_id | string | 发薪明细所在的发薪活动 ID，调用查询发薪活动列表接口后，可以从返回结果中获取到发薪活动 ID。 |
└ payment_accounting_items | payment_accounting_item\[\] | 发薪明细详情 |
└ id | string | 算薪项 ID，调用批量查询算薪项接口后，可以从返回结果中获取到算薪项 ID。 注：明细中返回的部分算薪项可能不存在于批量查询算薪项的接口结果中。 |
└ accounting_item_names | i18n_content\[\] | 算薪项名称 |
└ locale | string | 语种 |
└ value | string | 语种对应的值 |
└ accounting_item_value | accounting_item_value | 算薪项值 |
└ original_value | string | 算薪项数据原始值，当发薪明细的数据来源为「人工导入」时，如果当前算薪项类型为引用类型，那么算薪项原始值可能为空。 |
└ reference_values | i18n_content\[\] | 引用类型算薪项展示值 |
└ locale | string | 语种 |
└ value | string | 语种对应的值 |
└ segment_values | segment_value\[\] | 算薪项分段数据 |
└ start_time | string | 分段开始时间-毫秒级时间戳，[start_time, end_time] 是一个左闭右闭区间。 |
└ end_time | string | 分段结束时间-毫秒级时间戳，[start_time, end_time] 是一个左闭右闭区间。 |
└ reference_values | i18n_content\[\] | 引用类型算薪项分段展示值 |
└ locale | string | 语种 |
└ value | string | 语种对应的值 |
└ original_value | string | 算薪项分段原始值 |
└ accounting_item_type | int | 算薪项类型，1-文本；2-金额；3-数值；4-百分比；5-日期；6-引用 |
└ total | int | 发薪明细总数 |
响应体示例
json
{
"code": 0,
"msg": "success",
"data": {
"payment_details": [
{
"employee_id": "7202076988667019308",
"activity_id": "7202076988667019308",
"payment_accounting_items": [
{
"id": "7202076988667019308",
"accounting_item_names": [
{
"locale": "zh_cn",
"value": "名称"
}
],
"accounting_item_value": {
"original_value": "100",
"reference_values": [
{
"locale": "zh_cn",
"value": "名称"
}
]
},
"segment_values": [
{
"start_time": "7220356259681386540",
"end_time": "7220356259681386540",
"reference_values": [
{
"locale": "zh_cn",
"value": "名称"
}
],
"original_value": "10000"
}
],
"accounting_item_type": 1
}
]
}
],
"total": 50000
}
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 500 | 2500001 | unknown error | 未知错误，请联系技术支持。 |
| 400 | 2500002 | param is invalid | 参数错误，请检查参数。 |
| 400 | 2500003 | Too many payment activities. Please reduce the number of "payment activity ID list". | 发薪活动数量过多，请减少「发薪活动 ID 列表」个数。 |
| 400 | 2500004 | Pay date range can't exceed 12 months. Please shorten the pay date range. | 发薪日时间范围不能超过12个月，请缩短发薪日时间范围。 |
| 400 | 2500005 | Employee ID list is too long. Please reduce it to within 100 characters. | 员工 ID 列表过长，请减少至100个以内。 |
| 400 | 2500006 | Pay start and end dates and payment activity ID can't both be empty. | 发薪起止日、发薪活动 ID 不得均为空。 |
| 500 | 2500007 | rpc fail | 请求调用出错，请联系技术支持。 |
| 400 | 2500008 | Too many payment activities. Please shorten the pay date range. | 发薪活动数量过多，请缩短发薪日时间范围。 |