批量查询外部算薪数据记录

1. 支持通过payroll_period（必传）、employment_id（可选）这两个预置字段，批量查询指定数据源下的数据记录列表。
2. 数据源配置信息可从获取外部数据源配置信息或者 「飞书人事后台-设置-算薪数据设置-外部数据源配置」页面 获取

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/payroll/v1/datasource_records/query
HTTP Method	POST
接口频率限制	10 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	payroll:external_datasource_record:read Payroll外部数据记录查询权限 > Tip: 本接口支持行数据鉴权，请确保应用拥有写入员工所在薪资组的数据授权。（如果是用户身份访问，请在飞书人事后台-角色配置中赋予「外部数据源 - 数据明细」的权限）

请求头

名称	类型	必填	描述
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_size	int	是	示例值：10 数据校验规则： - 取值范围：1 ～ 100
page_token	string	否	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值：eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=

请求体

名称	类型	必填	描述
source_code	string	是	数据源code 示例值："test__c"
selected_fields	string\[\]	否	指定查询的数据源字段code。 1. 如不传入此字段，默认返回所有数据源字段 2. 如果传入，除了返回指定字段外，系统会默认返回emplyment_id、payroll_period字段的值。 示例值：["test__c"] 数据校验规则： - 长度范围：1 ～ 200
field_filters	datasource_record_field_filter\[\]	否	查询条件列表，多个条件之间为And关系，支持的查询条件如下： 1. employment_id - 非必传，最多传入100个，field_type=3（文本类型）。 - 该id为飞书人事中员工的基本信息id，可通过搜索员工信息获取. - 查询操作符只支持IsAnyOf（包含） 2. 时间范围条件必传，根据数据源的不同数据写入维度，支持的时间范围查询条件如下： - 算薪期间维度。payroll_period字段，格式：2024-01， 查询方式：IsAnyOf操作符枚举需要查的月份，最多可查2个月。 - 数据发生日期维度（灰度中）。occur_day字段，格式2024-01-02， 查询方式：通过InDateRange操作符查询（日期范围查询），occur_day的时间范围不允许超过90天， - 自定义数据周期维度（灰度中）。custom_start、custom_end字段，格式：2024-01-02。查询方式：两者都必传，通过InDateRange操作符查询（日期范围查询），时间范围不允许超过90天。 数据校验规则： - 最大长度：100
└ field_code	string	是	字段编码 示例值："employment_id"
└ field_values	string\[\]	否	包含的字段值列表。 示例值：["123"] 数据校验规则： - 长度范围：1 ～ 500
└ operator	int	否	查询操作符，不传默认为IsAnyOf 包含查询。 示例值：1 可选值有： - 1: IsAnyOf 包含查询，被查询记录的字段值被field_values列表包含即可。 - 2: InDateRange 日期范围查询。field_values长度必须为2，类似[startDate,endDate]，前后都是闭区间；其中日期格式为“2024-01-02”，仅occur_day、custom_start、custom_end字段支持此查询方式，且时间范围不超过90天。 数据校验规则： - 取值范围：1 ～ 2

请求体示例

{
    "source_code": "yache19_8680__c",
    "selected_fields": [
        "yache41_8680__c"  // 需查的字段
    ],
    "field_filters": [
        {
            "field_code": "employment_id", // 可选查询条件
            "field_values": [
                "6993242233201853965",
                "7163264720525592101"
            ]
        },
        {
            "field_code": "payroll_period", // 算薪期间，必要的查询条件
            "field_values": [
                "2024-10"
            ]
        }
    ]
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ page_token	string	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
└ has_more	boolean	是否还有更多项
└ records	datasource_record\[\]	数据记录列表
└ active_status	int	记录的启停用状态 可选值有： - 1: 已启用 - 2: 已停用
└ field_values	datasource_record_field\[\]	记录的字段值列表
└ field_code	string	数据源字段编码
└ value	string	字段值 通过string传输，值为API写入的值。
└ field_type	int	字段类型。可从「查询外部数据源设置」API 或者 「飞书人事后台-设置-算薪数据设置-外部数据源配置」页面 获取。 1. 金额 2. 数值 3. 文本 4. 日期 5. 百分比

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "page_token": "7413047003142619148",
        "has_more": true,
        "records": [
            {
                "active_status": 1,
                "field_values": [
                    {
                        "field_code": "yache41_8680__c",
                        "value": "2024-12-01",
                        "field_type": 1
                    }
                ]
            }
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
500	2500001	unknown error	未知错误，联系技术支持
400	2500002	param invalid	参数异常，请检查入参
200	2500004	datasource_code:{field_code} not exist	数据源编码不存在，请检查编码是否正确
200	2500005	field_code:{field_code} not exist	字段编码不存在，请检查编码是否正确
200	2500006	lack required field_filter :	缺少必传的查询条件
200	2500007	field_filter: {field code} values size is not valid	查询条件传入的值过多
200	2500019	{field_code} format not valid	字段传入的值的格式不正确，请按照字段类型传入正确格式的值
200	2500010	filter field_code:{field_code} duplicated	字段重复