虎符ERP多平台融合服务场景

接口规范

修订时间	变更内容	版本号
2019年12月11日	支持鼎内ERP系统和鼎外ERP系统之间双向调用，方便以后扩展	2.0
2019年12月25日	增加修改收获地址接口	2.1
2020年01月02日	订单非敏感获取接口增加orderType参数	2.2
2020年01月02日	增加逆向推送订单非敏感信息接口	2.3
2020年01月02日	增加后端签名（虎符网关转发到后端服务的请求会携带一个sign参数，sign计算方法见文档末）	2.4
2020年06月23日	jingdong.hufu.order.popOrderSearch、jingdong.hufu.order.popOrderGet、jingdong.hufu.order.popOrderPush接口增加orderMarkDesc字段(Map结构：key为TryBeforePayLater为1时代表是京品试订单)	2.5

1. 概述

1.1 需求背景

京东的数据的获取先从云鼎内通过JOS接口获取后进行存储，涉及敏感与非敏感数据的出鼎需求，通过如下的接口标准，通过虎符进行不影响正常业务的有限的出鼎开放。

2. 产品功能

2.1 虎符网关系统需求列表

模块	功能点	详细描述
虎符网关系统	订单敏感信息获取接口
	单个订单非敏感信息获取接口
	条件检索订单非敏感信息获取接口
	发货队列同步接口
	库存更新队列同步接口
	收获地址修改接口
	逆向推送订单非敏感信息接口

2.2虎符网关系统用户

用户	涉及系统
ISV	虎符网关系统

3. 接口规范

3.1 鼎内ERP与虎符的通信协议

3.1.1 协议描述

接口遵循REST规范，使用HTTP POST方式进行通讯。

标准协议的HTTP入口地址为：

ERP发给虎符：

http://[hufu_webservice_url]?method=[hufu_API]&app_key=[erp_appkey]&customerId=[HUFUUSR1]

虎符发给ERP：

http://[erp_webservice_url]?method=[erp_API]&app_key=[externalErp_appkey]&customerId=[HUFUUSR1]

注：

1.[]中需要根据具体业务进行填写。hufu_API，erp_API 在虎符控制台三方互通->我的场景->接入管理->我的API列表可以查看（虎符透传请求给后端服务时method参数会去掉jingdong.hufu.前缀）。

2.URL的系统参数值需要做URL Encoding处理。

3.请求和响应的消息主体使用json格式，字符编码为UTF-8。

4.[hufu_webservice_url]请用虎符网关接入地址代替,[erp_webservice_url]请用ERP系统服务地址代替

5.虎符网关正式：hufu.cn-north-1.jdcloud-api.net

3.1.2 访问授权

目前虎符网关只支持java和python版本的sdk（附件中已提供），如果开发语言不是java或python，需要以http的方式调用api，按照虎符签名算法（https://docs.jdcloud.com/cn/common-declaration/api/authorization-rules）加签，将签名信息放到请求头中，同时，虎符也会提供其他开发语言的签名包，如果开发语言是以下几种的话可以直接使用签名包加签：

 Go

https://github.com/jdcloud-api/jdcloud-sdk-go-signer

 Nodejs

https://github.com/jdcloud-api/jdcloud-sdk-nodejs-signer

 Php

https://github.com/jdcloud-api/jdcloud-sdk-php-signer

 Rust

https://github.com/jdcloud-api/jdcloud-sdk-rust-signer

 .net（如果vs版本是2015，参考 https://github.com/jdcloud-api/jdcloud-sdk-net-signer/tree/master/JDCloud.SDK.Signer）

https://github.com/jdcloud-api/jdcloud-sdk-net-signer

 Cpp

https://github.com/jdcloud-api/jdcloud-sdk-cpp-signer

3.1.3 请求参数

请求参数包含URL中带的系统参数和BODY中带的相关业务参数，系统参数如下：

参数	参数说明	类型	约束
method	ERP相关的业务接口名称，如商品信息同步的请求，method= jingdong.hufu.order.getSensitiveData	string	必须
app_key	应用接入时申请的appkey	string	ERP的appkey
customerId	鼎外ERP系统颁发给用户的ID	string	必须

3.1.4 响应参数

响应参数包含系统参数和业务参数，系统参数如下：

参数	参数说明	类型	约束
code	返回结果代码 0000成功其余失败	string（50）	必须
msg	返回结果说明	string（50）	必须
result	返回结果	string（200）	必须

3.2 虎符与鼎外ERP系统的通信协议

3.2.1 协议描述

接口遵循REST规范，使用HTTP POST方式进行通讯。

标准协议的HTTP入口地址为：

虎符发给鼎外ERP系统：

http://[externalErp_webservice_url]?method=[externalErp_API]&app_key=[erp_appkey]&customerId=[HUFUUSR1]

鼎外ERP系统发给虎符：

http://[hufu_webservice_url]?method=[hufu_API]&app_key=[externalErp_appkey]&customerId=[HUFUUSR1]

注：

1.[]中需要根据具体业务进行填写。hufu_API，externalErp_API 在虎符控制台三方互通->我的场景->接入管理->我的API列表可以查看（虎符透传请求给后端服务时method参数会去掉jingdong.hufu.前缀）。

2.URL需要做URL Encoding处理。

3.请求和响应的消息主体使用json格式，字符编码为UTF-8。

4.[hufu_webservice_url]请用虎符网关接入地址代替，[externalErp_webservice_url]请用鼎外ERP系统服务地址代替

5.虎符网关正式：hufu.cn-north-1.jdcloud-api.net

3.2.2 访问授权

 Go

https://github.com/jdcloud-api/jdcloud-sdk-go-signer

 Nodejs

https://github.com/jdcloud-api/jdcloud-sdk-nodejs-signer

 Php

https://github.com/jdcloud-api/jdcloud-sdk-php-signer

 Rust

https://github.com/jdcloud-api/jdcloud-sdk-rust-signer

 .net（如果vs版本是2015，参考 https://github.com/jdcloud-api/jdcloud-sdk-net-signer/tree/master/JDCloud.SDK.Signer）

https://github.com/jdcloud-api/jdcloud-sdk-net-signer

 Cpp

https://github.com/jdcloud-api/jdcloud-sdk-cpp-signer

3.3.3 请求参数

请求参数包含URL中带的系统参数和BODY中带的相关业务参数，以下是系统参数：

参数	参数说明	类型	约束
method	鼎外ERP系统相关的业务接口名称，如商品信息同步的请求	string	必须
app_key	应用接入时申请的appkey	string	鼎外ERP的appkey
customerId	鼎外ERP系统颁发给用户的ID	string	必须

3.3.4 响应参数

响应参数包含系统参数和业务参数。以下是系统参数：

参数	参数说明	类型	约束
code	返回结果代码 0000成功其余失败	string（50）	必须
msg	返回结果说明	string（50）	必须
result	返回结果	string（200）	必须

4 API文档

api文档，包括调用地址、入参、出参详细定义（点击跳转）

5 SDK下载

java SDK（点击下载）

python SDK（点击下载）

6 后端签名sign计算方法（注意这个签名是后端签名，是后端服务用来验证虎符身份的，调用虎符网关的签名参考上边的访问授权）

我们用虎符网关透传到鼎内ERP服务的请求为例：

    http://test.com?method=order.getSensitiveData&app_key=testerp_appkey&customerId=stub-cust-code&timestamp=2015-04-26%2000:00:07&sign=BEBE2622F988DBD735D6C225C2F8FAC8

输入参数为(如果参数中有类似 timestamp=2015-04-26%2000:00:07 的要把参数 URL Decode之后再计算签名) 注：参数列表中的sign不参与计算签名，除此之外所有参数都要参与计算签名

    method=order.getSensitiveData
    app_key=testerp_appkey
    customerId=test
    timestamp=2015-04-26 00:00:07

按首字母升序排列:

    app_key=testerp_appkey
    customerId=stub-cust-code
    method=order.getSensitiveData
    timestamp=2015-04-26 00:00:07

连接字符串: 连接参数名与参数值,并在首尾加上secret（此处secretKey指的是鼎内ERP应用对应的secretKey），此处假设secret=test，其中：body用请求中的body数据代替，如下：

    testapp_keytesterp_appkeycustomerIdstub-cust-codemethodorder.getSensitiveDatatimestamp2015-04-26 00:00:07bodytest

ERP改造虎符接口标准