老版授权签升级 PIN 码签署指南
本文档面向已接入授权签(旧称"自动签署")的自建应用集成客户,说明如何升级到 PIN 码签署。
如果您是第三方应用集成(渠道 API)客户,请参见授权签升级 PIN 码签署指南(第三方应用)。
改造范围
只有过去使用自动签署(授权签)的签署方需要改造,手动签署方无需改造。| 签署方类型 | 是否需要改造 | 说明 |
|---|---|---|
| 自动签署(授权签)方 | 需要改造 | 需改 ApproverType 并新增 PinCode 字段 |
| 手动签署方 | 无需改造 | 企业 0、个人 1 均保持不变,不涉及 PIN 码 |
判断方法:看签署方结构体里的
ApproverType。原来填3(企业授权签)或7(个人授权签)的签署方需要改;填0(企业手动签)、1(个人手动签)的保持原样。同一份合同里两种签署方可以并存,只改授权签那一部分。
升级要改两处:把原来单一的"授权签"类型按本方、他方拆成两个新类型,并给授权签签署方补上必填的 PinCode(用授权的 PIN 码加合同名称算出签署校验码,随发起接口一起传入)。
一. 升级前后对照
自建应用集成的 ApproverType 是数字枚举,升级后取值如下:
| 场景 | 升级前 | 升级后 |
|---|---|---|
| 本方(己方)企业授权签 | 3 | 8 |
| 合作方(他方)企业授权签 | 3 | 9 |
| 个人授权签(电子处方单,白名单能力) | 7 | 10(详见第五节) |
| 手动签署方(企业 / 个人) | 0 / 1 | 无需改造,保持原值,不涉及 PinCode |
升级前本方与他方共用
3,升级后用8、9区分。
表中前三项是授权签,需要改造;最后一项是手动签署方,不用改。判断依据是原 `ApproverType`:填 `3` / `7` 的按上表替换并补 `PinCode`;填 `0`(企业手动签)、`1`(个人手动签)的原样保留,既不用改类型也不用传 `PinCode`。详见[改造范围](#改造范围)。
授权签签署方还要新增一个必填字段:
| 字段 | 类型 | 说明 |
|---|---|---|
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": "92d3ff4c034bca783f4de87e6058a80e57ce956cafa9aae16318587b5603e00a", // 由授权方 PIN 码与 FlowName 计算得出(非明文 PIN 码)
"SignComponents": [ /* 印章控件,略 */ ]
// 其他参数省略
}
],
"FileIds": ["yDCHNUUckpauk4nsUuGS8n5wk5WSg6Fh"]
}
2. 模板发起(CreateFlow)
升级前:
{
"Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
"FlowName": "本企业自己的授权签合同",
"Approvers": [
{
"ApproverType": 3,
"OrganizationName": "典子谦示例企业"
// 其他参数省略
}
]
}
升级后:
{
"Operator": { "UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn" },
"FlowName": "本企业自己的授权签合同",
"Approvers": [
{
"ApproverType": 8,
"OrganizationName": "典子谦示例企业",
"PinCode": "3236dae7c96713848a8f937c5c9276d4a5b6467aadea4055b166da8a74ab62ee" // 由授权方 PIN 码与 FlowName 计算得出(非明文 PIN 码)
// 其他参数省略
}
]
}
模板发起流程中的 CreateDocument、StartFlow 两步不用改,改动只在 CreateFlow 的签署方结构体。
3. 合作方(他方)授权签
升级前:
"Approvers": [{
"ApproverType": 3,
"OrganizationName": "张三示例企业"
// 其他参数省略
}]
升级后:
"Approvers": [{
"ApproverType": 9,
"OrganizationName": "张三示例企业",
"PinCode": "145ce2f43a525f1bfcb28101ea42d67fb33fb2d45814c842887d0e9b3d48f397" // 由授权方 PIN 码与 FlowName 计算得出(非明文 PIN 码)
// 其他参数省略
}]
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": "61fc8633d0fb9e576b087a95ce997655f5df42ba91526bc7c1b99d8f88d5eb51" /* 由 PIN 码与 FlowName 计算得出(非明文 PIN 码);其他参数省略 */ }
]
}
他方授权签
升级前:
{
"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": "164b22d4ce143b13b80a48b9418efb09b6807c037c90b923c322e56357f11763" /* 由 PIN 码与 FlowName 计算得出(非明文 PIN 码);其他参数省略 */ }
]
}
- 嵌入页面发起的他方授权签取值与合作方(他方)授权签相同,均为
9。OrganizationName填他方企业名称;他方已授权的授权签印章在预发起页面中选择。- 本方与他方的
PinCode取自各自授权方的 PIN 码,不要混用。
三. 计算 PinCode
PinCode 的计算规则与各语言(Java、Go、Python、PHP、Node.js)示例代码,请直接使用 PIN码计算助手:
- 在线输入 PIN 码与合同名称,即时得到
PinCode,可用于比对自测结果。 - 提供 Java、Go、Python、PHP、Node.js 五种语言的计算示例代码,可直接复制接入。
- 计算全程在浏览器本地完成,数据不会上传。
四. 升级前准备
1. 获取 PIN 码
PIN 码由授权方在控制台设置后提供给被授权方,发起合同前必须拿到。
重点:本方「一人一码」,他方「一企业一码」本方(己方)企业授权签,每个被授权的员工各自持有一个独立 PIN 码,互不通用。本方授权签的签署人默认为发起合同的经办人,所以 谁来做自动签署,就用谁的 PIN 码计算
PinCode。拿 A 员工的 PIN 码去发起以 B 员工为经办人的合同,PinCode校验会失败。合作方(他方)企业授权签则是另一套:他方企业的 PIN 码由授权方(他方)企业设置,同一个他方企业共用一个 PIN 码,不区分具体经办人、模板或印章。无论本方由哪个员工发起,指向同一他方企业的授权签都用同一个
PinCode输入值。若合同涉及多个他方企业,分别取各自企业的 PIN 码,不要混用。
| 场景 | 设置入口 | 说明 |
|---|---|---|
| 本方企业员工 | 更多 > 高级签署能力 > 企业授权签署 > 员工 PIN 码设置 | 本企业超管设置,供本企业员工发起授权签时使用 |
| 合作方企业 | 更多 > 高级签署能力 > 企业授权签署 > 管理 > 我给合作方授权 | 授权方超管设置后提供给被授权方 |
PIN 码的获取位置
本方(己方)自动签署:由对应的员工本人登录电子签控制台获取自己的 PIN 码(谁自动签署就用谁的 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": "6f19004f8fb57da6aba7860eda92e9df4178eb5ed34053329f5d559871032e9f", // 由授权方 PIN 码与 FlowName 计算得出(非明文 PIN 码)
"SignComponents": [ /* 签名控件,略 */ ]
// 其他参数省略
}]
其余入参不变,包括 AutoSignScene 固定为 E_PRESCRIPTION_AUTO_SIGN、患者方 ApproverType 为 1 等。
注意:个人授权签为白名单能力,使用前请联系对接的客户经理。
六. 升级检查清单
- 确认授权方已设置 PIN 码,并已获取到 32 位 PIN 码
- 本方授权签确认用的是发起经办人本人的 PIN 码(一人一码,不可串用)
- 他方授权签确认用的是该他方企业的 PIN 码;多个他方企业分别取各自 PIN 码
- 本方授权签
ApproverType由3改为8 - 合作方授权签
ApproverType由3改为9 - 梳理全部发起接口,确认只改造原 `3` / `7` 的授权签签署方;手动签(`0` / `1`)保持不变
- 个人授权签(电子处方单)
ApproverType由7改为10 - 所有授权签签署方补充
PinCode字段 - 确认
PinCode使用去除前后空格后的FlowName计算,且与发起入参的FlowName一致 - 确认 HMAC 的 key 用的是 SHA-256 的十六进制字符串而非原始字节
- 接入 PIN 码相关回调,感知 PIN 码变更
- 联调验证:本方授权签、合作方授权签各跑通一次
七. 常见问题
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 码签署场景。