信手书小程序用户手册

1. 产品简介

1.1北京CA云签名平台（简称信步云）是基于移动终端和云服务平台建立能够向第三方提供服务的、安全的、开放的电子签名平台。该平台面向所有互联网业务系统提供身份认证、数据签名等服务。

云签名SDK是信步云系统中重要组成部分，是为移动终端App提供集成信步云签名业务功能的客户端开发包。移动终端App通过集成云签名SDK，可以使用信步云系统完成认证、签名、签章等云签名功能，同时也可以使用云签名SDK实现证书解析等数字证书操作功能。

2. 产品使用

2.1 如何使用接口产品

2.1.1 使用接口的准备工作

小程序插件下载证书的激活码需要业务方向信步云网关申请，具体详情请咨询项目经理。首先小程序先根据自己的appId和secret和后台交互获得openId，引用组件时作为参数传给小程序插件

注意：由于在微信小程序中，原生组件的层级是最高的，页面中的其他组件无论设置 z-index 为多少，都无法盖在原生组件上（参考小程序开发文档：https: //developers.weixin.qq.com/miniprogram/dev/component/native-component.html ），所以口令输入框下方若有原生组件（如textarea等）可能导致无法正常输入口令

2.1.2 产品部署流程

搜索“云签名组件”申请使用权限，等待申请通过之后，在使用者小程序中调用即可

2.1.3 接口的调用

环境地址说明：微信小程序插件由于配置地址受微信管理限制，因此不采用不同客户不同域名的模式。

按照目前信步云业务的部署环境和接入模式，确定信步云微信小程序插件支持以下三个环境的接入地址：

1、信步云联调测试环境（Dev）：https: //api-sit.isignet.cn:8443 供各业务系统联调测试使用

2、信步云公有云正式环境：https: //plug-in.isignet.cn:8443 接入阿里云系统正式上线环境

3、信步云政务云正式环境：https: //bjzw.isignet.cn 接入政务云系统正式上线环境

（未来有其他分离的云环境需要支持，由运维确认地址后统一添加。）

注：正式环境要正式环境的激活码,签名任务,appid和url，集成环境要集成环境的激活码,签名任务,appid和url，不同环境之间的调用是不通的。

组件引用时证书下载组件cert和签名组件sign，以标签形式在小程序中使用即和，参数以s_的形式传递

2.1.4 证书下载组件

以标签形式引入证书下载组件，以s_形式传递参数，需要传递的参数有

激活码（s_authcode）、应用ID （s_appId）、openid（s_openId）、云签名服务的地址（s_global）、是否显示隐私协议（s_showAgreement）。

1、需要绑定5个方法以（bind:方法名）的形式绑定，5个方法名分别是action、certresult、handleError、getDeviceId、getCertRes，

即绑定方式为:

bind:action=”你自己的方法名”；

bind:certresult=”你自己的方法名”；

bind:handleError=”你自己的方法名”；

bind:getCertRes=”你自己的方法名”；

bind:getCertRes=”你自己的方法名”。

bind:action绑定的方法是下载证书成功后返回的msspid返回参数是msspId（需要保存下来，签名是需要用），

bind:certresult绑定的方法是下载证书成功后需要做的操作比如跳转回小程序的某个页面等，

bind:handleError绑定的方法是错误码返回，返回参数是errorCod，具体见第四章错误码说明。新增加获取deviceId功能bind:getDeviceId=”getDeviceIdRes”绑定的方法返回参数是deviceId。bind:getCertRes=”getCertResArr”绑定的方法是获取下载成功的证书。

综上 证书下载引用方式举例为：

​	<cert 

bind:action="selectItemDetail" 

bind:getDeviceId="getDeviceIdRes" 

bind:getCertRes="getCertResArr" 

bind:handleError="getErrorCode" 

bind:certresult="resultsuccess" 

s_authcode="{{authcode}}" 

s_appId="{{appId}}" 

s_openId="{{openId}}" 

s_global="{{globalUrl}}" 

s_showAgreement="{{showAgreement}}" />

2.1.5 签名组件

1、以标签形式引入证书下载组件，以s_形式传递参数，需要传递的参数有

签名任务id（s_signId）、msspid（s_msspID）（下载证书成功后返回的）、应用ID （s_appId）、openid（s_openId）、云签名服务的地址（s_global）、是否记住密码：true记住，false不记住（s_savePwd）、之前用户保存的密码（s_prePwd）、是否使用无障碍键盘输入口令，true为使用，false为不使用（s_keyboardSwitch）、是否显示隐私协议（s_showAgreement）。

2、需要绑定6个方法以（bind:方法名）的形式绑定，方法名分别是action、signresult、handleError、getPass、getCloseKeyboard、getDeviceId，

即绑定方式为：

bind:action=”你自己的方法名”，

bind:signresult=”你自己的方法名”，

bind:handleError=”你自己的方法名”，

bind:getPass=”你的方法名”，

bind:getCloseKeyboard=”你自己的方法名”，

bind:getDeviceId=”你自己的方法名”。

bind:action绑定的方法是签名成功后返回的签名内容返回参数是certres，

bind:signresult绑定的方法是签名成功后返回的签名值，返回参数是signaure和当前签名的任务id，返回参数是signjobid，

bind:handleError绑定的方法是错误码返回，返回参数是errorCod，具体见第四章错误码说明。新增加获取deviceId功能bind:getDeviceId=”getDeviceIdRes”绑定的方法返回参数是deviceId。bind:getCloseKeyboard=”getCloseKeyboardRes”绑定的方法是获取直接关闭签名口令输入框的回调。

bind:getPass：绑定的方法是获取用户签名时使用的口令

综上 证书下载引用方式举例为：

​	<sign 

bind:signresult="getsignresult" 

bind:getDeviceId="getDeviceIdRes" 

bind:getCloseKeyboard="getCloseKeyboardRes" 

bind:getPass="getPassRes" 

bind:handleError="getErrorCode" 

bind:action="selectItemDetail" 

s_signId="{{signId}}" 

s_appId="{{appId}}" 

s_msspID="{{msspID}}" 

s_savePwd="{{savePwd}}" 

​        s_prePwd="{{prePwd}}"

s_keyboardSwitch="{{keyboardSwitch}}" 

s_openId="{{openId}}" 

s_global="{{globalUrl}}" 

s_showAgreement="{{showAgreement}}"></sign>

2.1.6 设置手写签章图片组件

1 以标签形式引入设置手写签章图片组件，单独使用一个页面来展示手写签章效果，该页的配置项最好设置为宽屏，页面page样式height设为100%，例如

 {

​    "navigationBarTitleText": "设置手写签章",

​    "pageOrientation": "landscape",

​    "usingComponents": {

​      "pen-signer": "plugin://myPlugin/pen-signer"

​    }

  }

  page{

​    height:100%;

  }

以s_形式传递参数，需要传递的参数有:

l msspid（s_msspID）下载证书成功后返回

l 应用ID （s_appId）

l openid（s_openId）

l 云签名服务的地址（s_global）

2 需要绑定2个事件回调方法，以（bind:方法名）的形式绑定，方法名分别是handleSuccess,handleError。

绑定方式为：

bind:handleSuccess=”你的方法名”，绑定的方法是设置手写签名接口updatepersonalseal成功后的返回值{ errorCode:’0’ ,message: “设置签章图片成功！” }；

bind:handleError=”你的方法名”,绑定的方法是像服务端发送请求过程中出现的服务异常和请求异常，参考第4章4.1.5印章管理服务异常与4.2中文提示异常。

综上 设置手写签章图片组件引用方式举例为：

<pen-signer

​      s_appId="{{appId}}" 

​      s_msspID="{{msspID}}" 

​      s_global="{{globalUrl}}" 

​      bind:handleSuccess="handleSuccess"

​      bind:handleError="handleError"

​    \></pen-signer>

3. 接口说明

云签名SDK中，分为下载证书接口和签名功能接口

3.1 下载证书接口

功能简述

在小程序引用cert组件时，调用该接口，通过云签名sdk实现设备激活与证书的生成与下载。

接口定义

​

参数说明

​ s_authcode：类型为String，激活码。

​ s_appId：应用ID

​ s_openId：openID

​ s_global：云签名服务的地址

​ s_showAgreement:是否显示隐私协议

返回值

​ bind:action：绑定的方法是下载证书成功后返回的msspid返回参数是msspId（需要保存下来，签名是需要用）

​ bind:certresult：绑定的方法是下载证书成功后需要做的操作比如跳转回小程序的某个页面等

​ bind:handleError：绑定的方法是错误码返回，返回参数是errorCod具体见第四章错误码说明。

​ bind:getDeviceId：绑定的方法是获取deviceId，返回参数是deviceId

​ bind:getCertRes：绑定的方法是获取下载成功的证书，返回参数是certRes

异常

​ 无

示例

​	 <cert 

​      bind:action="selectItemDetail" 

​      bind:getDeviceId="getDeviceIdRes" 

​      bind:getCertRes="getCertResArr"  

​      bind:handleError="getErrorCode" 

​      bind:certresult="resultsuccess"

​      s_authcode="{{authcode}}" 

​      s_appId="{{appId}}" 

​      s_openId="{{openId}}"

​      s_global="{{globalUrl}}" 

​      s_showAgreement="{{showAgreement}}" />

3.2 签名业务接口

功能简述

在小程序引用sign组件时，调用该接口，通过云签名sdk实现设备激活与证书的生成与下载。

接口定义

​

参数说明

​ s_signId：签名任务id

​ s_msspID：msspid

​ s_appId：应用ID

s_openId：openid

​ s_global：云签名服务的地址

​ s_savePwd：是否记住密码，true记住，false不记住

​ s_prePwd：之前用户保存的密码

  s_keyboardSwitch：是否使用无障碍键盘输入口令，true为使用，false为不使用

  s_showAgreement:是否显示隐私协议

返回值

​ bind:action绑定的方法是签名成功后返回的签名内容返回参数是certres

​ bind:signresult绑定的方法是签名成功后返回的签名值返回参数是signaure和当前签名的任务id返回参数是signjobid

​ bind:handleError：绑定的方法是错误码返回，具体见第四章错误码说明。

​ bind:getDeviceId：绑定的方法是获取deviceId，返回参数是deviceId

​ bind:getCloseKeyboard：绑定的方法是获取直接关闭签名口令输入框的回调，返回参数是closeKeyboard

​ bind:getPass：绑定的方法是获取用户签名时使用的口令，返回参数是pass

异常

​ 无

示例

​	 <sign 

​      bind:signresult="getsignresult" 

​      bind:getDeviceId="getDeviceIdRes" 

​      bind:getCloseKeyboard="getCloseKeyboardRes" 

​      bind:getPass="getPassRes" 

​      bind:handleError="getErrorCode" 

​      bind:action="selectItemDetail" 

​      s_signId="{{signId}}" 

​      s_appId="{{appId}}" 

​      s_openId="{{openId}}"

​      s_msspID="{{msspID}}" 

​      s_keyboardSwitch="{{keyboardSwitch}}" 

​      s_openId="{{openId}}" 

​      s_global="{{globalUrl}}" 

​      s_showAgreement="{{showAgreement}}"></sign>

​

3.3 设置手写签章接口（1.2.2新增）

功能简述

在小程序引用pen-signer组件时，调用该接口，通过云签名sdk实现手写签名图片的设置与修改。

接口定义

参数说明

s_msspID：msspid

s_appId：应用ID

s_global：云签名服务的地址

返回值

bind:handleSuccess绑定的方法是设置手写签名接口updatepersonalseal成功后的返回值{ errorCode:’0’ ,message: “设置签章图片成功！” }

bind:handleError绑定的方法是像服务端发送请求过程中出现的服务异常和请求异常，参考第4章4.1.5印章管理服务异常与4.2中文提示异常。

异常

无

示例

  <pen-signer

​      s_appId="{{appId}}" 

​      s_msspID="{{msspID}}" 

​      s_global="{{globalUrl}}" 

​      bind:handleSuccess="handleSuccess"

​      bind:handleError="handleError"

\></pen-signer>

3.4 证书解析类接口（1.2.4-1.2.6新增）

新增了4个对外开放接口，根据调用方式的不同，传入对应的参数，返回值通过回调函数callback获取。
接口列表：

· 获取设备Id接口 getDeviceId(callback)

· 获取用户及证书状态接口 checkState({ appId, msspID, globalUrl},callback)

· 获取证书用户列表接口 getCertUserList(callback)

· 获取用户证书信息接口 getCertListByUser(msspID,callback)

传递的参数说明：

· 应用ID （appId）

· 下载证书成功后返回的（msspID）

· 云签名服务的地址（globalUrl）

每个接口均有个callback，用来返回查询的结果res，res数据格式：

{ errorCode: ‘错误码’, msg: “信息提示”, data: ‘当错误码==”0”时返回结果数据’ }

错误码及其含义参考第4部分错误码说明。

调用方式参考：

var plugin = requirePlugin("myPlugin");

...

plugin.openApi(params,res => {

  this.setData({

​    result:  JSON.stringify(res)

  })

});

注意：以上接口须在用户下载证书后才能获取到正确的数据，未下载证书直接调用将返回错误码

4. 错误码说明

整个错误码由区段码和错误码合成，共8位16进制数，其中区段码占高四位、错误码占第四位

区段码四位中高两位为大分类码，低两位为次分类码

错误码四位无区分

说明：小程序插件返回错误提示是错误加英文分号加中文错误提示例如“0x80000008;验证信息失败”。中文提示的错误错误码统一都是0即“0; 单设备策略”

4.1 服务异常

区段：0x80000000 — 0x8FFFFFFF

4.1.1 设备验证服务异常

区段：0x81100000 — 0x811FFFFF

已知异常：

编号 服务 服务异常描述 服务端错误码 错误提示 处理方法

0x81100001 autologin 登录失败 用户状态异常，请重新激活#100001 终止调用并返回

0x81100002 precheck 预验证信息失败 0x80000008 (toast)用户信息验证失败#100002 接口终止调用并返回；信步云找回停留在当前页

0x81100003 所有服务 AppID信息有误 0x8000100A 应用信息验证失败#100003 终止调用并返回

0x81100004 所有服务 token超时 操作超时#100004 终止调用并返回

0x81100000 precheck 服务执行异常 0x80000000 服务异常#100000 终止调用并返回

4.1.2 用户验证服务异常

区段：0x81200000 — 0x812FFFFF

已知异常：

编号 服务 服务异常描述 服务端错误码 错误提示 处理方法

0x81200001 precheck；regwithauthcode；regwithuseraccount 用户下载码无效 0x80001009 用户信息验证失败#200001 终止调用并返回

0x81200002 precheck 用户身份信息有误 0x80001003 (toast)用户信息验证失败#200003 接口找回应返回调用者；信步云找回停留在当前页

0x81200003 precheck 用户尚未注册 0x8000100C 用户信息验证失败#200003 终止调用并返回

0x81200004 precheck 企业信息有误 0x80001010 (toast)用户信息验证失败#200004 接口找回应返回调用者；信步云找回停留在当前页

0x81200005 regwithauthcode 受信用户注册失败 0x80000005 用户信息验证失败#200005 终止调用并返回

0x81200006 regwithauthcode；regwithuseraccount 用户被管理员冻结 0x8000100E 用户状态异常 #200006 终止调用并返回

0x81200007 regwithauthcode 用户已注册 0x80000009 无 自动转入找回流程

0x81200008 selfreg 0x80004009 (toast)用户信息验证失败 提示用户信息核验失败并返回调用者

停留在当前页

0x81200009 uploadliveimage 0x80009005 (dialog)识别失败，请重试/退出/重试 退出终止调用并返回；重试转入活体检测流程

0x8120000A 无此用户 0x8000100D

0x8120000B 设备被删除 0x80001008

0x81200000 regwithauthcode；regwithuseraccount；selfreg；uploadliveimage 服务执行异常 0x80000000 服务异常#200000 终止调用并返回

4.1.3 证书激活服务异常

区段：0x81400000 — 0x814FFFFFF

编号 服务 服务异常描述 服务端错误码 错误提示 处理方法

0x81400001 useractive 用户激活失败 激活失败#400001 终止当前业务并返回调用者

终止调用并返回，未来需要服务端扩展

0x81400002 reqcert 用户激活失败 0x80001003 激活失败#400002 终止调用并返回

0x81400003 reqlocalcert 生成离线证书失败 证书生成失败#400003 终止调用并返回

0x81400000 useractive;reqcert 服务执行异常 0x80000000 服务异常#400000 终止调用并返回

4.1.4 签名服务异常

区段：0x81800000 — 0x818FFFFFF

编号 服务 服务异常描述 服务端错误码 错误提示 处理方法

0x81800001 getuserkeystate 查询密钥状态失败 0x8000400B 密钥查询失败#800001 终止调用并返回

0x81800002 signdatafinish 签名失败 【冻结】

(dialog)用户已冻结至00-00-00 00:00/确定

【OTP错误或其他】

服务异常#800002 再次调用getuserkeystate接口，返回冻结与OTP时：终止调用并返回

0x81800003 PIN口令错误 (dialog)口令错误，还可重试N次/确定 再次调用getuserkeystate接口，返回口令错误时：

确定进入密码键盘

0x81800004 getsigndata 获取签名数据失败 不做处理（M1接口） 终止调用并返回

0x81800005 addsigndatajob 移动端发起签名任务 签名发起失败#800005 终止调用并返回

0x81800006 recordlocalsigndata 上传离线密钥签名结果 本地处理不返回异常

0x81800007 checkpin 有PIN托管密钥激活 密钥激活失败#800007 返回重试，超时终止调用并返回

0x81800008 entrustactive 检查PIN码 口令验证失败#800008 返回重试，超时终止调用并返回

0x81800009 signinit 用户无权限签署当前数据 0x8000300A 您没有权限签名当前数据

0x8180000A signdocuinit docuId不存在，或docuId代表的文档指定其他用户签署 0x80004004 文档与用户信息不匹配

0x81800000 以上服务 服务执行异常 0x80000000 服务异常#800000 终止调用并返回

4.1.5 印章管理服务异常

区段：0x81A00000 — 0x81AFFFFF

编号 服务 服务异常描述 服务端错误码 错误提示 处理方法

0x81A00001 updatepersonalseal 上传个人印章 (dialog)操作失败，请重试/确定 返回重试，超时弹出提示，确定停留在当前页

4.1.6 中文提示异常

下载证书中有一个单设备策略提示，返回码即为：0;单设备策略

签名流程中中文提示，返回码为

0）如果本地没有证书提示“0;请先下载证书”。

1）秘钥已冻结。

2）OTP错误。

3）下载证书过程中

设置手写签名图片组件请求过程中，包含一些网络请求异常，用户在处理的时候可以对相关信息做弹窗提示后，返回上一页。

如下所示：

‘SIGNER0000’: 请先下载证书！

‘SIGNER0001’: 获取图片base64数据失败！

‘SIGNER0002’: 获取图片base64数据接口异常！

‘SIGNER0003’: 获取用户信息请求异常！

‘SIGNER0004’: 更新用户签章图片请求异常!

新增的对外开放接口错误码及其含义如下所示：

‘API0000’: 请传入appId参数

‘API0001’: 请传入msspID参数

‘API0002’: 请传入globalUrl参数

‘API0003’: 没有查到该用户的证书

‘API0004’: 请先下载证书