新页面

接入说明

本文档展示了如何通过http请求，完成于易百电子凭证系统完成对接。本文档主要面向的读者为各有需求接入电子凭证的，有一定开发能力的技术人员。

本文档中必填字段仅限于易百自制码，第三方制码可能存在部分字段无法返回。在对接时可与易百技术人员沟通

配置密钥

取码对接方对接时，需跟业务同事沟通后把公钥发送到指定邮箱。易百电子凭证系统会分配app_id, version, saleChannelId, 易百电子凭证系统公钥等信息

开发者调用接口前需自行生成RSA密钥，RSA密钥包含：

应用私钥(APP_PRIVATE_KEY)
应用公钥(APP_PUBLIC_KEY）

RSA私钥与公钥生成方法

1.运行 openssl

CMD> openssl

2.生成明文RSA私钥

OpenSSL> genrsa -out rsa_private_key.pem 2048

其中 rsa_private_key.pem 为私钥保存的文件名，2048位为密钥长度
默认情况下，openssl 输出的密钥格式为 PKCS#1-PEM

3.生成明文RSA公钥

OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem

其中 rsa_private_key.pem 为私钥保存的文件名，rsa_public_key.pem为公钥保存的文件名

4.如果是Java语言，私钥需要转成PKCS8格式

OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -out rsa_private_key.pkcs8 -nocrypt

其中 rsa_private_key.pem 为私钥保存的文件名，rsa_private_key.pkcs8为私钥PKCS8格式保存的文件名

生成密钥后在电子凭证管理中心进行密钥配置，配置完成后可以获取：

电子凭证公钥(WHALE_PUBLIC_KEY)。

第三步：搭建和配置开发环境

1.调用方法

内容	说明
通讯方式	采用 HTTPS 方式访问
提交方法	POST (application/json)
交互数据格式	JSON
字符编码	UTF-8
签名算法	SHA256WithRSA
签名验证	提交和返回数据都需要验证签名

2.报文结构

请求报文和返回报文都采用如下的报文结构

序号	参数	类型	参考数据	参数说明	备注
1	action	String	MakeCode	交易类型	具体接口有详细说明
2	app_id	String	2014072300007148	应用ID	开放平台分配给开发者的应用ID
3	biz_content	String	BASE64	报文内容BASE64	具体接口中有详细说明，本域需要采用BASE64编码
4	timestamp	String	1483372334	Unix时间戳	单位：秒
5	version	String	20171212	版本号	用于兼容不同的报文协议对应后台不同的处理方式
6	sign	String	7E65B60DCFA42B04	数据签名	详见：签名算法

注意事项

其中biz_content字段是对请求参数或返回参数进行BASE64编码后得到的，例如：

JSON

{
    "traceNo": "99000009100010101732123",
    "originalTraceNo": "99000009100010101732124"
}

BASE64编码后得到：

ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==

赋值给biz_content字段。
如果请求报文无法解析，或传过来的app_id无效，则异常提示返回的报文中sign字段为空。

报文举例

JSON

{
     "action" : "efuli.cashvoucher.send",
     "app_id" : "2014072300007148",
     "biz_content" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "timestamp" : "1483372334",
     "version" : "20171212",
     "sign" : "7E65B60DCFA42B04"
 }

3.签名算法

a.筛选并排序

获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。

注意：biz_content字段需要先Base64编码，再进行拼接

b.拼接

将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。

c.签名值计算

使用各自语言对应的SHA256WithRSA签名函数利用应用私钥（APP_PRIVATE_KEY）对待签名字符串进行签名，并进行Base64编码。

示例报文

 {
     "action" : "efuli.cashvoucher.send",
     "app_id" : "2014072300007148",
     "biz_content" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "timestamp" : "1483372334",
     "version" : "20171212",
     "sign" : "7E65B60DCFA42B04"
 }

应用私钥（APP_PRIVATE_KEY）

拼接报文参数

String

List

action=efuli.cashvoucher.send&app_id=2014072300007148&biz_content=ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==&timestamp=1483372334&version=20171212

签名值计算

gUTdEB0lAS/ECkP98weSHf6k31Fmd4hcw0zPG8ewbMTfDFSubKlel/1C16upb2AHzN873HMwUlkcTg7ZuN92KDIkfsbINd2IwVY2tWMvKt5O8gqC2a8XbS25ZObUlLK5zZmU7mQ/DLbyY+EAhkYdGnwskloJkydi2zmLv99xT5G01yXBLSNiTrPBTsc2OhBkA44kknnok0x+hS4HfcgQwGPMG4y+V5aT1bhPDypwdbfAg+EN/5XoSECsIcsvBirdk+BGPjBIuwHHF+Hir/3E3i20ImtlowBc6jwh5qFOVqGN/w2UEPfg6xJxHyW04FBipt6mw7huD4PA4pA4qZRnsg==

签名Demo Java版

点击下载 signdemo.zip