简介
概述
随着电子商务发展,商家所使用到的各类软件越来越多,各个软件之间没有相互打通,形成一个个信息孤岛,给商家的使用带来种种不便,商家要求各个系统之间的对接需求已经越来越迫切。
目前在行业内已经有部分系统直接由服务商之间完成了系统软件的对接,但是由于没有统一的接入标准,导致接入较混乱,对接接口的版本也参差不齐,往往这样的系统对接不具有可复制性,多个系统之间的对接,需要多次开发,给商家的使用和功能迭代升级带来了诸多的不便,同时也给服务商带来额外的维护、开发成本。为了满足商家需求,让商家能够突破各个业务系统之间的信息孤岛,提升商家在各个系统之间的操作效率,解决各个系统之间标准化对接的痛点,我们将计划推出虎符网关,以此来解决此类问题。
名词解释
序号 | 名词 | 解释 |
---|---|---|
1 | 虎符 | 京东商家业务系统标准化对接平台 |
2 | 正向调用 | 由前端(A)发起调用到虎符(B),虎符处理后将请求转发至后端(C) |
3 | 逆向调用 | 由后端(C)发起调用到虎符(B),虎符处理后将请求转发至前端(A) |
虎符对接方案
对接架构
前端系统与虎符应用进行对接,前端系统通过标准化通信协议、字段访问虎符系统,前端系统在此需要进行改造;
虎符应用主要提供字段映射、数据翻译、数据路由、账号权限、流控、数据打点等功能,能够让双方的请求通过虎符进行正常的传输。
系统调用流程
正向调用:前端应用与虎符应用进行交互,对于想要发送到后端应用的请求首先发送到虎符,由虎符负责数据的解析、字段映射、数据翻译,再将处理过后的数据根据前端应用匹配的路由规则发送到后端应用,后端应用收到请求后,将结果返回至虎符,由虎符统一返回至前端系统。
逆向调用:后端系统主动向前端系统发出的状态更新请求,同以上访问步骤。
接口规范
前端与虎符的通信协议
协议描述
接口遵循REST规范,使用HTTP POST方式进行通讯。
标准协议的HTTP入口地址为:
前端发给虎符:
http://[hufu_webservice_url]?method=[*hufu_API*]×tamp=[*2017-02-01 00:00:00]&format=xml&app_key=[front_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[HUFUUSR1*]
虎符发给前端:
http://[front_webservice_url]?method=[*front_API*]×tamp=[*2017-02-01 00:00:00]&format=xml&app_key=[backend_appkey]&v=1.0&sign=[xxxxxxxxxxxxxxxxxxxxxx]&sign_method=md5&customerId=[HUFUUSR1*]
注:
[]中需要根据具体业务进行填写。hufu_API,front_API具体见下方的API名称。
URL参数值需要做URL Encoding处理。
请求和响应的消息主体使用json格式。
[hufu_webservice_url] 请用虎符网关接入地址代替,[front_webservice_url]请用前端系统服务地址代替,[front_appkey]请用前端应用app_key代码,[backend_appkey]请用后端应用app_key代替
访问授权
需要商家提供该商家在对应后端系统的用户ID(customerId)和密钥(用于计算sign)。
请求参数说明
请求参数包含URL中带的系统参数和BODY中带的相关业务参数,系统参数如下:
参数 | 参数说明 | 类型 | 约束 |
---|---|---|---|
method | 前端相关的业务接口名称,如商品信息同步的请求,method= jingdong.hufu.item.synchronize | string | 必须 |
timestamp | 时间戳,格式为yyyy-MM-dd HH:mm:ss | string | 必须 |
format | content格式 | string | 目前支持json |
app_key | 应用接入时申请的appkey | string | |
v | 协议版本号,1.0 | string | 必须 |
sign | 根据url和密钥计算的结果。具体算法参看附录1 | string | 必须 |
sign_method | 参数加密方法,md5 | ||
customerId | 后端应用颁发给用户的ID | string | 必须 |
响应参数
响应参数包含系统参数和业务参数,系统参数如下:
参数 | 参数说明 | 类型 | 约束 | |
---|---|---|---|---|
flag | success\ | failure | string(50) | 必须 |
code | 返回状态码 | string(50) | 必须 | |
message | 返回状态描述 | string(200) | 必须 |
虎符与后端的通信协议
协议描述
接口遵循REST规范,使用HTTP POST方式进行通讯。
标准协议的HTTP入口地址为:
虎符发给后端:
后端发给虎符:
注:
[]中需要根据具体业务进行填写。hufu_API,backend_API具体见下方的API名称。
URL参数值需要做URL Encoding处理。
请求和响应的消息主体使用json格式。
请求参数
请求参数包含URL中带的系统参数和BODY中带的相关业务参数,以下是系统参数:
参数 | 参数说明 | 类型 | 约束 |
---|---|---|---|
method | 后端相关的业务接口名称,如商品信息同步的请求,method= item.synchronize | string | 必须 |
format | content格式 | string | 目前支持json |
app_key | 应用接入时申请的appkey | string | |
v | 协议版本号,1.0 | string | 必须 |
sign | 根据url和密钥计算的结果。具体算法参看附录1 | string | 必须 |
sign_method | 参数加密方法,md5 | String | 必须 |
customerId | 后端应用颁发给用户的ID | string | 必须 |
响应参数
响应参数包含系统参数和业务参数。以下是系统参数:
参数 | 参数说明 | 类型 | 约束 | |
---|---|---|---|---|
flag | success\ | failure | string(50) | 必须 |
code | 返回状态码 | string(50) | 必须 | |
message | 返回状态描述 | string(200) | 必须 |
接口说明
接口1
接口说明
前端调用虎符API名称:jingdong.hufu.[APINAME]
虎符调用后端API名称:[APINAME]
注:虎符接口都是同步接口,响应成功表示同步调用成功,而不只是消息接收成功。
附录
sign签名算法:
我们用前端应用调用虎符URL演示加密算法:
【http:// [hufu_webservice_url]?method=jingdong.hufu.itemlack.report×tamp=2015-04-26 00:00:07&format=xml&app_key=testerp_appkey&v=1.0&sign=abc&sign_method=md5&customerId=stub-cust-code
[hufu_webservice_url] 请用虎符网关接入地址代替
输入参数为
method= jingdong.hufu.itemlack.report
timestamp=2015-04-26 00:00:07
format=xml
app_key= testerp_appkey
v=1.0
sign_method=md5
customerId =test
按首字母升序排列
app_key= testerp_appkey
customerId = stub-cust-code
format=xml
method= jingdong.hufu.entryorder.query
sign_method=md5
timestamp=2015-04-26 00:00:07
v=1.0
连接字符串
连接参数名与参数值,并在首尾加上secret,此处假设secret=test,如下:
testapp_keytesterp_appkeycustomerIdstub-cust-codeformatxmlmethodjingdong.hufu.itemlack.reportsign_methodmd5timestamp2015-04-26 00:00:07v1.0bodytest
其中:body用请求中的body数据代替
生成签名 sign
32位大写MD5值-> D06D88CB34B2EC0E5C9BAB396C9542B6
拼装URL请求
将所有参数值转换为UTF-8编码,然后拼装,并作URL ENCODING 如下:
【http://[ hufu_webservice_url]?method=jingdong.hufu.itemlack.report×tamp=2015-04-26+00%3A00%3A07&format=xml&app_key=testerp_appkey&v=1.0&sign=D06D88CB34B2EC0E5C9BAB396C9542B6&sign_method=md5&customerId=stub-cust-code