回调通知模式 - 2号人事部开放平台

回调通知模式¶

概述¶

基本概念¶

回调通知模式
在回调通知模式下, 企业会收到2号人事部开放平台发送的事件通知, 企业只需要 配置回调地址 即可开启回调通知模式
事件通知
公司HR对员工信息进行维护, 2号人事部开放平台将具体的变更信息发送到公司设置的回调地址, 通知发送方式为 POST , 数据包使用 JSON 格式, UTF8编码
发送数据规范
2号人事部开放平台给客户公司发送事件通知的数据包格式规范
返回数据规范
客户公司接收到事件通知后, 返回给2号人事部开放平台的数据包格式规范

使用说明¶

在 配置回调地址 中测试验证通过, 则回调通知模式开启生效, 在 配置回调地址 中测试验证无效, 则回调通知模式关闭
回调通知模式下, 2号人事部开放平台会发送符合 发送数据规范 的数据给客户企业回调地址, 客户企业需要在超时时间(5s)内返回符合 返回数据规范 的数据包给2号人事部开放平台，返回超时或者数据不符合规范, 2号人事部开放平台均会判定本次通知失败，重新发送通知(重新发送数次最多为3次, 每次重新发送时间与上一次发送失败的时间间隔依次为 60s/300s/600s, 重试3次通知仍然不成功，2号人事部开放平台不再通知)
同一事件通知, 3秒发送一次, 在3秒内触发多次(不多于500次), 2号人事部开放平台会将多次的数据合并成一次事件通知(超出500次的部分合并到下一次事件通知)
事件通知通过事件 key 来区分, 不同的事件通知事件 key 不同, 请求参数参考 人事变更事件回调通知
回调通知模式下的所有事件通知 超时时间 为 5s
同一事件通知发送频率: 20次/分钟, 所有事件通知频率上限: 240次/分钟
对于部分事件, 只有修改信息对应的字段在 事件触发字段表 中才会触发相应事件通知, 如:员工修改事件, 修改员工手机号可以触发事件通知, 但是修改考勤编号不会触发事件通知

发送数据规范¶

不同事件通知, 事件 key 不同, 数据 data 所包含数据也不同, data 列表长度最大为500, 具体请查看 人事变更事件回调通知 表
下面是员工添加事件的发送数据包实例:

{
   "key": "employee_add",
   "data": ["e233b5*****2-4cf1-a3f6-5*****841dd2", "0d29f1*****4-433c-b68f-7*****dd4bfc"]
}

返回数据规范¶

请严格按照规范返回参数给2号人事部开放平台, 2号人事部开放平台收到符合规范的数据才会判定事件通知发送成功.

变量名	类型	必填	参数说明
result_code	String	是	返回状态码
result_msg	String	是	返回信息

{
   "result_code": "SUCCESS",
   "result_msg": "OK"
}

配置回调地址¶

如何配置¶

2号人事部顶部导航栏依次点击： 更多 -> 我的应用 -> 开放平台 ，在【回调通知模式】点击“设置”按钮，填入回调地址，点击“保存”，回调地址配置完成。

how

how2

如何验证通过¶

按照 如何配置 中的步骤正确填写回调地址，点击“测试回调地址”按钮，2号人事部开放平台会以 POST 方式发送测试数据包给回调地址，测试数据包如下：

{
    "key": "event_test",
    "data": []
}

收到测试数据包后请按 返回数据规范 返回数据，在超时时间(5s)内，2号人事部开放平台收到符合 返回数据规范 的数据，则验证通过，回调模式才能开启；验证结果以弹出消息框为准。

valid

人事变更事件回调通知¶

测试事件¶

事件名称	事件key	事件触发（描述）	事件参数
测试事件	event_test	测试回调地址	{"key": "event_test", "data": []}

员工事件¶

事件名称	事件key	事件触发（描述）	事件参数
员工添加事件	employee_add	新增员工时触发	{"key": "employee_add","data":["新增员工id1", "新增员工id2"]}
员工修改事件	employee_update	员工属性字段发生变化时触发	{"key": "employee_update", "data":["修改员工id1","修改员工id2"]}
员工删除事件	employee_delete	删除员工时触发	{"key": "employee_delete", "data": ["删除员工id1", "删除员工id2"]}
员工还原事件	employee_reduce	还原已删除员工时触发	{"key": "employee_reduce","data": ["还原员工id1", "还原员工id2"]}
员工转正事件	employee_formal	办理员工转正时触发	{"key": "employee_formal","data": ["转正员工id1", "转正员工id2"]}
员工离职事件	employee_leave	办理员工离职时触发	{"key": "employee_leave","data": ["离职员工id1", "离职员工id2"]}
员工重新入职事件	employee_re_entry	员工重新入职时触发	{"key": "employee_re_entry","data": ["重新入职员工id1","重新入职员工id2"]}

待入职员工事件¶

事件名称	事件key	事件描述	事件参数
待入职添加事件	intent_employee_add	添加待入职员工时触发	{"key": "intent_employee_add", "data": ["新增待入职员工id1", "新增待入职员工id2"]}
待入职修改事件	intent_employee_update	修改待入职信息时触发	{"key": "intent_employee_update", "data": ["修改待入职员工id1","修改待入职员工id2"]}
待入职删除事件	intent_employee_delete	删除待入职员工时触发	{"key": "intent_employee_delete", "data": ["删除待入职员工id1", "删除待入职员工id2"]}
待入职确认入职事件	intent_employee_entry	待入职员工确认入职时触发	{"key": "intent_employee_entry", "data":[("待入职员工id1", "id1入职后员工id"),("待入职员工id2", "id2入职后员工id")]}
待入职放弃入职事件	intent_employee_give_up	待入职员工放弃入职时触发	{"key": "intent_employee_give_up", "data": ["放弃待入职员工id1", "放弃待入职员工id2"]}

合同事件¶

事件名称	事件key	事件描述	事件参数
签署电子合同事件	sign_electronic_contract	签署电子合同成功同步员工合同后触发	{"key": "sign_electronic_contract", "data": [(签署合同员工id1, 合同类型列举项1, 合同类型文本1),(签署合同员工id2, 合同类型列举项2, 合同类型文本2),(签署合同员工id3, 合同类型列举项3, 合同类型文本3)]}

审批申请状态变化回调通知¶

使用场景： 当审批单的流程状态发生变化时，会将审批单最新的流程状态回调给开发者。

支持所有审批单类型的审批在状态变化时进行回调通知

请求方式： POST（HTTPS）

请求地址： 用户在企业设置的回调地址

请求包结构体：

{
   "key": "approve_result",
   "data": [{ 
            "add_dt": "添加日期",
            "submit_title": "审批单标题",
            "submit_no": "审批单编号",
            "submit_id": "审批单id",
            "company_id": "企业id",
            "status": "", 
            "is_delete": "审批单是否被删除",
            "url": "审批单附件url"
    }]
}

参数	类型	是否必须	说明
key	String	是	回调事件类型
data	Arrary	是	3s内状态变化的审批单批量返回（最多500条）
add_dt	String	是	添加日期
submit_title	String	是	审批单标题
submit_no	String	是	审批单编号
status	String	是	审批单状态：1进行中，2审批通过，3审批拒绝，4审批撤销
submit_id	String	是	审批单id
company_id	String	是	公司id
is_delete	Boolean	是	审批单是否被删除
url	String	否	审批单附件url

注意： 当审批单通过/拒绝/撤销/删除时，把审批单的状态传递给用户在2号人事部开发平台绑定的回调地址。

入职信息采集事件回调通知¶

使用场景： 入职登记表信息采集流程中的相关事件，会将该事件回调给开发者。

请求方式： POST（HTTPS）

请求地址： 用户在企业设置的回调地址

请求包结构体示例：

{
    "key": "entry_form_submit",
    "data": {
        "entry_id": "bx33fg*****17b081bfd8*****c51c8e8a"
    }
}

参数	类型	是否必须	说明
key	String	是	回调事件类型
data	Object	是	回调消息主体内容
entry_id	String	是	流程ID

key名称	key 值	事件触发（描述）	事件参数
入职信息采集登记表短信推送结果	entry_form_message_send	给用户推送入职信息采集消息(短信)时触发	{"key": "entry_form_message_send", "data": {"entry_id": "流程ID", "is_success": true, "add_dt": "时间"}}
用户入职信息采集提交结果推送	entry_form_submit	用户提交入职信息采集时触发	{"key": "entry_form_submit", "data": {"entry_id": "流程ID", "is_success": true, "add_dt": "时间"}}

电子合同签署任务事件回调通知¶

使用场景： 电子合同签署任务流程中，2号系统会通过开放平台将该签署任务的各个节点的结果以【回调通知事件】通知开发者。

请求方式： POST（HTTPS）

请求地址： 用户在企业设置的回调地址

请求包结构体示例：

{
    "key": "econtract_task",
    "data": {
        "entry_id": "d22ba6*****f44c7a89ae*****19c7f5",
        "type": "econtract_create",
        "is_success": true, 
        "add_dt": "2022-02-16 15:41:41"
    }
}

参数	类型	是否必须	说明
key	String	是	回调事件类型，固定为 `econtract_task` 表示电子合同签署任务
data	Object	是	回调消息主体内容
entry_id	String	是	流程ID
type	String	是	电子合同任务类型，type类型说明详见下表
is_success	bool	是	是否成功，true 表示该节点成功，false 代表该任务节点失败
add_dt	String	是	记录时间

type名称	type 值	事件触发（描述）	事件参数
电子合同创建	econtract_create	接口提交电子合同参数校验通过，生成电子合同时触发	{"key": "econtract_task", "data": {"entry_id": "流程ID", "type": "econtract_create", "is_success": true, "add_dt": "时间"}}
电子合同消息推送	econtract_message_send	给用户推送电子合同消息时触发	{"key": "econtract_task", "data": {"entry_id": "流程ID", "type": "econtract_message_send", "is_success": true, "add_dt": "时间"}}
员工签署结果消息推送	econtract_employee_sign	员工签署电子合同时触发	{"key": "econtract_task", "data": {"entry_id": "流程ID", "type": "econtract_employee_sign", "is_success": true, "add_dt": "时间"}}
企业签署结果消息推送	econtract_company_sign	员工签署电子合同时触发	{"key": "econtract_task", "data": {"entry_id": "流程ID", "type": "econtract_company_sign", "is_success": true, "add_dt": "时间"}}

电子合同模版变更事件回调通知¶

使用场景： 电子合同模版发生变更，2号系统会通过开放平台将变更企业和合同模版ID通过【回调通知事件】通知开发者。

请求方式： POST（HTTPS）

请求地址： 用户在企业设置的回调地址

请求包结构体示例：

{
    "key": "econtract_template",
    "data": {
        "company_id": "d22ba6*****f44c7a89ae*****19c7f5",
        "template_id": "19c7f*****5d22ba6*****f44c7a89ae",
        "type": "template_create"
    }
}

参数	类型	是否必须	说明
key	String	是	回调事件类型，固定为 `econtract_template` 表示电子合同模版变更事件
data	Object	是	回调消息主体内容
company_id	String	是	企业ID
type	String	是	电子合同模版变更类型，type类型说明详见下表
template_id	String	是	变更模版ID

type名称	type 值	事件触发（描述）	事件参数
电子合同模版创建	template_create	2号中创建新的合同模版时触发	{"key": "econtract_template", "data": {"company_id": "企业ID", "type": "template_create", "template_id": "模版ID"}}
电子合同模版更新	template_update	2号中更新合同模版时触发	{"key": "econtract_template", "data": {"company_id": "企业ID", "type": "template_update", "template_id": "模版ID"}}
电子合同模版删除	template_delete	2号中删除合同模版时触发	{"key": "econtract_template", "data": {"company_id": "企业ID", "type": "template_delete", "template_id": "模版ID"}}

事件触发字段表¶

员工相关字段表¶

在职信息	个人信息	联系信息	工资社保
工号	姓名	手机号码	工资卡卡号
组织	英文名	个人邮箱	工资卡开户城市
岗位	证件类型	工作邮箱	工资卡开户行
岗位职级编号	证件号码	现居住地址	个人社保账号
工作城市	性别		个人公积金账号
工作地点	生日
合同公司	出生日期
工作性质	年龄
员工状态	是否已婚
入职日期	是否已育
试用期	国家地区
离职日期	民族
离职原因	政治面貌
	户籍城市
	户口性质

待入职员工相关字段表¶

在职信息	个人信息	联系信息	工资社保
组织	姓名

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search