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. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​