跳到主要内容

PIN码相关回调

一. PIN 码生成、重置、清除回调​

1. 回调触发时机​

当自动签场景下的 PIN 码被生成、重置、清除时,电子签平台会推送此回调。三种行为共用同一个消息类型,通过 OperateType 字段区分。

会触发回调的操作

业务操作对应 OperateType触发说明
批量生成 PIN(已有 PIN 则沿用)GENERATE仅为本次新建的 PIN 推送一次;已有 PIN 的被授权方沿用原 PIN,不重复推送
批量生成并重置 PIN(不存在则生成,已存在则重置)GENERATE / RESET新建的推送 GENERATE;已有 PIN 的推送 RESET(携带旧 PIN 指纹)
批量重置 PINRESET要求被授权方都已存在 PIN,重置后逐条推送
批量清除 PINDELETE仅为本次命中并清除的被授权方推送;不存在的被授权方不推送

PIN 的查询(是否存在)、校验(比对 PIN)均不会触发回调。

2. 回调消息类型​

OperatePinPartner

3. 其他说明​

1)OperateType 取值

PIN 操作对应 OperateType说明
生成 PINGENERATEPIN 首次创建,CurPinCodeEncrypted 有值
重置 PINRESETPIN 被替换为新值,CurPinCodeEncrypted 与 PrevPinCodeEncrypted 均有值
清除 PINDELETEPIN 被清除(软删除),仅 PrevPinCodeEncrypted 有值

2)PinType 取值

PIN 场景PinType说明
员工个人EMPLOYEE子客员工在子客企业下的个人 PIN,回调给 PIN 归属子客企业
企业授权PARTNER子客企业间相互授权(含授权给他人 / 被他人邀请),回调给被授权方子客企业
个人自动签PERSONAL个人用户的自动签 PIN 授权给子客企业,回调给被授权方子客企业

3)字段省略

MsgData 中取值为空的字段不会出现在回调报文中(例如 GENERATE 场景没有 PrevPinCodeEncrypted,个人自动签场景没有授权方 OrganizationId 等字段)。请按"字段可能缺省"的方式解析。

4)推送时序

  • 回调为异步推送,与接口返回解耦:接口返回成功仅代表 PIN 已落库,回调可能有秒级延迟。
  • 一次批量操作涉及多个被授权方时,会逐条推送,可能收到多条回调。

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
PinTypeStringPIN 场景类型:
EMPLOYEE:员工个人
PARTNER:企业授权
PERSONAL:个人自动签
OperateTypeString本次 PIN 操作类型:
GENERATE:生成
RESET:重置
DELETE:清除
PinIdStringPIN 的唯一标识,为32位字符串。
重置不改变 PinId;清除后该 PinId 失效
UserIdString操作人(子客员工)的用户 ID。
EMPLOYEE、PERSONAL 场景返回
OpenIdString操作人在第三方平台的用户唯一标识,对应 Agent 结构体中的 ProxyOperatorOpenId。
EMPLOYEE、PERSONAL 场景返回
OrganizationIdStringPIN 归属子客企业(授权方企业)的企业 ID。
EMPLOYEE、PARTNER 场景返回
OrganizationOpenIdStringPIN 归属子客企业在第三方平台的唯一标识,对应 Agent 中的 ProxyOrganizationOpenId。
EMPLOYEE、PARTNER 场景返回
ApplicationIdStringPIN 归属子客企业使用的应用 ID,对应 Agent 中的 AppId。
EMPLOYEE、PARTNER 场景返回
ProxyApplicationIdStringPIN 归属子客企业的代理应用 ID,对应 Agent 中的 ProxyAppId。
EMPLOYEE、PARTNER 场景返回
AuthOrganizationIdString被授权方子客企业的企业 ID,即本次回调的接收方企业
AuthOrganizationOpenIdString被授权方子客企业在第三方平台的唯一标识
AuthApplicationIdString被授权方子客企业的应用 ID
AuthProxyApplicationIdString被授权方子客企业的代理应用 ID
CurPinCodeEncryptedString本次操作后 PIN 的加密字段。
GENERATE、RESET 场景返回;DELETE 场景不返回
PrevPinCodeEncryptedString本次操作前(旧)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 码验证失败0PIN 码校验未通过,可能是签署人重置了 PIN 码授权

FailReason 枚举从 0 开始,后续失败类型待定扩展,请按"未知枚举值需兼容"的方式解析。

2)字段省略

MsgData 中取值为空的字段不会出现在回调报文中(例如个人 PIN 码签场景没有 OrganizationName,合同不属于合同组时没有 FlowGroupId,签署方非第三方子客企业时没有 ProxyOrganizationOpenId、ProxyOperatorOpenId)。请按"字段可能缺省"的方式解析。

3)推送时序

  • 回调为异步推送,与签署动作解耦,可能有秒级延迟。
  • 请以 FlowId + RecipientId + FailReason 做幂等处理,避免因消息重投导致重复消费。

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString发起方企业在第三方平台的唯一标识,定义和 Agent 中的 ProxyOrganizationOpenId 一样,可以参考Agent结构体
FlowIdString合同流程 ID,为 32 位字符串
FlowGroupIdString合同组 ID。合同属于合同组时返回,非组内子合同该字段缺省
FailReasonInteger失败原因枚举:
0:PIN码验证失败
FailMessageString失败原因文案,FailReason 的可读描述,当前固定返回:PIN码验证失败
ApproverInfoApproverDetail签署失败的签署方信息,结构体的定义可以参考下面的ApproverDetail

ApproverDetail结构体定义

参数名称参数类型参数描述
RecipientIdString签署方的参与角色 ID,为 32 位字符串
SignIdString签署人签署区 ID,与查询合同详情接口返回的签署人 SignId 一致
ApproverTypeInteger签署人类型:
8:本方企业 PIN 码授权
9:他方企业 PIN 码授权
10:个人 PIN 码授权
OrganizationNameString签署方企业名称。个人 PIN 码签场景该字段缺省
ApproverNameString签署人姓名
ApproverMobileString签署人手机号(打码返回,如 185****0000)
ApproverIdCardTypeString签署人证件类型:
ID_CARD:中国大陆居民身份证
HONGKONG_AND_MACAO:中国港澳居民来往内地通行证
HONGKONG_MACAO_AND_TAIWAN:中国港澳台居民居住证(格式同居民身份证)
ApproverIdCardNumberString签署人证件号码(打码返回,仅保留首末位,如 1****************6)
ProxyOrganizationOpenIdString签署方企业在第三方平台的唯一标识。签署方为第三方子客企业时返回
ProxyOperatorOpenIdString签署方经办人在第三方平台的唯一标识,定义和 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"
}
}
}