创建薪资档案

该接口适用于员工入职定薪、调薪或者更正档案场景，通过创建调薪任务的方式，为员工生成对应薪资档案数据。
当员工在调薪生效日期存在档案数据时，则是对该档案进行更正操作。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/compensation/v1/archives
HTTP Method	POST
接口频率限制	10 次/秒
支持的应用类型	custom
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用	`corehr:compensation_archive:write` 创建定调薪任务
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 `contact:user.employee_id:readonly` 获取用户 user ID

请求头

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

查询参数

名称	类型	必填	描述
`user_id_type`	`string`	是	用户 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

请求体

名称	类型	必填	描述
`unique_id`	`string`	是	外部幂等id，表示操作的唯一标识，避免重复发起，格式为标准的UUIDV4（32 个十六进制字符 + 4 个连字符）示例值："123e4567-e89b-42d3-a456-426614174000"
`operator_id`	`string`	否	操作人ID，具体类型由入参中的 user_id_type 指定，选择应用身份鉴权时，该参数不能为空示例值："7337149697626801708"
`user_id`	`string`	是	员工id，具体类型由入参中的 user_id_type 指定示例值："7337149697626801708"
`effective_time`	`string`	是	生效时间，日期格式为 YYYY-MM-DD，字符长度为10 示例值："2024-11-12"
`currency_id`	`string`	是	币种ID，通过查询货币信息接口可获得示例值："6863329932261459464"
`plan_id`	`string`	是	薪资方案ID，通过批量查询薪资方案接口可获得示例值："7431430313074247212"
`plan_tid`	`string`	是	薪资方案TID，通过批量查询薪资方案可获得示例值："7431430313074279980"
`change_reason_id`	`string`	是	调薪原因ID，通过批量查询定调薪原因接口可获得示例值："7125907336899888684"
`item_value_lists`	`archive_item_value\[\]`	是	- 薪资项值集合，所填薪资项信息必须是该方案中的薪资项 - 仅需填写方案中可编辑的薪资项即可，不可编辑的薪资项不能传入，否则会校验报错。 - 根据参数plan_id，可通过批量查询薪资方案接口获得对应的具体方案信息数据校验规则： - 长度范围：`0` ～ `2147483647`
└ `item_id`	`string`	是	薪资项ID，具体值可通过接口查询批量查询薪资项示例值："7244131355509917228"
└ `item_value`	`string`	是	- 薪资项的值，该值的单位取决于入参currency_id对应的币种 - 字符串为数字格式，且长度最大不超过18个字符，最小长度为1个字符，不支持负数，不允许为空示例值："200.00"
└ `item_value_regular`	`string`	否	- 员工转正后薪资项的值，该值的单位取决于入参currency_id对应的币种。字符串为数字格式，且长度不超过18个字符，不支持负数 - 当员工处于试用期且入参plan_id对应的薪资方案已开启试用期时，才能填写该值。 - 所有可编辑薪资项的转正值要么都为空，要么都不为空，否则会报错。示例值："600.00"
`description`	`string`	否	调薪说明，长度不超过1000字符示例值："因2024年Q2绩效优秀，对该同学调薪10%"
`edit_remark`	`string`	否	更正说明，长度不超过1000字符，如果本次操作为更正员工薪资档案时，该字段即为更正调薪的说明。示例值："更正2024年Q2绩效调薪金额"

请求体示例

json

{
    "unique_id": "123e4567-e89b-42d3-a456-426614174000",
    "operator_id": "7337149697626801708",
    "user_id": "7337149697626801708",
    "effective_time": "2024-11-12",
    "currency_id": "6863329932261459464",
    "plan_id": "7431430313074247212",
    "plan_tid": "7431430313074279980",
    "change_reason_id": "7125907336899888684",
    "item_value_lists": [
        {
            "item_id": "7244131355509917228",
            "item_value": "200.00",
            "item_value_regular": "600.00"
        }
    ],
    "description": "因2024年Q2绩效优秀，对该同学调薪10%",
    "edit_remark": "更正2024年Q2绩效调薪金额"
}

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-
└ `unique_id`	`string`	定调薪任务创建的唯一ID
└ `archive_tid`	`string`	薪资档案的TID

响应体示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
        "unique_id": "123e4567-e89b-42d3-a456-426614174000",
        "archive_tid": "7434007780111336970"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	2290001	param is empty	参数为空报错，请排查是否有参数为空
400	2290002	effective time is invalid, correct example: 2024-01-01	生效时间不合法，格式应为：2024-01-01
400	2290003	Invalid user ID, cannot find employment	人员id无法查询到对应员工，请确认人员id是否正确
500	2290004	service error	服务内部错误，请稍后重试
400	2290005	No permission to adjust	- 没有创建薪资档案的权限，请检查应用身份/用户身份的权限设置。 - 首先进入到应用设置页面，选择权限配置，核对权限配置是否合理
400	2290006	The plan not exist, please check plan_tid	薪资方案不存在，检查入参的薪资方案id和tid
400	2290007	the description is too long, limit 1000	调薪说明长度过长，长度不能超过1000
400	2290008	the edit remark is too long, limit 1000	更正说明过长，不能超过1000
400	2290009	the change reason does not exist	调薪原因不存在，请检查参数change_reason_id
400	2290010	the currency not exist, please check currency_id	币种不存在，请检查参数currency_id
400	2290011	the currency not match with the plan currency	所传币种与方案的币种不一致
400	2290012	Invalid user ID, cannot find employment	人员id不存在，请检查人员userID信息
400	2290013	employment id to people id failed, please check user_id	无法通过员工ID找到该人员的people id
400	2290014	effective time is invalid, correct example: 2024-01-01	生效时间不合法，格式为2024-01-01
400	2290015	the effective time is range out of limit, limit（1970-01-01, 2038-01-19）	生效时间不能超过限制，日期需大于1970-01-01，且小于2038-01-19
400	2290016	archive effective time is not allow before the plan effective time	档案生效时间早于方案生效时间，请修改参数的生效时间，或者修改薪资方案的对应生效时间
400	2290017	the plan status is deactivate	薪资方案已停用，请先启用方案
400	2290018	the effective time is after employee's last day, please check effective_time	生效时间不能超过员工离职日期
400	2290019	the effective time is before employee's hire day, please check effective_time	生效时间不能早于员工入职日期
400	2290020	miss required archive items, please check item_value_lists	缺少必填的的薪资项，方案中可编辑的薪资项都需要填写。
400	2290021	the item not allow to edit or the item not in plan, please check item_value_lists	方案中不存在该薪资项，或者存在不可编辑的薪资项，请完整填写方案中允许编辑的薪资项。
400	2290022	the item value is invalid, value must be a positive number and cannot be greater than 9223372036854775807	薪资项的值需为正数，且不能大于9223372036854775807
400	2290023	the plan is not open probation, the item not allow to have regular value	薪资方案未开启试用期，薪资项不允许有转正值
400	2290024	the employee is not in probation, the item not allow to have regular value	人员不在试用期内，不允许填写转正值
400	2290025	under this effective date, employees' adjust items are not allowed to have regular value	在该生效时间下，给用户进行调薪操作，不允许存在转正值
400	2290026	regular item values are either all empty or all null. Values must be positive numbers and cannot be greater than 9223372036854775807	薪资项的转正值要么都为空，要么都不为空，且为正数，不能大于9223372036854775807
400	2290027	match standard fail	- 匹配薪资标准出错，请排查系统是否尚未配置对应的薪资标准 - 首先进入到飞书人事的薪资标准表设置页面，排查是否存在该员工能匹配上的薪资标准
400	2290028	unique id is exist, please change	唯一id已存在并使用，请使用新的唯一id
400	2290029	operator id invalid, If using application identity for authentication, the operator id must be valid	- 操作人ID不合法，如果选择应用身份鉴权，则入参operator_id不能为空
400	2290030	operator id invalid, If using application identity for authentication, the operator id must be valid	操作人ID不合法，如果选择应用身份鉴权，则入参operator_id不能为空
400	2290031	This user already has a duplicate salary adjustment task under the effective date	用户在当前生效日期下，已经存在有尚未结束的调薪任务，请先结束该调薪任务后再发起
400	2290032	The user has unfinished salary adjustment tasks and cannot initiate another salary adjustment.	用户存在尚未完成的调薪任务，请先完成该调薪任务
400	2290033	effective_time is empty	生效时间为空
400	2290034	plan_id is empty	方案id为空
400	2290035	plan_tid is empty	方案tid为空
400	2290036	currency_id is empty	币种id为空
400	2290037	user_id is empty	用户id为空
400	2290038	unique_id is empty	唯一id为空
400	2290039	change_reason_id is empty	调薪原因为空
400	2290040	There are duplicate items in item_value_lists, please check item_value_lists	薪资项不允许重复，请检查是否存在相同id的薪资项
400	2290041	the item value is invalid, value must be a positive number and cannot be greater than 9223372036854775807	薪资项的值需为正数，且不能大于9223372036854775807
400	2290042	regular item values are either all empty or all null. Values must be positive numbers and cannot be greater than 9223372036854775807	薪资项的转正值需为正数，且不能大于9223372036854775807

事件

事件

员工兼职

员工国际派遣

职位数据事件

事件

事件

事件

事件

事件

事件

事件

成本中心 · version

事件

事件

事件

事件

地点 · address

事件

事件

创建薪资档案 ​

请求 ​

请求头 ​

查询参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

创建薪资档案

请求

请求头

查询参数

请求体

请求体示例

响应

响应体

响应体示例

错误码