电子存证服务API接入手册
1. 摘要保全接口
1.1 接口定义
| 接口功能 |
业务系统将需要保全的电子数据通过提供的 SDK 或者本地安装 bjcahash 服务进行生成 Hash 值（Hash工具使用说明），建议使用 sha256 或者 sm3，将工具返回的 hash 值提交到云保全。 |
| 接口地址 |
/preservationServer/v1/hashPreservation |
| 请求类型 |
POST |
| Content Type |
application/json |
1.2 参数
| 字段名称 |
描述 |
是否必须 |
示例 |
| hash |
hash值（请使用提供的 SDK 或者bjcahash 服务进行生成） |
是 |
JyEpBV7G9eoTi+17rc1 mmAJMCykrCHUl/qcLd GK+Kwk= |
| userDataJson |
用 户 自 定 义 json 字 符 串，格式[{\“key\”:\”\”,\“value\”:\”\”}]，最大 2K。 |
否 |
[{\“key\”:\” 姓 名 \”,\“value\”:\” 张 三 \”}] |
| signAlgIdentifier |
支持的签名算法列表：SHA256withRS A，SM3withSM2，默认 SHA256withRSA；保全系统根据该参数做签名运算。 注意：该值需要与 hash 工具计算hash算法保持对应关系：sm3 -> SM3withSM2 sha256 -> SHA256withRSA |
否 |
SHA256withRSA |
| judicial |
若未接司法服务，可忽略此参数 司法参数NONACTIVATED 或者 HZ_COUNT_OF_INTERNET |
否 |
{“judicialType”:”HZ_CO UNT_OF_INTERNET”,” data”:{“certName”:”测试 企 业 “,”certNo”:”11111111111 111111111”,”legalPerso云保全 V2.0.1 用户技术手册 第11页共26 页 n”:”张三”,”legalPersonId”:”11111 1111111111111111”,”age nt”:”李四”,”agentId”:”11111111111 1111111111”,”phase”:”1” }} |
报文示例：
{
"version":"1.0",
"signAlgo":"HmacSHA256",
"signature":"Base64 的签名数据",
"deviceId":"网关设备 ID",
"appId":"应用 ID",
"hash":"JyEpBV7G9eoTi+17rc1mmAJMCykrCHUl/qcLdGK+Kwk=",
"userDataJson":"[{\"key\":\"姓名\",\"value\":\"张三\"}]",
"signAlgIdentifier":"SHA256withRSA",
"judicial":"{ //若未接司法服务，可忽略此参数
\"judicialType\":\"NONACTIVATED\", // 司法类型
\"data\":{
\"certName\":\"测试企业\", // 客户企业名称
\"certNo":"9111xxxxxxxxxxxxxA\", // 客户企业统一社会信用代码
\"legalPerson\":\"张三\", // 客户企业法人姓名
\"legalPersonId\":\"130xxxxxxxxxxxxxxx\", // 客户企业法人身份证号
\"agent\":\"李四\", // 客户企业经办人姓名
\"agentId\":\"130xxxxxxxxxxxxxxx \", // 客户企业经办人身份证
\"phase\":\"1\" // 存证事务阶段（目前服务仅支持 1）
}}"
}
|
1.3 返回数据
| 字段名称 |
描述 |
是否必须 |
示例 |
| status |
响应码 |
是 |
200 |
| message |
响应信息 |
是 |
success |
| data |
响应数据值为： txHash：存证编号 transId：存证事务 ID preserveNum：保全编号 |
否 |
{ “txHash”: “138fe2d0833c19…”, “transId”: “cfeea9bb121…”, “preserveNum”: “ra3Uayqz2Q…” } |
1.4 示例:
测试接口如下：
curl -X POST \
http:
'Content-Type: application/json' \
'cache-control: no-cache' \
'{
"hash": "JyEpBV7G9eoTi+17rc1mmAJMCykrCHUl/qcLdGK+Kwk=",
"userDataJson": "[{\"key\":\"姓名\",\"value\":\"XXX\"},{\"key\":\"性别\",\"value\":\"XXX\"}]",
"signAlgIdentifier": "SHA256withRSA",
"appId": "APP_1234567891",
"signAlgo": "HmacSHA256",
"version": "1.0",
"deviceId": "DEV_B7DFE648EAED41D4A6F71643D682C6B2",
"signature": "kmr0sjXLNq3ZjlZrR+EaURknOSvBW9wq6UZCBomHI6M="
}'
|
返回数据如下：
{
"status": 200,
"message": "SUCCESS",
"data": "n9PpSfNVcNoDZyjFLCRX2schjAfXTy6rMlOUuIsvNZmwqV+9poYIAg=="
}
|
2. 原文保全-上传文件接口
2.1 接口定义
| 接口功能 |
业务系统将需要保全的文件提交到云保全服务中。该接口是原文保全时，业务系统需要调用文件上传接口。 |
| 接口地址 |
/open/upload |
| 请求类型 |
POST |
| Content Type |
application/json |
2.2 参数
| 字段名称 |
描述 |
是否必须 |
位置 |
示例 |
| sha256 |
生成文件 sha256 哈希值 |
是 |
url |
1231sdfsdfsdf |
| keep |
String，保留天数，如果不传默认7天，最大30天 |
否 |
url |
7 |
| file |
需要保全的文件 |
是 |
body |
multipart |
2.3 返回数据
| 字段名称 |
描述 |
是否必须 |
示例 |
| message |
响应信息 |
是 |
success |
| id |
响应数据，包含文件 类型 |
是 |
“id”:”20190826-cbb297c0-14a9-46b c-ad91-1d0ef9b42df9.pdf” |
2.4 示例
测试接口如下：
curl -X POST \
'http://beta.isignet.cn:10017/open/upload?version=1.0
&signature=CahHldhUt17Ij5H+xWMFp4GTQA1NRfJIes0kgOejm+o=&deviceId=DEV_23AF7
AA39C734BC9A4213D98221BF220&appId=APP_1234567890&sha256=4355a46b19d348dc2f5
7c046f8ef63d4538ebb936000f3c9ee954a27460dd865&signAlgo=HmacSHA256' \
'Cache-Control: no-cache' \
'Content-Type: application/x-www-form-urlencoded' \
'service-id: 6' \
'Postman-Token: 22868616-1e6a-4191-abdb-786ee24b0fe8' \
'content-type:
multipart/form-data;
boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
=@/Users/shuvigoss/Documents/1.txt
|
返回数据如下：
{
"message":"success",
"id":"20190826-cbb297c0-14a9-46bc-ad91-1d0ef9b42df9"
}
|
3. 原文保全-提交文件id接口
3.1 接口定义
| 接口功能 |
业务系统将需要保全的文件提交到云保全服务中。该接口是原文保全时，业务系统提交文件id接口。 |
| 接口地址 |
/preservationServer/v1/filePreservation |
| 请求类型 |
POST |
| Content Type |
application/json |
3.2 参数
| 字段名称 |
描述 |
是否必须 |
示例 |
| fileId |
fileId，上传文件接口的返回值。 |
是 |
20190829-1490ae8e-f53c-40dd-897c-4aa87fdf1bf1.pdf |
| userDataJson |
用 户 自 定 义 json 字 符 串 ， 格 式 [{\“key\”:\”\”,\“value\”:\”\”}]，最大 2K。 |
否 |
[{\“key\”:\” 姓 名 \”,\“value\”:\” 张 三 \”}] |
| signAlgIdentifier |
支 持 的 签 名 算 法 列 表 ： SHA256withRSA，SM3withSM2，默认SHA256withRSA |
是 |
SHA256withRSA |
请求报文：
{
"version":"1.0",
"signAlgo":"HmacSHA256",
"signature":"Base64 的签名数据",
"deviceId":"网关设备 ID",
"appId":"应用 ID",
"fileId":"20190829-1490ae8e-f53c-40dd-897c-4aa87fdf1bf1.pdf",
"userDataJson":"[{\"key\":\"姓名\",\"value\":\"张三\"}]",
"signAlgIdentifier":"SHA256withRSA"
}
|
3.3 返回数据
| 字段名称 |
描述 |
是否必须 |
示例 |
| status |
响应码 |
是 |
200 |
| message |
响应信息 |
是 |
success |
| data |
响应数据，值为 保全编号 |
否 |
“data”: “4vnfe0F9U4pdJxJTkNZlU1VzAdy1xBuG+ AfWMDtywE0otU21xxyZ5g==” |
3.4 示例
3.5 测试接口如下：
curl -X POST \
http:
'Content-Type: application/json' \
'cache-control: no-cache' \
'{
"fileId": "20190829-1490ae8e-f53c-40dd-897c-4aa87fdf1bf1.pdf",
"userDataJson": "[{\"key\":\"姓名\",\"value\":\"许子钰\"},{\"key\":\"性别\",\"value\":\"男\"}]",
"chainSofeVidenceJson": "",
"signAlgIdentifier": "SHA256withRSA",
"appId": "APP_1234567891",
"signAlgo": "HmacSHA256",
"version": "1.0",
"deviceId": "DEV_B7DFE648EAED41D4A6F71643D682C6B2",
"signature": "kmr0sjXLNq3ZjlZrR+EaURknOSvBW9wq6UZCBomHI6M="
}
|
返回数据如下：
{
"status": 200,
"message": "SUCCESS",
"data": "4vnfe0F9U4pdJxJTkNZlU1VzAdy1xBuG+AfWMDtywE0otU21xxyZ5g=="
}
|
4. 保全信息查询
4.1 接口定义
| 接口功能 |
业务系统根据保全编号查询保全信息，只能查询今天之前的保全数据 |
| 接口地址 |
/preservationServer/v1/preservingInfo?preserveNum=XXX&appId=XXX&deviceId=XXX&signAlgo=HmacSHA256&signature=XXX&version=1.0’ |
| 请求类型 |
GET |
| Content Type |
application/json |
4.2 参数
| 字段名称 |
描述 |
是否必须 |
示例 |
| preserveNum |
保全编号 |
是 |
hsPv65tcbJUDZyjFLCRX2n8dF2VQK+ihXvWzV/N/sgk83Ca8ZLxTsQ== |
4.3 返回数据
| 字段名称 |
描述 |
是否必须 |
示例 |
| status |
响应码 |
是 |
200 |
| message |
响应信息 |
是 |
success |
| data |
响应数据 |
是 |
“data”: { “appId”: “APP_FA541”, “preserveNum”: “bi7D0fNg==”, “preserveType”: 11, “preserveStartTime”: “”, “preserveEndTime”: “”, “userDataJson”: “”, “customerOwner”: “bjca”, “original”: “”, “signAlgIdentifier”: “SHA256withRSA” } |
类型说明：
| 参数名 |
类型 |
是否必须 |
说明 |
| appId |
string |
是 |
系统码 |
| preserveNum |
string |
是 |
保全编号 |
| preserveType |
int |
是 |
11：摘要保全 12：原文保全 |
| preserveStartTime |
timestamp |
是 |
保全起始时间 yy-MM-dd hh:mm:ss |
| preserveEndTime |
timestamp |
是 |
保全截止时间 yy-MM-dd hh:mm:ss |
| userDataJson |
string |
否 |
业务系统保全时，提交的自定义数据 |
| customerOwner |
string |
是 |
服务提供方 |
| original |
string |
是 |
preserveType=11 时为业务系统提 交的摘要值；preserveType=12 时为 业务系统提交的文件 id |
| signAlgIdentifier |
string |
是 |
签名算法 |
4.4 示例
测试接口如下：
curl -X GET \ ‘http://beta.isignet.cn:28081/preservationServer/v1/preservingInfo?preserveN
um=IXbAnZTT+mZSsb/itnkeAvh8bOszUACVkNUVFXrVXBM=&appId=APP_1234567891&deviceId=
DEV_B7DFE648EAED41D4A6F71643D682C6B2&signAlgo=HmacSHA256&signature=
rRmlNNjFGBvx7fvHWOlDyqxVjD2GG5G+supylJ0WS1g=&version=1.0’ \ -H ‘cache-control: no-cache’
返回数据如下：
{
"status": 200,
"message": "SUCCESS",
"data": {
"appId": "APP_FA548076851E4AA7B51EA4B1C4F0A7E81111",
"preserveNum": "4vnfe0F9U4pmFuCgbiK2bksgQdmdHwgY7WQIf7U00D0fNg==",
"preserveType": 11,
"preserveStartTime": "2019-08-23 20:11:25",
"preserveEndTime": "2024-08-23 20:11:25",
"userDataJson": "[{\"key\":\"姓名\",\"value\":\"XX\"},{\"key\":\"性别\",\"value\":\"男\"}]",
"customerOwner": "bjca",
"original": "JyEpBV7G9eoTi+17rc1mmAJMCykrCHUl/qcLdGK+Kwk=",
"signAlgIdentifier": "SHA256withRSA"
}
}
|
5. 保全信息下载
5.1 接口定义
| 接口功能 |
业务系统根据保全编号下载保全信息，只能下载今天之前的保全数据。 |
| 接口地址 |
/preservationServer/v1/preservingFile?appId=XXX&deviceId=XXX&signAlgo=HmacSHA256&signature=XXX&version=1.0&preserveNum=XXX |
| 请求类型 |
GET |
| Content Type |
application/json |
5.2 参数
| 字段名称 |
描述 |
是否必须 |
示例 |
| preserveNum |
保全编号 |
是 |
hsPv65tcbJUDZyjFLCRX2n8dF2VQK+ihXvWzV/N/sgk83Ca8ZLxTsQ== |
5.3 返回数据
成功时以文件流的方式返回zip包，失败时返回错误码。
5.4 示例
测试接口如下：
curl -X GET \ ‘http://beta.isignet.cn:28081/preservationServer/v1/preservingFile?appId=AP
P_1234567891&deviceId=DEV_B7DFE648EAED41D4A6F71643D682C6B2&signAlgo=HmacSHA256&signature
=JqAymOtTX9XwbXbAMYAZ1pz1GurtXlLZqSwUlImqLNM=&version=1.0&preserveNum=
x464wcQNi+1Zti0tMjrKXPiVy/6TNU9UIliSe/S7Zm942ReJOw33XA==’ \ -H ‘cache-control: no-cache’
