升级 PIN 码签指南

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

如果您是第三方应用集成（渠道 API）客户，请参见授权签升级 PIN 码签署指南（第三方应用）。

改造范围

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

签署方类型	是否需要改造	说明
自动签署（授权签）方	需要改造	需改 `ApproverType` 并新增 `PinCode` 字段
手动签署方	无需改造	企业 `0`、个人 `1` 均保持不变，不涉及 PIN 码

判断方法：看签署方结构体里的 ApproverType。原来填 3（企业授权签）或 7（个人授权签）的签署方需要改；填 0（企业手动签）、1（个人手动签）的保持原样。同一份合同里两种签署方可以并存，只改授权签那一部分。

升级要改两处：把原来单一的"授权签"类型按本方、他方拆成两个新类型，并给授权签签署方补上必填的 PinCode（用授权的 PIN 码加合同名称算出签署校验码，随发起接口一起传入）。

一. 升级前后对照

自建应用集成的 ApproverType 是数字枚举，升级后取值如下：

场景	升级前	升级后
本方（己方）企业授权签	`3`	`8`
合作方（他方）企业授权签	`3`	`9`
个人授权签（电子处方单，白名单能力）	`7`	`10`（详见第五节）

升级前本方与他方共用 3，升级后用 8、9 区分。

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

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

二. 接口改造示例

以下对照均取自实际请求体，仅保留与授权签相关的字段。

1. 文件发起（CreateFlowByFiles）

升级前：

{
  "Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
  "FlowName": "西红柿采购合同（20240807）",
  "Approvers": [
    {
      "ApproverType": 3,
      "OrganizationName": "典子谦示例企业",
      "SignComponents": [ /* 印章控件，略 */ ]
      // 其他参数省略
    }
  ],
  "FileIds": ["yDCHNUUckpauk4nsUuGS8n5wk5WSg6Fh"]
}

升级后：

{
  "Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
  "FlowName": "西红柿采购合同（20240807）",
  "Approvers": [
    {
      "ApproverType": 8,
      "OrganizationName": "典子谦示例企业",
      "PinCode": "签署校验码",
      "SignComponents": [ /* 印章控件，略 */ ]
      // 其他参数省略
    }
  ],
  "FileIds": ["yDCHNUUckpauk4nsUuGS8n5wk5WSg6Fh"]
}

2. 模板发起（CreateFlow）

升级前：

{
  "Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
  "FlowName": "本企业自己的授权签合同",
  "Approvers": [
    {
      "ApproverType": 3,
      "OrganizationName": "典子谦示例企业"
      // 其他参数省略
    }
  ]
}

升级后：

{
  "Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
  "FlowName": "本企业自己的授权签合同",
  "Approvers": [
    {
      "ApproverType": 8,
      "OrganizationName": "典子谦示例企业",
      "PinCode": "签署校验码"
      // 其他参数省略
    }
  ]
}

模板发起流程中的 CreateDocument、StartFlow 两步不用改，改动只在 CreateFlow 的签署方结构体。

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

升级前：

"Approvers": [{
  "ApproverType": 3,
  "OrganizationName": "张三示例企业"
  // 其他参数省略
}]

升级后：

"Approvers": [{
  "ApproverType": 9,
  "OrganizationName": "张三示例企业",
  "PinCode": "签署校验码"
  // 其他参数省略
}]

4. 嵌入页面发起（CreatePrepareFlow）

嵌入页面发起同时支持本方与他方授权签，取值与前面一致：本方 8、他方 9。

本方授权签

升级前：

{
  "Operator": { "UserId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxxYj" },
  "Unordered": true,
  "FlowName": "嵌入式合同-本方授权签",
  "ResourceId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxx6d",
  "ResourceType": 2,
  "FlowType": "1",
  "Approvers": [
    { "ApproverType": 3, "OrganizationName": "张三示例企业" /* 其他参数省略 */ }
  ]
}

升级后：

{
  "Operator": { "UserId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxxYj" },
  "Unordered": true,
  "FlowName": "嵌入式合同-本方授权签",
  "ResourceId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxx6d",
  "ResourceType": 2,
  "FlowType": "1",
  "Approvers": [
    { "ApproverType": 8, "OrganizationName": "张三示例企业", "PinCode": "签署校验码" /* 其他参数省略 */ }
  ]
}

他方授权签

升级前：

{
  "Operator": { "UserId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxxYj" },
  "Unordered": true,
  "FlowName": "嵌入式合同-他方授权签",
  "ResourceId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxx6d",
  "ResourceType": 2,
  "FlowType": "1",
  "Approvers": [
    { "ApproverType": 3, "OrganizationName": "李四示例企业" /* 其他参数省略 */ }
  ]
}

升级后：

{
  "Operator": { "UserId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxxYj" },
  "Unordered": true,
  "FlowName": "嵌入式合同-他方授权签",
  "ResourceId": "yDxxxxxxxxxxxxxxxxxxxxxxxxxxxx6d",
  "ResourceType": 2,
  "FlowType": "1",
  "Approvers": [
    { "ApproverType": 9, "OrganizationName": "李四示例企业", "PinCode": "签署校验码" /* 其他参数省略 */ }
  ]
}

嵌入页面发起的他方授权签取值与合作方（他方）授权签相同，均为 9。
OrganizationName 填他方企业名称；他方已授权的授权签印章在预发起页面中选择。
本方与他方的 PinCode 取自各自授权方的 PIN 码，不要混用。

三. 计算 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码计算助手可以线上算 PinCode，也能直接取用示例代码：

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

算出来对不上时，先回头核对上面的易错点：HMAC 的 key 用 SHA-256 的十六进制字符串，合同名称要去除前后空格。

四. 升级前准备

1. 获取 PIN 码

PIN 码由授权方在控制台设置后提供给被授权方，发起合同前必须拿到。

重点：本方「一人一码」，他方「一企业一码」
本方（己方）企业授权签，每个被授权的员工各自持有一个独立 PIN 码，互不通用。本方授权签的签署人默认为发起合同的经办人，所以谁来做自动签署，就用谁的 PIN 码计算 PinCode。拿 A 员工的 PIN 码去发起以 B 员工为经办人的合同，PinCode 校验会失败。
合作方（他方）企业授权签则是另一套：他方企业的 PIN 码由授权方（他方）企业设置，同一个他方企业共用一个 PIN 码，不区分具体经办人、模板或印章。无论本方由哪个员工发起，指向同一他方企业的授权签都用同一个 PinCode 输入值。若合同涉及多个他方企业，分别取各自企业的 PIN 码，不要混用。

场景	设置入口	说明
本方企业员工	更多 > 高级签署能力 > 企业授权签署 > 员工 PIN 码设置	本企业超管设置，供本企业员工发起授权签时使用
合作方企业	更多 > 高级签署能力 > 企业授权签署 > 管理 > 我给合作方授权	授权方超管设置后提供给被授权方

几条约束：

PIN 码由系统生成，为 32 位字母数字组合，不支持自定义。
仅当次展示，不可查看；遗忘只能重置。
同一合作方企业的所有授权（按模板、按印章）共用 1 个 PIN 码。
重置后旧 PIN 码立即失效，进行中、未签署的合同将失效，请谨慎操作。

2. 监听 PIN 码变更回调

PIN 码被生成、重置、清除时，电子签会通过 PIN 码相关回调推送通知。建议接入，以便及时感知变更：

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

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

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

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

该场景在医师授权流程中会一并完成 PIN 码设置，详见电子处方单中"医师完成授权"的第 3.5 步。

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

升级前：

"Approvers": [{
  "ApproverType": 7,
  "ApproverName": "刘波",
  "ApproverIdCardType": "ID_CARD",
  "ApproverIdCardNumber": "370222200002022222",
  "ApproverMobile": "18500000000",
  "SignComponents": [ /* 签名控件，略 */ ]
  // 其他参数省略
}]

升级后：

"Approvers": [{
  "ApproverType": 10,
  "ApproverName": "刘波",
  "ApproverIdCardType": "ID_CARD",
  "ApproverIdCardNumber": "370222200002022222",
  "ApproverMobile": "18500000000",
  "PinCode": "签署校验码",
  "SignComponents": [ /* 签名控件，略 */ ]
  // 其他参数省略
}]

其余入参不变，包括 AutoSignScene 固定为 E_PRESCRIPTION_AUTO_SIGN、患者方 ApproverType 为 1 等。

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

六. 升级检查清单

七. 常见问题

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

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

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

按以下顺序检查：

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

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

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

不能。本方每个员工有自己单独的 PIN 码，且授权签的签署人默认为发起合同的经办人，所以只能用该经办员工本人的 PIN 码计算 PinCode，换人就会校验失败。

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

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

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

Q5：升级后是否还能用 `ApproverType = 3`？

不能。8、9 分别对应本方、他方，3 不再适用于 PIN 码签署场景。

改造范围​

一. 升级前后对照​

二. 接口改造示例​

1. 文件发起（CreateFlowByFiles）​

2. 模板发起（CreateFlow）​

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

4. 嵌入页面发起（CreatePrepareFlow）​

本方授权签​

他方授权签​

三. 计算 PinCode​

1. 计算公式​

2. 计算与校验工具​

四. 升级前准备​

1. 获取 PIN 码​

2. 监听 PIN 码变更回调​

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

六. 升级检查清单​

七. 常见问题​

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

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

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

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

Q5：升级后是否还能用 ApproverType = 3？​

八. 相关文档​

改造范围

一. 升级前后对照

二. 接口改造示例

1. 文件发起（CreateFlowByFiles）

2. 模板发起（CreateFlow）

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

4. 嵌入页面发起（CreatePrepareFlow）

本方授权签

他方授权签

三. 计算 PinCode

1. 计算公式

2. 计算与校验工具

四. 升级前准备

1. 获取 PIN 码

2. 监听 PIN 码变更回调

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

六. 升级检查清单

七. 常见问题

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

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

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

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

Q5：升级后是否还能用 `ApproverType = 3`？

八. 相关文档