PIN码相关回调
一. PIN 码生成、重置、清除回调
1. 回调触发时机
当自动签场景下的 PIN 码被生成、重置、清除时,电子签平台会推送此回调。三种行为共用同一个消息类型,通过 OperateType 字段区分。
会触发回调的操作
| 业务操作 | 对应 OperateType | 触发说明 |
|---|---|---|
| 批量生成 PIN(已有 PIN 则沿用) | GENERATE | 仅为本次新建的 PIN 推送一次;已有 PIN 的被授权方沿用原 PIN,不重复推送 |
| 批量生成并重置 PIN(不存在则生成,已存在则重置) | GENERATE / RESET | 新建的推送 GENERATE;已有 PIN 的推送 RESET(携带旧 PIN 指纹) |
| 批量重置 PIN | RESET | 要求被授权方都已存在 PIN,重置后逐条推送 |
| 批量清除 PIN | DELETE | 仅为本次命中并清除的被授权方推送;不存在的被授权方不推送 |
PIN 的查询(是否存在)、校验(比对 PIN)均不会触发回调。
2. 回调消息类型
OperatePinPartner
3. 其他说明
1)OperateType 取值
| PIN 操作 | 对应 OperateType | 说明 |
|---|---|---|
| 生成 PIN | GENERATE | PIN 首次创建,CurPinCodeEncrypted 有值 |
| 重置 PIN | RESET | PIN 被替换为新值,CurPinCodeEncrypted 与 PrevPinCodeEncrypted 均有值 |
| 清除 PIN | DELETE | PIN 被清除(软删除),仅 PrevPinCodeEncrypted 有值 |
2)PinType 取值
| PIN 场景 | PinType | 说明 |
|---|---|---|
| 员工个人 | EMPLOYEE | 子客员工在子客企业下的个人 PIN,回调给 PIN 归属子客企业 |
| 企业授权 | PARTNER | 子客企业间相互授权(含授权给他人 / 被他人邀请),回调给被授权方子客企业 |
| 个人自动签 | PERSONAL | 个人用户的自动签 PIN 授权给子客企业,回调给被授权方子客企业 |
3)字段省略
MsgData 中取值为空的字段不会出现在回调报文中(例如 GENERATE 场景没有 PrevPinCodeEncrypted,个人自动签场景没有授权方 OrganizationId 等字段)。请按"字段可能缺省"的方式解析。
4)推送时序
- 回调为异步推送,与接口返回解耦:接口返回成功仅代表 PIN 已落库,回调可能有秒级延迟。
- 一次批量操作涉及多个被授权方时,会逐条推送,可能收到多条回调。
4. 回调结构体
MsgData结构体定义
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| PinType | String | PIN 场景类型: EMPLOYEE:员工个人 PARTNER:企业授权 PERSONAL:个人自动签 |
| OperateType | String | 本次 PIN 操作类型: GENERATE:生成 RESET:重置 DELETE:清除 |
| PinId | String | PIN 的唯一标识,为32位字符串。 重置不改变 PinId;清除后该 PinId 失效 |
| UserId | String | 操作人(子客员工)的用户 ID。 EMPLOYEE、PERSONAL 场景返回 |
| OpenId | String | 操作人在第三方平台的用户唯一标识,对应 Agent 结构体中的 ProxyOperatorOpenId。 EMPLOYEE、PERSONAL 场景返回 |
| OrganizationId | String | PIN 归属子客企业(授权方企业)的企业 ID。 EMPLOYEE、PARTNER 场景返回 |
| OrganizationOpenId | String | PIN 归属子客企业在第三方平台的唯一标识,对应 Agent 中的 ProxyOrganizationOpenId。 EMPLOYEE、PARTNER 场景返回 |
| ApplicationId | String | PIN 归属子客企业使用的应用 ID,对应 Agent 中的 AppId。 EMPLOYEE、PARTNER 场景返回 |
| ProxyApplicationId | String | PIN 归属子客企业的代理应用 ID,对应 Agent 中的 ProxyAppId。 EMPLOYEE、PARTNER 场景返回 |
| AuthOrganizationId | String | 被授权方子客企业的企业 ID,即本次回调的接收方企业 |
| AuthOrganizationOpenId | String | 被授权方子客企业在第三方平台的唯一标识 |
| AuthApplicationId | String | 被授权方子客企业的应用 ID |
| AuthProxyApplicationId | String | 被授权方子客企业的代理应用 ID |
| CurPinCodeEncrypted | String | 本次操作后 PIN 的加密字段。 GENERATE、RESET 场景返回;DELETE 场景不返回 |
| PrevPinCodeEncrypted | String | 本次操作前(旧)PIN 的加密字段。 RESET、DELETE 场景返回;首次 GENERATE 场景不返回 |
5. 示例
示例一: 企业授权(PARTNER)场景,新建 PIN
{
"MsgId": "yDwFkUUckpstin4sUuZjBEY5Ia2XB7sz",
"MsgType": "OperatePinPartner",
"MsgVersion": "ThirdPartyApp",
"MsgData": {
"PinType": "PARTNER",
"OperateType": "GENERATE",
"PinId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"OrganizationId": "yDRSRUUgygj6qnyvUuO4zjE1vLuGdWjL",
"OrganizationOpenId": "org_dianziqian",
"ApplicationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF",
"ProxyApplicationId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
"AuthOrganizationId": "yDxbNUyKQDxGYNUuO4zjEwvl3XYQmAcO",
"AuthOrganizationOpenId": "org_target",
"AuthApplicationId": "yDRS4UUgygqdcjjdUuO4zjEC0osCOsHS",
"AuthProxyApplicationId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
"CurPinCodeEncrypted": "b1946ac92492d2347c6235b4d2611184"
}
}
示例二: 员工个人(EMPLOYEE)场景,重置 PIN(携带新旧指纹)
{
"MsgId": "yDRIGUUgygs8oey1UuO4zjEC8S6bOcm8",
"MsgType": "OperatePinPartner",
"MsgVersion": "ThirdPartyApp",
"MsgData": {
"PinType": "EMPLOYEE",
"OperateType": "RESET",
"PinId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"UserId": "yDRS4UUgygqdcjjdUuO4zjEC0osCOsHS",
"OpenId": "n9527",
"OrganizationId": "yDRSRUUgygj6qnyvUuO4zjE1vLuGdWjL",
"OrganizationOpenId": "org_dianziqian",
"ApplicationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF",
"ProxyApplicationId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
"AuthOrganizationId": "yDRSRUUgygj6qnyvUuO4zjE1vLuGdWjL",
"AuthOrganizationOpenId": "org_dianziqian",
"AuthApplicationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF",
"AuthProxyApplicationId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
"CurPinCodeEncrypted": "25f9e794323b453885f5181f1b624d0b",
"PrevPinCodeEncrypted": "b1946ac92492d2347c6235b4d2611184"
}
}
示例三: 个人自动签(PERSONAL)场景,清除 PIN
{
"MsgId": "yDxbNUyKQDxGYNUuO4zjEwvl3XYQmAcO",
"MsgType": "OperatePinPartner",
"MsgVersion": "ThirdPartyApp",
"MsgData": {
"PinType": "PERSONAL",
"OperateType": "DELETE",
"PinId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"UserId": "yDRS4UUgygqdcjjdUuO4zjEC0osCOsHS",
"OpenId": "n9527",
"AuthOrganizationId": "yDxbNUyKQDxGYNUuO4zjEwvl3XYQmAcO",
"AuthOrganizationOpenId": "org_target",
"AuthApplicationId": "yDRS4UUgygqdcjjdUuO4zjEC0osCOsHS",
"AuthProxyApplicationId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
"PrevPinCodeEncrypted": "25f9e794323b453885f5181f1b624d0b"
}
}
二. PIN 码验证签署失败回调
1. 回调触发时机
当轮到 PIN 码签类型的签署方进行 PIN 码授权签署时,平台校验其 PIN 码失败(可能是签署人重置了PIN码)。
仅 PIN 码签类型的签署方会触发此回调:8-本方企业 PIN 码授权、9-他方企业 PIN 码授权、10-个人 PIN 码授权。
失败后的处理方式
- 发起方可调用 ModifyFlowApproverPinCodes(更新签署方 PIN 码) 接口更新该签署方的 PIN 码,更新成功后,若当前已轮到此签署方签署,则会重新触发签署;若尚未轮到,则会在轮到该签署方时使用更新后的 PIN 码进行验证。
- PIN 码授权签署是异步进行的,具体是否签署成功,可通过监听合同状态变更回调获取。
2. 回调消息类型
PinCodeSignVerifyFailed
3. 其他说明
1)FailReason 取值
| 失败原因 | 对应 FailReason | 说明 |
|---|---|---|
| PIN 码验证失败 | 0 | PIN 码校验未通过,可能是签署人重置了 PIN 码授权 |
FailReason 枚举从 0 开始,后续失败类型待定扩展,请按"未知枚举值需兼容"的方式解析。
2)字段省略
MsgData 中取值为空的字段不会出现在回调报文中(例如个人 PIN 码签场景没有 OrganizationName,合同不属于合同组时没有 FlowGroupId,签署方非第三方子客企业时没有 ProxyOrganizationOpenId、ProxyOperatorOpenId)。请按"字段可能缺省"的方式解析。
3)推送时序
- 回调为异步推送,与签署动作解耦,可能有秒级延迟。
- 请以
FlowId+RecipientId+FailReason做幂等处理,避免因消息重投导致重复消费。
4. 回调结构体
MsgData结构体定义
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| ApplicationId | String | 第三方应用的应用编号 |
| ProxyOrganizationOpenId | String | 发起方企业在第三方平台的唯一标识,定义和 Agent 中的 ProxyOrganizationOpenId 一样,可以参考Agent结构体 |
| FlowId | String | 合同流程 ID,为 32 位字符串 |
| FlowGroupId | String | 合同组 ID。合同属于合同组时返回,非组内子合同该字段缺省 |
| FailReason | Integer | 失败原因枚举: 0:PIN码验证失败 |
| FailMessage | String | 失败原因文案,FailReason 的可读描述,当前固定返回:PIN码验证失败 |
| ApproverInfo | ApproverDetail | 签署失败的签署方信息,结构体的定义可以参考下面的ApproverDetail |
ApproverDetail结构体定义
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| RecipientId | String | 签署方的参与角色 ID,为 32 位字符串 |
| SignId | String | 签署人签署区 ID,与查询合同详情接口返回的签署人 SignId 一致 |
| ApproverType | Integer | 签署人类型: 8:本方企业 PIN 码授权 9:他方企业 PIN 码授权 10:个人 PIN 码授权 |
| OrganizationName | String | 签署方企业名称。个人 PIN 码签场景该字段缺省 |
| ApproverName | String | 签署人姓名 |
| ApproverMobile | String | 签署人手机号(打码返回,如 185****0000) |
| ApproverIdCardType | String | 签署人证件类型: ID_CARD:中国大陆居民身份证 HONGKONG_AND_MACAO:中国港澳居民来往内地通行证 HONGKONG_MACAO_AND_TAIWAN:中国港澳台居民居住证(格式同居民身份证) |
| ApproverIdCardNumber | String | 签署人证件号码(打码返回,仅保留首末位,如 1****************6) |
| ProxyOrganizationOpenId | String | 签署方企业在第三方平台的唯一标识。签署方为第三方子客企业时返回 |
| ProxyOperatorOpenId | String | 签署方经办人在第三方平台的唯一标识,定义和 Agent.ProxyOperator.OpenId 一样。签署方为第三方子客企业员工时返回 |
5. 示例
示例一: 本方企业 PIN 码授权(ApproverType=8)场景,PIN 码验证失败
{
"MsgId": "yDwFkUUckpstin4sUuZjBEY5Ia2XB7sz",
"MsgType": "PinCodeSignVerifyFailed",
"MsgVersion": "ThirdPartyApp",
"MsgData": {
"ApplicationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF",
"ProxyOrganizationOpenId": "org_dianziqian",
"FlowId": "yDCVjUUckpw7hdznUyigyC6El96dC2Yo",
"FailReason": 0,
"FailMessage": "PIN码验证失败",
"ApproverInfo": {
"RecipientId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlMfy",
"SignId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlXq",
"ApproverType": 8,
"OrganizationName": "典子谦养生茶馆",
"ApproverName": "刘波",
"ApproverMobile": "185****0000",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardNumber": "1****************6",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperatorOpenId": "n9527"
}
}
}
示例二: 他方企业 PIN 码授权(ApproverType=9)场景,合同组内子合同 PIN 码验证失败
{
"MsgId": "yDxbNUyKQDxGYNUuO4zjEwvl3XYQmAcO",
"MsgType": "PinCodeSignVerifyFailed",
"MsgVersion": "ThirdPartyApp",
"MsgData": {
"ApplicationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF",
"ProxyOrganizationOpenId": "org_dianziqian",
"FlowId": "yDCVjUUckpw7hdznUyigyC6El96dC2Yo",
"FlowGroupId": "yDCVjUUckpw7hdznUyigyC6El96dC2Yp",
"FailReason": 0,
"FailMessage": "PIN码验证失败",
"ApproverInfo": {
"RecipientId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlMfy",
"SignId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlXq",
"ApproverType": 9,
"OrganizationName": "子谦科技有限公司",
"ApproverName": "猪猪侠",
"ApproverMobile": "173****0000",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardNumber": "3****************8",
"ProxyOrganizationOpenId": "org_ziqian",
"ProxyOperatorOpenId": "n9528"
}
}
}