虎符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 访问授权

目前虎符网关只支持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.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

生成签名 sign: 32位大写MD5值-> EEF303B02F3A8F6695A631C6F7894986

results matching ""

    No results matching ""