H5交互式签署系统接口文档

1. 范围

文档说明了电子签章系统统一接口规范制定的规范引用文件、术语和定义、缩略语、接口说明及错误码等内容。其中接口部门说明了印章安全访问控制流程和对接参数，将接口按照与业务系统的对接方式划分为API方式签章接口和H5页面跳转方式签章接口两种接口。API方式签章接口包括：普通签章、骑缝章、签章结果查询、验章及获取印章及证书接口内容。H5页面跳转方式签章接口是一种将签章能力封装成独立的签章服务供业务系统调用，包括：签章请求接口和签章结果查询接口内容。

2. 规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。

C0119-2018国家政务服务平台统一电子签章技术要求

C0120-2018国家政务服务平台统一电子印章技术要求

C0122-2018国家政务服务平台统一电子印章系统接口

3. 术语和定义

下列术语和定义适用于本文件。

3.1

电子印章 electronic seal

一种以电子签名数据为表现形式的印章，可用于签署电子文件，其内容包括电子印章印文图像数据、印章信息和信任凭证。

3.2

电子签章

使用电子印章签署电子文件的过程。

3.3

电子签章数据

电子签章过程产生的包含电子印章信息和签名信息的数据。

3.4

HTML语言 Hyper Text Markup Language

一种描述性语言。

3.5

电子签章系统 Electronic Seal System

提供电子印章管理及电子签章服务的系统。电子签章系统由[数字证书](https: //baike.baidu.com/item/数字证书/326874)认证系统（PKI/CA系统）、电子印章管理系统、客户端电子签章软件构成。本文档提及的电子签章系统为电子签章系统及电子签章云服务等的统称。

3.6

业务系统 Application System

电子签章业务发起方，调用电子签章系统接口实现业务文件的签章。通常OA、ERP、SCM、EAM等都可以成为业务系统。

3.7

同步接口 Synchronous Interface

接口调用后最终结果会同步返回。

3.8

异步接口 Asynchronous Interface

接口调用后仅返回调用结果，而不能将最终结果返回给调用方，调用方需要发起另外的接口调用来获取最终结果。

4. 缩略语

下列缩略语适用于本文件。

API 应用程序编程接口（Application Programming Interface）

H5 一种描述性语言，HTML5的简称（Hyper Text Markup Language 5）

5. 接口说明

5.1 H5交互式签名

电子签章系统提供全套的签章能力。包括 “H5交付签名页面”。业务系统与电子签章服务商之间实现页面的跳转，实现签章请求接口和签章结果响应接口，用户签章过程的操作全部在H5签章前台页面。

5.1.1 签署发起接口

功能说明：

该接口调用方为业务系统，被调用方为电子签章系统 云服务 或网关。

接口调用流程：

img

服务地址：

https: //ipAddress/xxxxxx/h5Sign

HTTP请求类型：

POST请求

content-type：

application/json

请求参数：

参数名称 类型 是否必选 描述
appId String 是 标识业务系统的唯一标识
configInfo签署配置信息noticeUrl String 否 回调通知地址（签署完成后由H5签署组件调用此URL进行状态通知，详见签署完成通知接口），默认使用系统配置地址
configInfo签署配置信息redirectUrl String 否 签署完成H5页面点击返回按钮重定向地址,默认签署完成停在当前页面
ext String 否 可用于自定义扩展

响应格式：

属性名 属性类型 描述
status Int 响应码，成功是200，其他错误为8位错误码
message String 响应信息
trace String 错误栈信息，用于显示错误的深层次原因，帮助调用者解决错误
transId String 请求流水号
data Object 返回业务字段
url String 该地址作为签署当前业务的H5页面地址嵌入接入方系统中完成页面文件签署动作。
businessId String 签署业务ID 业务系统需留存后续用于1.业务系统接收签署完成通知时可根据此ID区分具体业务；2.业务系统在签署文件下载接口中利用此ID下载签署后的文件；

请求示例：

{
	"appId": "app-1",
	"configInfo": {
		"noticeUrl": "http://192.168.118.59:10616/getRedirectUrl/123456789",
		"redirectUrl": "http://192.168.118.59:10616/getRedirectUrl/123456789"
	}
}

响应示例：

{
	"status": 200,
	"message": "SUCCESS",
	"transId": null,
	"data": {
		"url": "http://192.168.118.58:8080/ecSign/tools/#/sso/index?businessId=1294519964845252610&businessType=h5send",
		"businessId": "1294519964845252610"
	}
}

5.1.2 签署完成通知接口

功能说明：

由于文件签署涉及大量数字签名、文档操作等耗时操作，签署任务的执行采用异步方式进行，完成后通过HTTP协议get请求回调的方式通知业务系统签署结果，此接口需要业务系统实现，签章平台调用。

接口调用流程：

img

服务地址：

接入方在调用 签署发起接口时传入的noticeUrl地址；

HTTP请求类型：

GET请求

content-type：

application/json

请求参数：

名称 类型 必填 示例值 描述
businessId String 是 b6a3bf93626b54abb303ea 签署业务ID
signTime String 是 2020-07-11 23:59:59 签署时间格式yyyy-MM-dd HH:MM:SS
status Int 是 1 1:签署完成 2:签署未完成
message String 是 服务器内部异常 签署失败异常消息
timestamp String 是 1263967486940 回调通知时间戳

5.1.3 签署信息查询接口

功能说明：

根据签署业务ID （businessId）查询业务信息。

接口调用流程：

img

服务地址：

https: //ipAddress/xxxxxx/h5Sign/{businessId}

HTTP请求类型：

GET请求

content-type：

application/json

请求参数：

名称 参数类型 类型 必填 示例值 描述
appId Query String 是 456455645656dfd 标识业务系统的唯一标识
businessId path String 是 456455645656dfd 签署业务ID

响应格式：

属性名 属性类型 描述
status Int 响应码，成功是200，其他错误为8位错误码
message String 响应信息
trace String 错误栈信息，用于显示错误的深层次原因，
transId String 请求流水号
data Object 返回业务信息
signTime String 签署时间
status String 签署状态
fileList Array 签署文件列表
fileId String 上传文件id
signFileId String 签署完成的文件ID
fileName String 文件名称

请求示例：

http: //ipAddress/xxxxxx/h5sign/1294513569148194817?appId=app-1

响应示例：

{
	"status": 200,
	"message": "SUCCESS",
	"transId": null,
	"data": {
		"signTime": "2020-08-15 14:18:57",
		"status": "1",
		"fileList": [{
			"fileId": "9e74390b-84a3-4ea3-8807-2a3f2a33ddac",
			"signFileId": "1294514346080088066",
			"fileName": "入职合同-张三.pdf"
		}]
	}
}

5.1.4 签署文件下载接口

功能说明：

根据相关签署业务ID 加签署文件ID 下载签署完成的文件。

接口调用流程：

img

服务地址：

http: //ipAddress/xxxxxx/h5Sign/downloadFiles/{businessId}

HTTP请求类型：

GET请求

content-type：

application/json

请求参数：

名称 参数类型 类型 必填 示例值 描述
appId Query String 是 456455645656dfd 标识业务系统的唯一标识
businessId path String 是 456455645656dfd 签署业务ID
signFileId query String 是 456455645656dfd 签署文件ID

响应格式：

正常HTTP响应头：(下载成功 HTTP status code 等于 200)

HTTP/1.1 200

Content-Type: application/octet-stream

异常HTTP响应头：(下载失败 HTTP status code 不等 200)

HTTP/1.1 404

Content-Length: 0

请求示例：

http: //ipAddress/xxxxxx/h5sign/downloadFiles/1294513569148194817?appId=app-1&signFileId=1294514346080088066

5.1.5 H5页面验签

功能说明：

接入系统直接通过验签url打开验签页面，完成对已签署的文档验证功能。

接口调用流程：

img

页面地址：

http: //ipAddress/xxxxxx/ecSign/tools//#/sso/index?businessType=h5validate&appId=appid-01

说明：ipaddress这里需要看前端部署对互联网开放的域名是什么 ，不一定和服务端相同

HTTP请求类型：

GET请求

content-type：

application/json

请求参数：

名称 参数类型 类型 必填 示例值 描述
appId Query String 是 456455645656dfd 标识业务系统的唯一标识
businessType Query String 是 h5validate 业务类型 h5validate为验签功能

6. 错误码说明

错误码 说明 备注
200 成功
-1 服务内部错误
70000003 远程调用异常
70000017 没有查询到有效文件
75010020 没有查到签署文件
75010021 文件类型错误
75010022 文件不能超过20M
75010023 远程失败
75010024 验证签名失败
75010025 业务异常
75010026 签署异常