升级 PIN 码签指南

本文档面向已接入授权签（旧称"自动签署"）的第三方应用集成（渠道 API）客户，说明如何升级到PIN 码签署。

如果您是自建应用集成（企业 API）客户，请参见授权签升级 PIN 码签署指南（自建应用）。

改造范围

只有过去使用自动签署（授权签）的签署方需要改造，手动签署方无需改造。

签署方类型	是否需要改造	说明
自动签署（授权签）方	需要改造	需改 ApproverType 并新增 PinCode 字段
手动签署方	无需改造	ORGANIZATION、PERSON 保持不变，不涉及 PIN 码

判断方法：读签署方结构体里的 ApproverType。原来填 PERSON_AUTO_SIGN（个人授权签）、本方授权签的 ORGANIZATION 或 ENTERPRISESERVER、他方授权签的 ENTERPRISESERVER，这几类要改。手动签的 ORGANIZATION、PERSON 保持原样。同一份合同里两种签署方可以并存，只改授权签那一部分。

升级要做两件事：

1. 改 ApproverType：授权签的参与方式换成带 PIN_CODE_SIGN 后缀的新枚举。
2. 补 PinCode：用授权方 PIN 码和合同名称算出签署校验码，随发起接口传入。

---

一. 升级前后对照

第三方应用集成的 ApproverType 是字符串枚举，按下表替换：

场景	升级前	升级后
本方（己方）企业授权签	ORGANIZATION（模板发起） ENTERPRISESERVER（文件发起）	ORGANIZATION_PIN_CODE_SIGN
合作方（他方）企业授权签	ENTERPRISESERVER	OTHER_ORGANIZATION_PIN_CODE_SIGN
个人授权签（电子处方单，白名单能力）	PERSON_AUTO_SIGN	PERSON_PIN_CODE_SIGN（详见第五节）

授权签签署方还要新增一个必填字段：

字段	类型	说明
PinCode	String	签署校验码，计算方式见第三节。升级前无此字段。

注意：升级前本方授权签的枚举不统一，模板发起用 ORGANIZATION、文件发起用 ENTERPRISESERVER。升级后统一为 ORGANIZATION_PIN_CODE_SIGN，不再区分发起方式。按发起方式分支赋值的逻辑可以合并。

---

二. 接口改造示例

示例取自实际请求体，只保留与授权签相关的字段。

1. 模板发起（CreateFlowsByTemplates）

升级前：

{
  "Agent": {
    "AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperator": { "OpenId": "n9527" }
  },
  "FlowInfos": [{
    "FlowName": "小狗买卖合同(15:15:35)",
    "TemplateId": "yDCHZUUckpa92gkgUEGCHIpxTXEX7JWe",
    "FlowApprovers": [{
      "ApproverType": "ORGANIZATION",
      "RecipientId": "yDCHZUUckpa98oi9Uuc3g1LBvOjPT147"
      // 其他参数省略
    }]
  }]
}

升级后：

{
  "Agent": {
    "AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperator": { "OpenId": "n9527" }
  },
  "FlowInfos": [{
    "FlowName": "小狗买卖合同(15:15:35)",
    "TemplateId": "yDCHZUUckpa92gkgUEGCHIpxTXEX7JWe",
    "FlowApprovers": [{
      "ApproverType": "ORGANIZATION_PIN_CODE_SIGN",
      "PinCode": "签署校验码",
      "RecipientId": "yDCHZUUckpa98oi9Uuc3g1LBvOjPT147"
      // 其他参数省略
    }]
  }]
}

2. 文件发起（ChannelCreateFlowByFiles）

升级前：

"FlowApprovers": [{
  "OrganizationName": "典子谦示例企业",
  "ApproverType": "ENTERPRISESERVER",
  "SignComponents": [ /* 印章控件，略 */ ]
  // 其他参数省略
}]

升级后：

"FlowApprovers": [{
  "OrganizationName": "典子谦示例企业",
  "ApproverType": "ORGANIZATION_PIN_CODE_SIGN",
  "PinCode": "签署校验码",
  "SignComponents": [ /* 印章控件，略 */ ]
  // 其他参数省略
}]

3. 合作方（他方）授权签

升级前：

"FlowApprovers": [{
  "OrganizationName": "益达呱呱的子客",
  "OrganizationOpenId": "org_guagua",
  "ApproverType": "ENTERPRISESERVER"
  // 其他参数省略
}]

升级后：

"FlowApprovers": [{
  "OrganizationName": "益达呱呱的子客",
  "OrganizationOpenId": "org_guagua",
  "ApproverType": "OTHER_ORGANIZATION_PIN_CODE_SIGN",
  "PinCode": "签署校验码"
  // 其他参数省略
}]

4. 混合场景（本方授权签 + 他方授权签）

升级前：

"FlowApprovers": [
  {
    "OrganizationName": "典子谦示例企业",
    "OpenId": "ggboud",
    "OrganizationOpenId": "org_dianziqian",
    "ApproverType": "ORGANIZATION",
    "RecipientId": "yDCHZUUckpa98oi9Uuc3g1LBvOjPT147"
    // 其他参数省略
  },
  {
    "OrganizationName": "益达呱呱的子客",
    "OrganizationOpenId": "org_guagua",
    "ApproverType": "ENTERPRISESERVER",
    "RecipientId": "yDCHZUUckpa98oixUuc3g1LE93SM8QeS"
    // 其他参数省略
  }
]

升级后：

"FlowApprovers": [
  {
    "OrganizationName": "典子谦示例企业",
    "OpenId": "ggboud",
    "OrganizationOpenId": "org_dianziqian",
    "ApproverType": "ORGANIZATION_PIN_CODE_SIGN",
    "PinCode": "签署校验码",
    "RecipientId": "yDCHZUUckpa98oi9Uuc3g1LBvOjPT147"
    // 其他参数省略
  },
  {
    "OrganizationName": "益达呱呱的子客",
    "OrganizationOpenId": "org_guagua",
    "ApproverType": "OTHER_ORGANIZATION_PIN_CODE_SIGN",
    "PinCode": "签署校验码",
    "RecipientId": "yDCHZUUckpa98oixUuc3g1LE93SM8QeS"
    // 其他参数省略
  }
]

注意：本方与他方的 PinCode 取自各自授权方的 PIN 码，不要混用。

5. 嵌入页面发起（获取发起合同嵌入链接）

嵌入页面发起同时支持本方与他方授权签，取值与前面一致：本方 ORGANIZATION_PIN_CODE_SIGN、他方 OTHER_ORGANIZATION_PIN_CODE_SIGN，不再区分模板发起与文件发起。

本方授权签

升级前：

"FlowApprovers": [{
  "OrganizationName": "典子谦示例企业",
  "OpenId": "ggboud",
  "OrganizationOpenId": "org_dianziqian",
  "ApproverType": "ORGANIZATION"
  // 其他参数省略
}]

升级后：

"FlowApprovers": [{
  "OrganizationName": "典子谦示例企业",
  "OpenId": "ggboud",
  "OrganizationOpenId": "org_dianziqian",
  "ApproverType": "ORGANIZATION_PIN_CODE_SIGN",
  "PinCode": "签署校验码"
  // 其他参数省略
}]

他方授权签

升级前：

"FlowApprovers": [{
  "OrganizationName": "益达呱呱的子客",
  "OrganizationOpenId": "org_guagua",
  "ApproverType": "ENTERPRISESERVER"
  // 其他参数省略
}]

升级后：

"FlowApprovers": [{
  "OrganizationName": "益达呱呱的子客",
  "OrganizationOpenId": "org_guagua",
  "ApproverType": "OTHER_ORGANIZATION_PIN_CODE_SIGN",
  "PinCode": "签署校验码"
  // 其他参数省略
}]

---

三. 计算 PinCode

1. 计算公式

PinCode = HEX(HMAC_SHA256(HEX(SHA256(对方授权的 PIN 码)), (合同名称)))

参数	说明
对方授权的 PIN 码	授权方设置的 PIN 码，32 位字母数字组合
合同名称	签署流程名称，即发起接口中的 FlowName，需去除前后空格
HEX(SHA256(...))	SHA-256 摘要后的小写十六进制字符串（64 位），作为 HMAC 的 key
HMAC_SHA256(key, message)	key 为上述十六进制字符串，message 为合同名称，输出小写十六进制

易错点：HMAC 的 key 是 SHA-256 结果的十六进制字符串（64 个字符），不是原始的 32 字节摘要。两者算出的 PinCode 完全不同。

2. 各语言示例

各语言的计算示例与在线校验，请直接使用 PIN码计算助手：

• 在线输入 PIN 码与合同名称，即时得到 PinCode，可用于比对自测结果。
• 提供 Java、Go、Python、PHP、Node.js 五种语言的计算示例代码，可直接复制接入。
• 计算全程在浏览器本地完成，数据不会上传。

---

四. 升级前准备

1. 获取 PIN 码

授权方设置 PIN 码后提供给被授权方。发起合同前先拿到。

重点：本方「一人一码」，他方「一企业一码」

本方（己方）子客企业授权签：每个员工一个 PIN 码

• 子客企业里每个被授权的员工各自持有一个 PIN 码，互不通用。
• 谁做自动签署，就用谁的 PIN 码计算 `PinCode`。本方授权签的签署人默认为发起合同的经办人，取该经办员工的 PIN 码。
• 用 A 员工的 PIN 码发起以 B 员工为经办人的合同，PinCode 校验失败。

合作方（他方）企业授权签：同一企业共用一个 PIN 码

• 他方企业在自己的控制台设置 PIN 码，同一企业共用，不区分经办人、模板或印章。
• 无论本方哪个员工发起，指向同一他方企业的授权签都用同一个 PIN 码。
• 合同涉及多个他方企业时，分别取各自企业的 PIN 码，不要混用。

场景	设置入口	说明
本方企业员工	通过生成子客登录链接生成员工登录链接，员工登录后到 企业中心 > 拓展服务 > 企业授权签署 > 员工PIN码设置	子客企业设置，供本企业员工发起授权签时使用
合作方企业	合作方（他方）企业在其控制台的 我给合作方授权 中设置	授权方超管设置后提供给被授权方

关键约束：

• 系统生成 PIN 码，32 位字母数字组合，不支持自定义。
• PIN 码仅当次展示，无法再次查看；遗忘只能重置。
• 重置后旧 PIN 码立即失效，进行中、未签署的合同将失效。

2. 监听 PIN 码变更回调

生成、重置或清除 PIN 码时，电子签会通过PIN 码相关回调推送通知。接入后可在 PIN 码变更时及时更新本地使用的 PIN 码，避免拿旧值去算 PinCode：

字段	说明
OperateType	GENERATE 生成 / RESET 重置 / DELETE 清除
PinType	EMPLOYEE 员工个人 / PARTNER 企业授权 / PERSONAL 个人自动签
PinId	PIN 唯一标识，重置不改变，清除后失效
CurPinCodeEncrypted	操作后 PIN 的加密字段
PrevPinCodeEncrypted	操作前（旧）PIN 的加密字段

回调为异步推送，请以 PinId + OperateType 做幂等处理。

---

五. 个人授权签（电子处方单）场景

电子处方单场景的医师授权签，ApproverType 由 PERSON_AUTO_SIGN 改为 PERSON_PIN_CODE_SIGN，同样需新增 PinCode 字段。

医师在授权流程中设置 PIN 码，步骤见电子处方单中"医师完成授权"部分。

改造示例（用PDF文件创建签署流程）：

升级前：

"FlowApprovers": [{
  "Name": "刘波",
  "IdCardType": "ID_CARD",
  "IdCardNumber": "370222200002022222",
  "Mobile": "18500000000",
  "ApproverType": "PERSON_AUTO_SIGN",
  "SignComponents": [ /* 签名控件，略 */ ]
  // 其他参数省略
}]

升级后：

"FlowApprovers": [{
  "Name": "刘波",
  "IdCardType": "ID_CARD",
  "IdCardNumber": "370222200002022222",
  "Mobile": "18500000000",
  "ApproverType": "PERSON_PIN_CODE_SIGN",
  "PinCode": "签署校验码",
  "SignComponents": [ /* 签名控件，略 */ ]
  // 其他参数省略
}]

其余入参（AutoSignScene 固定为 E_PRESCRIPTION_AUTO_SIGN、患者方 ApproverType 为 PERSON 等）不变。

注意：个人授权签为白名单能力，使用前请联系对接的客户经理沟通。

---

六. 升级检查清单

• 已拿到授权方设置的 32 位 PIN 码
• 本方授权签用的是发起经办人本人的 PIN 码（一人一码，不可串用）
• 他方授权签用的是该他方企业的 PIN 码；多个他方企业分别取各自 PIN 码
• 本方授权签改为 ORGANIZATION_PIN_CODE_SIGN（模板、文件、嵌入页面发起统一）
• 合作方授权签改为 OTHER_ORGANIZATION_PIN_CODE_SIGN
• 梳理全部发起接口，只改造授权签签署方；手动签（`ORGANIZATION` / `PERSON`）保持不变
• 个人授权签（电子处方单）改为 PERSON_PIN_CODE_SIGN
• 合并按发起方式分支赋值 ORGANIZATION / ENTERPRISESERVER 的逻辑
• 所有授权签签署方补充 PinCode 字段
• PinCode 用去除前后空格后的 FlowName 计算，且与发起入参的 FlowName 一致
• HMAC 的 key 用的是 SHA-256 的十六进制字符串而非原始字节
• 接入 PIN 码相关回调，感知 PIN 码变更
• 联调验证：本方授权签、合作方授权签各跑通一次

---

七. 常见问题

Q1：升级后不传 PinCode 会怎样？

PinCode 是 PIN 码签署场景的必填字段，缺失会导致发起失败。

Q2：PinCode 算出来不对，怎么排查？

按以下顺序检查：

1. HMAC 的 key 是否为 SHA-256 结果的小写十六进制字符串（64 字符），而非原始 32 字节。
2. 合同名称是否与发起入参的 FlowName 完全一致，且已去除前后空格。
3. PIN 码是否为 32 位，有无复制时混入空格或换行。
4. 本方 / 他方是否用对了各自授权方的 PIN 码。

可先用 PIN码计算助手 工具比对结果。

Q3：本方授权签能用其他员工的 PIN 码吗？

不能。本方每个员工有自己单独的 PIN 码，授权签的签署人默认为发起合同的经办人，必须用该经办员工本人的 PIN 码计算 PinCode。

他方授权签不同：同一他方企业共用 1 个 PIN 码，与本方经办人是谁无关。详见第四节。

Q4：PIN 码重置后，存量合同受影响吗？

受影响。重置后旧 PIN 码立即失效，进行中、未签署的合同将失效，需重新发起。

Q5：升级前为什么模板和文件发起用的枚举不一样？

升级前模板发起用 ORGANIZATION、文件发起用 ENTERPRISESERVER。升级后统一为 ORGANIZATION_PIN_CODE_SIGN，不再区分发起方式。

Q6：个人“授权签”（处方单）的枚举也变了吗？

变了。PERSON_AUTO_SIGN 改为 PERSON_PIN_CODE_SIGN，同样需新增 PinCode 字段，详见第五节。

---

八. 相关文档

• 授权签使用说明
• 电子处方单
• PIN 码相关回调
• 通过文件发起签署流程
• 通过模板发起签署流程
• PIN码计算助手