飞书开放平台 Server API 文档

主题

批量获取员工参保档案 ​

通过用户ID列表和生效日期查询

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/compensation/v1/social_archive/query
HTTP MethodPOST
接口频率限制10 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:compensation.social_archive:read 获取员工参保档案信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 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: 以people_corehr_id来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
user_id_liststring\[\]是用户ID列表，与入参 user_id_type 类型一致，最少1个，最大200
示例值：["7023711013443944467"]
数据校验规则：
- 长度范围：0 ～ 200
effective_datestring是生效日期，查询在该日期生效的社保档案，格式为 YYYY-mm-dd，长度为 10 字符
示例值："2024-01-01"

请求体示例 ​

json
{
    "user_id_list": [
        "7023711013443944467"
    ],
    "effective_date": "2024-01-01"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ archivessocial_archive\[\]参保档案列表
    └ user_idstring员工ID，与入参 user_id_type 类型一致
    └ detailssocial_archive_detail\[\]员工参保档案，包含社保、公积金档案
      └ descriptioni18n调整说明
        └ zh_cnstring2024年社保基数调整
        └ en_usstring英文名称
      └ insurance_typestring类型。social_insurance: 社保; provident_fund: 公积金
可选值有：
- social_insurance: 社保 - provident_fund: 公积金
      └ insurance_statusstring参保状态，非「参保」状态下，基数、险种数据等为空
可选值有：
- contribution: 参保 - not_contribution: 不参保 - stopped_contribution: 停保
      └ idstring员工参保档案ID
      └ tidstring员工参保档案调整记录ID（根据档案生效时间查询对应年月的调整记录）
      └ plan_idstring参保方案ID，详细信息可通过查询参保方案接口获取
      └ plan_tidstring参保方案版本ID
      └ location_idstring参保城市ID，可通过获取地点信息接口查询详细信息
      └ company_idstring社保缴纳主体ID，可通过获取公司主体接口查询详细信息
      └ account_typestring社保账户类型
      └ insurance_accountstring社保账号
      └ base_salarystring申报缴纳基数，单位：元
      └ insurance_detailssocial_archive_item\[\]险种数据详情
        └ insurance_idstring险种ID，可通过获取险种配置列表接口查询
        └ company_deductionstring企业缴纳金额，单位：元
        └ company_settingsocial_plan_item_setting企业缴纳配置
          └ lower_limitstring基数下限，浮点数，保留二位小数，单位：元
          └ upper_limitstring基数上限，浮点数，保留二位小数，单位：元
          └ payment_ratiostring缴纳比例，浮点数，默认填充到二位小数，支持输入到四位，单位为 %
          └ payment_rounding_rulestring缴纳金舍入规则。rounding: 四舍五入; round_up: 向上舍入; round_down: 向下舍入
可选值有：
- rounding: 四舍五入 - round_up: 向上舍入 - round_down: 向下舍入
          └ payment_decimalsint缴纳金小数位数，0位小数-6位小数之间选择
          └ fixed_paymentstring附加固定金额，浮点数，保留二位小数，单位：元
        └ personal_deductionstring个人缴纳金额，单位：元
        └ personal_settingsocial_plan_item_setting个人缴纳配置
          └ lower_limitstring基数下限，浮点数，保留二位小数，单位：元
          └ upper_limitstring基数上限，浮点数，保留二位小数，单位：元
          └ payment_ratiostring缴纳比例，浮点数，默认填充到二位小数，支持输入到四位，单位为 %
          └ payment_rounding_rulestring缴纳金舍入规则。rounding: 四舍五入; round_up: 向上舍入; round_down: 向下舍入
可选值有：
- rounding: 四舍五入 - round_up: 向上舍入 - round_down: 向下舍入
          └ payment_decimalsint缴纳金小数位数，0位小数-6位小数之间选择
          └ fixed_paymentstring附加固定金额，浮点数，保留二位小数，单位：元
        └ payment_frequencystring缴纳频率
可选值有：
- annually: 每年 - monthly: 每月 - quarterly: 每季度
        └ payment_monthsint\[\]缴纳月份，1月～12月
      └ effective_datestring档案生效时间，yyyy-MM-dd

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "archives": [
            {
                "user_id": "9960875",
                "details": [
                    {
                        "description": {
                            "zh_cn": "中文名称",
                            "en_us": "Social Insurance Contribution Record"
                        },
                        "insurance_type": "social_insurance",
                        "insurance_status": "contribution",
                        "id": "7202347584043501100",
                        "tid": "7202347584043566636",
                        "plan_id": "7200668421690885676",
                        "plan_tid": "7200668421690852908",
                        "location_id": "7152398273176192556",
                        "company_id": "7096372135576618540",
                        "account_type": "associated_company",
                        "insurance_account": "ac123456",
                        "base_salary": "1000.10",
                        "insurance_details": [
                            {
                                "insurance_id": "111223",
                                "company_deduction": "2000.20",
                                "company_setting": {
                                    "lower_limit": "1000.00",
                                    "upper_limit": "2000.00",
                                    "payment_ratio": "8.00",
                                    "payment_rounding_rule": "round_down",
                                    "payment_decimals": 2,
                                    "fixed_payment": "200.00"
                                },
                                "personal_deduction": "1000.20",
                                "personal_setting": {
                                    "lower_limit": "1000.00",
                                    "upper_limit": "2000.00",
                                    "payment_ratio": "8.00",
                                    "payment_rounding_rule": "round_up",
                                    "payment_decimals": 2,
                                    "fixed_payment": "200.00"
                                },
                                "payment_frequency": "monthly",
                                "payment_months": [
                                    1
                                ]
                            }
                        ],
                        "effective_date": "2024-01-01"
                    }
                ]
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5002290001server error服务端异常，请稍后重试
4002290002param is invalid请检查请求参数的格式或值是否符合接口要求，参考文档中的参数说明
4042290003plan or plan version not found接口404，联系技术支持

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

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