跳到主要内容

老版授权签升级 PIN 码签署指南

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

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

改造范围​

只有过去使用自动签署(授权签)的签署方需要改造,手动签署方无需改造。
签署方类型是否需要改造说明
自动签署(授权签)方需要改造需改 ApproverType 并新增 PinCode 字段
手动签署方无需改造企业 0、个人 1 均保持不变,不涉及 PIN 码

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

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


一. 升级前后对照​

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

场景升级前升级后
本方(己方)企业授权签38
合作方(他方)企业授权签39
个人授权签(电子处方单,白名单能力)710(详见第五节)
手动签署方(企业 / 个人)0 / 1无需改造,保持原值,不涉及 PinCode

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

表中前三项是授权签,需要改造;最后一项是手动签署方,不用改。判断依据是原 `ApproverType`:填 `3` / `7` 的按上表替换并补 `PinCode`;填 `0`(企业手动签)、`1`(个人手动签)的原样保留,既不用改类型也不用传 `PinCode`。详见[改造范围](#改造范围)。

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

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

二. 接口改造示例​

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

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 码相关回调 推送通知。建议接入,以便及时感知变更:

字段说明
OperateTypeGENERATE 生成 / RESET 重置 / DELETE 清除
PinTypeEMPLOYEE 员工个人 / PARTNER 企业授权 / PERSONAL 个人自动签
PinIdPIN 唯一标识,重置不改变,清除后失效
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 算出来不对,怎么排查?​

按以下顺序检查:

  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:升级后是否还能用 ApproverType = 3?​

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


八. 相关文档​