# 批量查询发薪明细 根据 __发薪活动 ID 列表__ 、__发薪日起止时间__ 和 __飞书人事雇佣 ID 列表__ 分页查询发薪明细列表和关联的算薪明细分段数据。 **注意事项**：当前接口仅支持查询某些员工在特定范围内的发薪明细，若需要查询某个发薪活动下的所有发薪明细数据，请使用[查询发薪活动明细列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/payment_activity_detail/list)接口。 ## 注意事项 1. 批量查询发薪明细接口提供的请求参数中，用户必须填写「__发薪日起止时间__（pay_period_start_date，pay_period_end_date）」或「__发薪活动 ID 列表__」，当传入的三个参数均为空时，开放接口将返回 2500006 错误码。 2. 每一次调用接口时，系统最多会扫描 __50__ 个发薪活动，当用户传入的查询条件命中的发薪活动个数大于 __50__ 时，开放接口将根据查询参数返回 2500003 或 2500008 错误码，请合理使用查询参数。 3. 开放接口中的「员工的飞书人事雇佣 ID 列表（employee_ids）」参数为必填。 4. **批量查询发薪明细接口数据取自发薪活动**，调用前请先创建发薪活动并完成算薪活动关联。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/payroll/v1/payment_detail/query HTTP Method | POST 接口频率限制 | [1 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 获取发薪明细数据V2(payroll:payment_details:read) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 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_index | int | 是 | 页码，第一页从 1 开始
**示例值**：100
**数据校验规则**：
- 取值范围：`1` ～ `100000` page_size | int | 是 | 每页大小，范围为：[1, 100]
**示例值**：10 acct_item_ids | string\[\] | 否 | 算薪项 ID 列表，调用[批量查询算薪项](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/acct_item/list)接口后，可以从返回结果中获取到算薪项 ID。
1. 当前参数传空时，接口会返回发薪明细中所有的算薪项；
2. 当前参数不为空时，接口只返回发薪明细中与 acct_item_ids 存在交集的算薪项。
**示例值**：["7202076988667019333"]
**数据校验规则**：
- 长度范围：`0` ～ `100000` employee_ids | string\[\] | 是 | 员工的飞书人事雇佣 ID 列表，__该参数为必填__，调用[搜索员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search)接口后，可以从返回结果中获取到飞书人事雇佣 ID。
注：调用[搜索员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search)接口时，查询入参 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 列表，调用[查询发薪活动列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/payment_activity/list)接口后，可以从返回结果中获取到发薪活动 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，调用[搜索员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search)接口后，可以从返回结果中获取到飞书人事雇佣 ID。
注：调用[搜索员工信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/employee/search)接口时，查询入参 user_id_type 应为 people_corehr_id。 activity_id | string | 发薪明细所在的发薪活动 ID，调用[查询发薪活动列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/payment_activity/list)接口后，可以从返回结果中获取到发薪活动 ID。 payment_accounting_items | payment_accounting_item\[\] | 发薪明细详情 id | string | 算薪项 ID，调用[批量查询算薪项](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/acct_item/list)接口后，可以从返回结果中获取到算薪项 ID。
注：明细中返回的部分算薪项可能不存在于[批量查询算薪项](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/payroll-v1/acct_item/list)的接口结果中。 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 | 未知错误，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。 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 | 请求调用出错，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)。 400 | 2500008 | Too many payment activities. Please shorten the pay date range. | 发薪活动数量过多，请缩短发薪日时间范围。