积分兑换

积分接入API

商家有自己的积分系统，积分兑换相关系统通过对接商家积分服务实现定制化的积分定制兑换商城。

  1. 文档说明

1.1 目标

本文档对京东科技江湖积分平台合作商户的积分对接进行详细说明，帮助商户方便快捷、安全的对接京东科技江湖积分平台。

1.2 阅读对象

本文档的阅读对象是与京东科技江湖积分平台对接的商户技术人员。

1.3 业务术语

描述
请求 江湖积分平台以字符串形式把需要传输的数据发送给合作商户的过程
响应 合作商户返回处理结果给江湖积分平台的过程
江湖积分平台 积分请求调用方
商户积分系统 积分服务提供方

1.4 关键业务调用流程

1.5 API生产对接流程

对接开发手册、rsa密钥生成工具、SDK 见 起步章-API对接2.0

1、【对接商户】生成商户密钥：由【对接商户】操作

2、上线生产前【对接商户】把生成的公钥发送给京东江湖侧，jdd.esu.appId、jdd.esu.openPublicKey（京东公钥） 由京东江湖提供给【对接商户】

3、替换SDK，jdd_sdk_config.properties文件，配置替换jdd.esu.appId、jdd.esu.server、jdd.esu.openPublicKey、jdd.esu.appPrivateKey

数据传输加密配置jdd.esu.encryptType=3DES_RSA，无需加密可配置为jdd.esu.encryptType=NONE

4、配置完成后，调用sdk方法生产联调测试

2.安全与开发规范

2.1 安全机制

为确保消息安全准确且不被篡改，接口交互安全机制采用（sdk支持自动进行加解密和验签）：

  • 核心业务参数，调用方采用DES3加密后放置在bizContent字段，接收方通过网关sdk解密后的明文参数，再进行业务逻辑处理；
  • 消息体增加签名机制，调用方对消息体用RSA私钥进行加签，接收方用RSA公钥验签；

2.2 接口幂等要求

（1）积分发放接口：同一笔交易流水(唯一标识-业务流水号)只能执行发放一次

（2）积分扣减接口：同一笔交易流水(唯一标识-业务流水号)只能执行扣减一次

（3）积分退回接口：同一笔交易流水(唯一标识-业务流水号)只能执行退回一次，且同一笔原单(唯一标识-原交易流水号)直接退回一次

（4）回执通知接口：同一笔交易流水(唯一标识-业务流水号)只能处理一次业务逻辑

3.接口接入方式

3.1 HTTP POST请求

描述： 【江湖积分平台】通过HTTP POST方式请求【商户积分系统】，【商户积分系统】接受请求并处理完成后，同步返回响应给【江湖积分平台】。

具体接口定义参见第4章。

** 【接口超时时间】：3s以内 **

3.2 HTTP POST请求规范

(1) 请求使用HTTP POST的方式

(2) 使用UTF-8编码

(3)请求参数使用x-www-form-urlencoded格式，响应参数使用JSON格式

查询积分

4.4 查询积分

4.4.1 描述

此接口用来查询用户在商户侧的积分资产。

4.4.2 请求报文

参数 参数说明 类型 备注 可否为空
userAccountId 用户Id String 不可空

请求原文示例：

示例：https://xxx.yy.com/v1/jdtx/queryPoints

参数：

{
  "encrypt":"1pVNbtTMyuzfky0bvFkYNfrf8dG7CfNuqIN+epGDKXzJjAOpZ8Sm30oeCm+wCOrl8ZCwkpZbWI5xup0drVfHtkw6Ae5gOU2xZge4HcypJqE="
}
1
2
3

encrypt解密后明文

{
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f"
}
1
2
3

4.4.3 返回报文

解密后明文

参数 参数说明 类型 备注 可否为空
bizCode 调用结果返回码 Integer code枚举（1：成功， 失败：-1） 不可空
bizMsg 调用结果描述 String 交易成功的时候，该字段可为空，交易失败时，该字段返回相应错误信息 可空
pointAmountAvailable 可用积分积分数量 BigDecimal 2位精度 不可空

返回原文示例：

{
    "bizCode":"1",
    "bizMsg":"success",
    "pointAmountAvailable":"1"
}
1
2
3
4
5

扣减积分

4.5 扣减积分

4.5.1 描述

此接口用来扣减用户在商户侧的积分资产。

4.5.2 请求报文

参数 参数说明 类型 备注 可否为空
userAccountId 用户Id String 不可空
pointsAmount 积分数量 BigDecimal 2位精度 不可空
eventType 事件类型 Integer 事件类型(100：积分兑换商品消耗 101:积分营销活动消耗 102:积分过期消耗) 不可空
description 描述 String 可空
xcTradeNo 江湖积分交易单号 String 不可空
tradeType 交易类型 String 交易类型（order 订单支付） 不可空
orderNo 京东江湖订单号 String 京东江湖平台订单号,可以到江湖系统查询订单信息，注意非京东商城主站订单号！ 不可空

请求示例：

示例：https://xxx.yy.com/v1/jdtx/costPoints 参数:

{
  "encrypt":"IyvcmvBTe+y859lSBAVwM9b6ntXLk2rlg2NOtf6vykUKQQm6sVcff3GhXX2S+oGoyFgIe3KPR9io9goc35WOgwztzJsQoizJxSKxuE9oHNSTB19rk2U3aCr1Y/00a9SlBW3Be2CcLj7TXPGmlH991knvJAfs01zlQ9h4ggjXK4cYC2b+LVMuT5lTGEb3zjIg0T0oLqaphxRYoBbmqVKhnBHg932Oo/7f"
}
1
2
3

encrypt解密后明文：

{
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f",
    "pointsAmount":1,
    "eventType":100,
    "description":"123123123-orderCost",
    "xcTradeNo":"xc-order-800002020",
    "tradeType":"order",
    "orderNo":"4200395876107353"
}
1
2
3
4
5
6
7
8
9

4.5.3 返回报文

解密后明文

公共返回参数 见4.2 不可空
bizCode 调用结果返回码 Integer code枚举（1：成功， 失败：-1） 不可空
bizMsg 调用结果描述 String 交易成功的时候，该字段可为空，交易失败时，该字段返回相应错误信息 可空
shopTradeNo 商户端业务单号 String 商户侧返回的业务单号 不可空

返回原文示例：

{
    "bizCode":"1",
    "bizMsg":"success",
    "shopTradeNo":"123"
}
1
2
3
4
5

退回积分

4.6 退回用户积分

4.6.1 描述

此接口退回用户被扣减的积分资产，主要应用场景：当积分订单履约失败后或者售后订单取消，要退回用户的积分资产。

4.6.2 请求报文

参数 参数说明 类型 备注 可否为空
userAccountId 用户Id String 不可空
pointsAmount 积分数量 BigDecimal 2位精度 不可空
eventType 事件类型 Integer 110：积分兑换商品消耗回退，111：积分营销活动消耗回退（事件类型为交易类型的子类型） 不可空
description 描述 String 可空
xcTradeNo 江湖积分交易单号 String 不可空
oldXcTradeNo 江湖积分原业务单号 String 不可空
description 积分交易操作描述 String 可空
tradeType 交易类型 String 交易类型（orderBack 订单支付） 不可空
oldShopTradeNo 商家积分系统原始扣减单号 String 不可空

请求原文示例：

示例：https://xxx.yy.com/v1/jdtx/costBackPoints

参数：

{
 "encrypt":"cWagMZUySGRxr2/qnrE8ObpPuIfs2XHdsd55I0fA1M2Gc8azVyy6tJkXimOu9vMEk8bvhjb4tnWaQzcNb3GEZNIec8i2nlZQh3nmQrXSHr6YqGCcQGfLe2QBWMbWcharKBA0qBr5yN2UaTy9BjttB1+ETjURtxm4D9KD4hVKCwsuUalqFY3BouNfkJxnvkENfIyuLh690qhTfrJPC+Yf9XUR0sLg02JoZTfnxLaXXB/rEKs7VT0mmDSIFJJuJiTgNN8mp+3UIwQu2zKs7AInWVjQZ9sL3+jz"
}
1
2
3

encrypt解密后明文：

{
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f",
    "pointsAmount":1,
    "xcTradeNo":"xc-order-800002020",
    "eventType":"110",
    "description":"积分兑换商品消耗回退",
    "oldXcTradeNo":"111",
    "tradeType":"orderBack",
    "oldShopTradeNo":"123123"
}
1
2
3
4
5
6
7
8
9
10

4.6.3 返回报文

解密后明文

参数 参数说明 类型 备注 可否为空
bizCode 调用结果返回码 Integer code枚举（1：成功， 失败：-1） 不可空
bizMsg 调用结果描述 String 交易成功的时候，该字段可为空，交易失败时，该字段返回相应错误信息 可空
shopTradeNo 商户端业务单号 String 商户侧返回的业务单号 不可空

返回原文示例：

{
    "bizCode":"1",
    "bizMsg":"success",
    "shopTradeNo":"123"
}
1
2
3
4
5

充值积分

4.7 充值积分

4.7.1 描述

此接口用来将商户侧的积分资产发放给用户。

4.7.2 请求报文

参数 参数说明 类型 备注 可否为空
userAccountId 用户Id String 不可空
pointsAmount 积分数量 BigDecimal 2位精度 不可空
eventType 事件类型 Integer 事件类型(105:用户积分发放) 不可空
description 描述 String 可空
xcTradeNo 星辰交易单号 String 不可空
tradeType 交易类型 String 交易类型（send 发放积分） 不可空

请求示例：

示例：https://xxx.yy.com/v1/jdtx/costPoints

参数:

{
 "encrypt":"wQTxqb1F09+NfXCSfDjtIKqVi/52I4qhClcMBWn/dou3fjVItOAufQpUo30CH4qUjhPuoVE61yt4wtvGmJtgvBKfpZx5nchjqr/0B9AoqE6nn886XFW2mWf8ihfHwzXfKn3ZIAHBrzGOHrCPXm5q4h6iTXJFR5DaRBTWEG5nEafDpzLM/ZIgUw3wZnnB6TiMS+Va0GXQcq94TfbWiZx4rQ=="
}
1
2
3

encrypt解密后明文：

{
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f",
    "pointsAmount":1,
    "xcTradeNo":"111",
    "eventType":"105",
    "description":"充值积分",
    "tradeType":"send"
}
1
2
3
4
5
6
7
8

4.7.3 返回报文

解密后明文

参数 参数说明 类型 备注 可否为空
bizCode 调用结果返回码 Integer code枚举（1：成功， 失败：-1） 不可空
bizMsg 调用结果描述 String 交易成功的时候，该字段可为空，交易失败时，该字段返回相应错误信息 可空
shopTradeNo 商户端业务单号 String 商户侧返回的业务单号 不可空

返回原文示例：

{
    "bizCode":"1",
    "bizMsg":"success",
    "shopTradeNo":"123"
}
1
2
3
4
5

查询积分消耗明细

4.8 查询积分消耗明细

4.8.1 描述

此接口用来查询商户侧的积分消耗明细。

4.8.2 请求报文

参数 参数说明 类型 备注 可否为空
pageNo 分页页码 Integer 不可空
pageSize 分页大小 Integer 不可空
userAccountId 用户Id Integer 不可空

请求示例：

示例：https://xxx.yy.com/v1/jdtx/queryPointsDetailList参数:

{
 "encrypt":"0aKcFTpwrwhFHvQJzlyK66ezcarolGmNqSRPQm8jiDjU5rrFBvkthmVsfycKNTRtb9J428X3HfWUbJERKmJzLtCo3N1SDNGi4YQrXgv9FI8="
}
1
2
3

encrypt解密后明文：

{
    "pageNo":1,
    "pageSize":10,
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f"
}
1
2
3
4
5

4.8.3 返回报文

解密后明文

参数 参数说明 类型 备注 可否为空
bizCode 调用结果返回码 Integer code枚举（1：成功， 失败：-1） 不可空
bizMsg 调用结果描述 String 交易成功的时候，该字段可为空，交易失败时，该字段返回相应错误信息 可空
pageTotalPage 总页数 Integer 不可空
pageNo 当前分页页码 Integer 不可空
pageSize 当前分页大小 Integer 不可空
pageTotalCount 总条数 Integer 不可空
data 数据List Object 不可空

data:

参数 参数说明 类型 备注 可否为空
tradeType 交易类型 String 交易类型：order订单消耗、orderBack订单退还积分、send发放积分 不可空
description 积分操作描述 String 积分操作描述，例如：七日签到积分发放、订单消耗积分等 不可空
pointsAmount 积分数量 BigDecimal 二位小数精度 不可空
createdTime 创建时间 Date 时间戳 不可空

返回原文示例：

{
    "bizCode":"1",
    "bizMsg":"success",
    "pageTotalPage":"1",
    "pageNo":"1",
    "pageSize":"10",
    "pageTotalCount":"2",
    "data":[
        {
            "tradeType":"order",
            "description":"扣减",
            "pointsAmount":"1",
            "createdTime":"yyyyhhmmss"
        },
        {
            "tradeType":"order",
            "description":"扣减",
            "pointsAmount":"1",
            "createdTime":"yyyyhhmmss"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

积分交易通知

4.9 积分交易通知接口

4.9.1 描述

此接口用来同步【积分扣减】/【积分退回】/【积分充值】的交易类操作结果，积分扣减成功/失败结果都会通知给商户侧积分系统，用来保证交易双方业务状态一致。

主要应用场景：

接口调用超时或者【网络故障】江湖积分平台未接收到响应，江湖积分平台无法判断商户侧积分是否操作成功，此时调用方按照扣减失败处理，并通知扣减结果给商户侧，商户侧根据通知结果判断双方积分操作结果状态是否一致，不一致则需要报警人工介入处理。

注意:

(1)商户侧积分系统接收到通知后，返回http state=200 则认为通知成功，不成功则每间隔1小时重试一次，最大重试48次。

4.9.2 请求报文

参数 参数说明 类型 备注 可否为空
userAccountId 用户Id String 不可空
xcTradeNo 江湖积分订单号 String xcTradeType=send【积分充值订单号】 xcTradeType=order【积分扣减订单号】 xcTradeType=orderback【积分退回订单号】 不可空
xcTradeTime 江湖积分订单时间 String 格式:yyyyMMddHHmmss xcTradeType=send【积分充值时间】 xcTradeType=order【积分扣减时间】 xcTradeType=orderback【积分退回时间】 不可空
xcTradeStatus 江湖积分订单状态 String 订单状态(-1:失败 1：成功) xcTradeType=send【-1：充值失败、1：充值成功】 xcTradeType=order【-1：扣减失败、1：扣减成功】 xcTradeType=orderback【-1：退回失败、1：退回成功】 不可空
extInfo 扩展字段 String 【Map】格式 xcTradeType=send【空】 xcTradeType=order【空】 xcTradeType=orderback 【extInfo="{"xcDeductOrderNo":"江湖积分扣减原单号"}"】 可空
xcEventType 交易类型 String 交易事件类型(100:积分兑换商品消耗 101:积分营销活动消耗 105:活动用户积分发放 110:积分兑换商品消耗回退 111:积分营销活动消耗回退 117:抽奖扣积分) 不可空
xcPointsAmount 积分数量 BigDecimal 小数二位精度 不可空
xcTradeType 交易类型 String 交易类型：order=扣减 orderback=退回 send=充值 不可空

请求示例：

示例：https://xxx.yy.com/user/v1/jdtx/notifyPointsEvent

参数：

{
  "encrypt":"M7Kcct7LqQf2Hqjdz3nNwladVYf2xaLetsZ50rloQq6FyJBj7+y1rnSEY6hBt1gAm75trF8SJXjG3K5nYavca/NQNsQcQex1QV75rAOh5+793pit62hwdwrWveJJWdrAQV75rAOh5+4Q7rrxFUfAx/IpLrtdrHBySIOvyvjHhup5zBujiTXEXQcKU4Su7rH71ZUSEZ59sCA="
}
1
2
3

encrypt解密后明文：

{
    "xcTradeStatus":"1",
    "userAccountId":"4a5634fca025625860d8f3ad9c3b005f",
    "xcTradeNo":"146437474",
    "xcTradeTime":"20211103171330",
    "xcPointsAmount":1,
    "extInfo":null,
    "xcTradeType":"order",//积分扣减
    "xcEventType":"100"//积分兑换商品消耗
}
1
2
3
4
5
6
7
8
9
10

扣减通知示例(原文)：

{
    "userAccountId":"商户侧的用户ID",
    "xcTradeTime":"yyyyMMddHHmmss",//江湖积分扣减时间
    "xcTradeNo":"20200731105018-10",//江湖积分扣减单号
    "xcPointsAmount":999,//江湖积分扣减金额
    "xcTradeStatus":1, //订单状态
    "extInfo":null,
    "xcTradeType":"order",//积分扣减
    "xcEventType":"100"//积分兑换商品消耗
}
1
2
3
4
5
6
7
8
9
10
11

退回通知示例(原文):

{
    "userAccountId": "商户侧的用户ID", 
    "xcEventType": 110, //110-积分兑换商品消耗回退
    "xcTradeNo": "20200731105019-11", //江湖积分退回单号
    "xcTradeTime":"yyyyMMddHHmmss", //江湖积分退回时间
    "xcPointsAmount": 999, //江湖积分退回金额
    "xcTradeStatus": 1, //订单状态
    "extInfo": "积分回退",
    "xcTradeType":"order",//积分退回
}
1
2
3
4
5
6
7
8
9
10
11

发放通知示例(原文)：

{
    "userAccountId": "商户侧的用户ID", 
    "xcEventType": 105, //105-积分发放
    "xcTradeNo": "20200731105019-11", //江湖积分发放单号
    "xcTradeTime":"yyyyMMddHHmmss", //江湖积分发放时间
    "xcPointsAmount": 999, //江湖积分发放金额
    "xcTradeStatus": 1, //订单状态
    "extInfo": "积分回退",
    "xcTradeType":"send",//积分发放
}
1
2
3
4
5
6
7
8
9
10

4.9.3 返回报文

无

5.附录

5.1 本地测试

若使用postman进行自测，要在Headers中填写以下字段，请求参数放在Body中，以json类型存放

{
    "Content-Type":"application/x-www-form-urlencoded",//请求参数形式
    "jrgw-request-time":"",//请求时间
    "jrgw-enterprise-user-id":"",//请求用户id
    "jrgw-user-id-type":"",//请求用户类型
    "gw-encrypt-type":"3DES_RSA",//网关加密类型
    "gw-sign-type":"SHA256withRSA",//网关加签类型
    "gw-sign":"",//网关签名
    "jrgw-env-key":""//解密字段
}
1
2
3
4
5
6
7
8
9
10

扣减积分样例：

{
    "Content-Type":"application/x-www-form-urlencoded",//请求参数形式
    "jrgw-request-time":"20211103021436319",//请求时间
    "jrgw-enterprise-user-id":"4a5634fca025625860d8f3ad9c3b005f",//请求用户id
    "jrgw-user-id-type":"0",//请求用户类型
    "gw-encrypt-type":"3DES_RSA",//网关加密类型
    "gw-sign-type":"SHA256withRSA",//网关加签类型
    "gw-sign":
    "XC0fhCgrifyu8XNVOS/dnDfo4NadxIbfZmktAaqrZ7n6gjBvV9EQ8BHlzYC4LpjGxzBrCxk8bgethtB2jq+RIUOnuxScWuKr1wxDSGeSwrIVovjtOnEVDWLf72jMOzB/T3JT00mzyI/PRewHwgZGKRBSmjA8z1Y3y+Wt73182LKj+bQcR6fAHG2GdIRDviX4qxIyi71aW71CfuoqJ3Kssa5XSSRUrbpGSefbx3VRe2b10tDEMbePR2YcWE826ef9At5WVI87t+iJFGODD0ZSkhKJR5ewh7omQ2su1AKxiueYeusKUl5vt+Adxzspuouzi/1zY7ndg8Zat7+SyOeZTA==",//网关签名
    "jrgw-env-key":"XC0fhCgrifyu8XNVOS/dnDfo4NadxIbfZmktAaqrZ7n6gjBvV9EQ8BHlzYC4LpjGxzBrCxk8bgethtB2jq+RIUOnuxScWuKr1wxDSGeSwrIVovjtOnEVDWLf72jMOzB/T3JT00mzyI/PRewHwgZGKRBSmjA8z1Y3y+Wt73182LKj+bQcR6fAHG2GdIRDviX4qxIyi71aW71CfuoqJ3Kssa5XSSRUrbpGSefbx3VRe2b10tDEMbePR2YcWE826ef9At5WVI87t+iJFGODD0ZSkhKJR5ewh7omQ2su1AKxiueYeusKUl5vt+Adxzspuouzi/1zY7ndg8Zat7+SyOeZTA=="//解密字段
}
1
2
3
4
5
6
7
8
9
10
11
12

postman测试样例链接（包含积分扣减，积分查询，积分退回，积分发放，积分明细查询，积分交易通知的测试用例，可自行导入使用）：

  • https://www.getpostman.com/collections/1db8cd0489256db696b8

5.2 调用方法

  • 反向调用SPI类型**（包含积分扣减，积分查询，积分退回，积分发放，积分明细查询）**

注意：适用京东数科通知合作伙伴接口，并且需要合作伙伴返回结果的场景 。

第一步：启动

Spring Boot 项目， JD 测访问 ip: 端口 /spi/demo

第二步：加载

jdd_sdk_config.properties 配置文件的信息，读取应用 ID 、密钥、加密方式、加签方式

DefaultSpiJddClient defaultSpiJddClient = new DefaultSpiJddClient(EsuSdkConfig.getAppInfo());

第三步：接受

JD 测发送过来的数据，函数内部已经做好对 JD 测密文数据进行解密验签工作

String bizContent = defaultSpiJddClient.receive(request);
1

第四步：商户对明文

bizContent 做业务逻辑处理

第五步：响应

JD 测信息，函数内部已做好对商户发送给 JD 测信息的加密加签工作

String body = defaultSpiJddClient.callback(request, response, spiResponse);
response.getWriter().write(body);
1
2

调用示例：

public class SpiDemoController {
@PostMapping("/demo")
public void demo(HttpServletRequest request, HttpServletResponse response) throws Exception {
    DefaultSpiJddClient defaultSpiJddClient = new DefaultSpiJddClient(EsuSdkConfig.getAppInfo());
	String bizContent = defaultSpiJddClient.receive(request);
	log.info("demo request,bizContent={}", bizContent);
	/* 
		TODO 如下是业务逻辑开始
	*/
	Map<String, String> responseDemo = new HashMap<>();
	responseDemo.put("respDemo", bizContent);
	/* 
		业务逻辑结束，开始封装响应
	*/
	SpiResponse spiResponse = new SpiResponse("000000", "成功",DateUtils.formatDate(new Date(), "yyyyMMddHHmmss"),
JacksonUtils.toJson(responseDemo));
	String body = defaultSpiJddClient.callback(request, response, spiResponse);
	log.info("demo response,body={}", body);
	//获得字符输出流
	response.setCharacterEncoding("utf-8");
	PrintWriter writer = response.getWriter();
	writer.write(body);
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
  • 反向通知NAPI类型**（包含积分交易通知）**

注意：适用合作伙伴通知商户，合作伙伴方接口必须保持幂等

第一步：启动

Spring Boot 项目， JD 测访问 ip: 端口 /napi/demo

第二步：加载

jdd_sdk_config.properties 配置文件的信息，读取应用 ID 、密钥、加密方式、加签方式

DefaultNapiJddClient defaultNapiJddClient = new DefaultNapiJddClient(EsuSdkConfig.getAppInfo());
1

第三步：接受

JD 测发送过来的数据，函数内部已经做好对 JD 测密文数据进行解密验签工作

OutResponse notifyContent = defaultNapiJddClient.notify(request);
1

第四步：商户对明文

bizContent 做业务逻辑处理

调用示例：

public class NapiDemoController {

@PostMapping("/demo")
public void demo(HttpServletRequest request, HttpServletResponse response) throws Exception {
	DefaultNapiJddClient defaultNapiJddClient = new DefaultNapiJddClient(EsuSdkConfig.getAppInfo());
	OutResponse notifyContent = defaultNapiJddClient.notify(request);
	log.info("demo request,notifyContent={}", notifyContent);
    /* 
        TODO 如下是业务逻辑
    */
	response.getWriter().write("OK");
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13

订单API

6.API调用-对接流程

对接开发手册、rsa密钥生成工具、SDK 见 起步章-API对接2.0

6.1 【对接商户】生成商户密钥：由【对接商户】操作

密钥生成工具：OpenSSL(RSA公私钥生成工具).rar

【对接商户】通过该密钥生成工具，生成商户的公钥和私钥，私钥为app_rsa_private_pkcs8_key.pem，公钥为app_rsa_public_key.pem。

6.2 上线生产前【对接商户】把生成的公钥发送给京东江湖侧，jdd.esu.appId、jdd.esu.openPublicKey（京东公钥） 由京东江湖提供给【对接商户】

6.3 替换SDK，jdd_sdk_config.properties文件，配置替换jdd.esu.appId、jdd.esu.server、jdd.esu.openPublicKey、jdd.esu.appPrivateKey

数据传输加密配置jdd.esu.encryptType=3DES_RSA，无需加密可配置为jdd.esu.encryptType=NONE

6.4 配置完成后，调用sdk方法生产联调测试

订单列表查询

7.1. 订单列表

接口描述

请求URI：/smapi/v1/jdtx/listOrderDto

请求方式：POST

请求类型：application/json 响应类型：application/json

加密方式：NONE,RSA,ENV_RSA,3DES_RSA

签名方式：MD5_RSA,SHA256withRSA,SHA1withRSA

7.1.1. 请求公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-request-time string header 必填 请求时间
2 jrgw-enterprise-user-id string header 必填 用户ID
3 jrgw-user-id-type string header 必填 用户ID类型
4 gw-encrypt-type string header 必填 加密方式
5 gw-sign-type string header 必填 签名方式
6 gw-sign string header 必填 签名
7 jrgw-env-key string header 非必填 请求信封

7.1.2. 请求业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 orderNo string body 非必填 订单号
1.2 createBeginDate string body 非必填 创建查询时间-开始,格式：yyyy-MM-dd HH:mm:ss
1.3 createEndDate string body 非必填 创建查询时间-结束格式：yyyy-MM-dd HH:mm:ss
1.4 pageNo integer body 必填 当前页码
1.5 pageSize integer body 必填 分页size

7.1.3. 响应公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-resp-code string header 必填 返回码
2 jrgw-resp-msg string header 必填 返回码描述
3 jrgw-respond-time string header 必填 响应时间
4 jrgw-resp-env-key string header 非必填 响应信封
5 gw-encrypt-type string header 必填 加密方式
6 gw-sign-type string header 必填 签名方式
7 gw-sign string header 必填 签名

7.1.4. 响应业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 resultCode string body 必填 业务返回码
1.2 resultMsg string body 非必填 业务返回信息
1.3 value array body 必填 订单列表
1.3.1 orderDto object body 必填 订单数据
1.3.1.1 orderNo string body 必填 订单号
1.3.1.2 originalAmount amount body 必填 原价
1.3.1.3 orderAmount amount body 必填 订单价
1.3.1.4 actualPayAmount amount body 必填 实际支付金额
1.3.1.5 benefitAmount amount body 必填 优惠金额
1.3.1.6 freight amount body 必填 运费
1.3.1.7 orderStatus integer body 必填 订单状态
1.3.1.8 payStatus integer body 必填 支付状态
1.3.1.9 points amount body 必填 积分
1.3.1.10 expressCompany string body 必填 快递公司
1.3.1.11 expressNo string body 必填 快递单号
1.3.1.12 finishedDate date body 必填 确认收货时间
1.3.1.13 createOrderDate date body 必填 订单创建时间
1.3.1.14 orderProductDtoList array body 必填 订单商品列表
1.3.1.14.1 productDto object body 必填 订单商品数据
1.3.1.14.1.1 productId long body 必填 商品编码
1.3.1.14.1.2 productName string body 必填 商品名称
1.3.1.14.1.3 picture string body 必填 商品图片
1.3.1.14.1.4 quantity string body 必填 商品数量
1.3.1.15 receiverName string body 必填 收货人姓名,脱敏数据
1.3.1.16 receiverPhone string body 必填 收货人电话,脱敏数据
1.3.1.17 receiverAddressDetail string body 必填 收货地址,脱敏数据
1.3.1.18 uid string body 必填 用户ID
1.4 pageBean object body 必填 分页对象
1.4.1 pageNo integer body 必填 当前页码
1.4.2 pageSize integer body 必填 分页size
1.4.3 totalRecord integer body 必填 总条数
1.4.4 totalPage integer body 必填 总页数
1.4.5 end boolean body 必填 true最后一页

物流轨迹查询

7.2. 渠道订单物流查询

接口描述：订单物流查询接口，根据uid和订单号查询订单物流信息 webTrackInfo

数据示例：对接时提供 webTrackInfo

解析顺序：根据ziyingShowResult数组数据 和 thirdPsShowResult.thirdPsShowInfoList数组拼接出物流信息链路

请求URI：/smapi/v1/jdtx/getTrackInfo

请求方式：POST

请求类型：application/json 响应类型：application/json

加密方式：NONE,RSA,ENV_RSA,3DES_RSA

签名方式：MD5_RSA,SHA256withRSA,SHA1withRSA

7.2.1. 请求公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-request-time string header 必填 请求时间
2 jrgw-enterprise-user-id string header 必填 用户ID
3 jrgw-user-id-type string header 必填 用户ID类型
4 gw-encrypt-type string header 必填 加密方式
5 gw-sign-type string header 必填 签名方式
6 gw-sign string header 必填 签名
7 jrgw-env-key string header 非必填 请求信封

7.2.2. 请求业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 orderNo string body 必填 订单号
1.2 uid string body 必填 用户Id

7.2.3. 响应公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-resp-code string header 必填 返回码
2 jrgw-resp-msg string header 必填 返回码描述
3 jrgw-respond-time string header 必填 响应时间
4 jrgw-resp-env-key string header 非必填 响应信封
5 gw-encrypt-type string header 必填 加密方式
6 gw-sign-type string header 必填 签名方式
7 gw-sign string header 必填 签名

7.2.4. 响应业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 resultCode string body 必填 业务响应码
1.2 resultMsg string body 必填 业务响应信息
1.3 value object body 必填 data数据
1.3.1 orderNo string body 必填 江湖订单号
1.3.2 uid string body 必填 用户ID
1.3.3 expressNo string body 必填 物流单号
1.3.4 expressCompanyName string body 必填 物流公司名称
1.3.5 webTrackInfo string body 必填 物流json字符串信息

订单消息同步

7.3. 订单消息同步

接口描述：

订单消息同步接口（商家提供post请求url ） 商户自行根据订单号 + requestTime控制消息..处理顺序

biz-content示例：

{"orderNo":"1000001","orderProductDtoList":[{"productId":123,"productName":"商品123"}]}
1

请求URI：/napi/v1/jdtx/orderStatePush

请求方式：POST

请求类型：application/json 响应类型：application/json

加密方式：NONE,RSA,ENV_RSA,3DES_RSA

签名方式：MD5_RSA,SHA256withRSA,SHA1withRSA

重试策略：按递增间隔重试 初始延迟：10m

重试次数：5 延迟倍数：4

7.3.1. 请求公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-request-time string header 必填 请求时间
2 jrgw-notify-no string header 必填 通知流水号
3 jrgw-env-key string header 非必填 请求信封
4 gw-encrypt-type string header 必填 加密方式
5 gw-sign-type string header 必填 签名方式
6 gw-sign string header 必填 签名

7.3.2. 请求业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 orderNo string body 必填 订单号
1.2 originalAmount amount body 必填 原价
1.3 orderAmount amount body 必填 订单价
1.4 actualPayAmount amount body 必填 实际支付金额
1.5 benefitAmount amount body 必填 优惠金额
1.6 freight amount body 必填 运费
1.7 orderStatus integer body 必填 订单状态
1.8 payStatus integer body 必填 支付状态
1.9 points amount body 必填 积分
1.10 expressCompany string body 必填 快递公司
1.11 expressNo string body 必填 快递单号
1.12 finishedDate string body 必填 确认收货时间格式：yyyy-MM-dd HH:mm:ss
1.13 createOrderDate string body 必填 订单创建时间,格式：yyyy-MM-dd HH:mm:ss
1.14 receiverName string body 必填 收货人姓名,脱敏数据
1.15 receiverPhone string body 必填 收货人电话,脱敏数据
1.16 receiverAddressDetail string body 必填 收货地址,脱敏数据
1.17 uid string body 必填 用户ID
1.18 orderProductDtoList array body 必填 订单商品列表
1.18.1 productDto object body 必填 订单商品数据
1.18.1.1 productId long body 必填 商品编码
1.18.1.2 productName string body 必填 商品名称
1.18.1.3 picture string body 必填 商品图片
1.18.1.4 quantity string body 必填 商品数量

7.3.3. 响应公共参数

序号 参数 类型 位置 必填 描述

7.3.4. 响应业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填

商品API

商品对接说明

对接开发手册：京东数科开放平台-接入技术规范v1.0.pdf

rsa密钥生成工具：OpenSSL(RSA公私钥生成工具).rar

SDK（包含 API 网关 SDK 使用指南、README.MD）：

如果使用的java（支持jdk1.7+）、php语言对接，可直接使用SDK开发，SDK已做好封装，调用方只关注业务参数调用即可。

使用说明可参考【SDK（包含 API 网关 SDK 使用指南、README.MD）】 或【京东数科开放平台-接入技术规范v1.0.pdf】的6.2 API 交互 章节。

SDK业务对象在jdd-api-domain-1.0.0.jar（商户请求响应实体类）中。

8.API调用-对接流程

8.1 【对接商户】生成商户密钥：由【对接商户】操作

密钥生成工具：OpenSSL(RSA公私钥生成工具).rar

【对接商户】通过该密钥生成工具，生成商户的公钥和私钥，私钥为app_rsa_private_pkcs8_key.pem，公钥为app_rsa_public_key.pem。

8.2 上线生产前【对接商户】把生成的公钥发送给京东江湖侧，jdd.esu.appId、jdd.esu.openPublicKey（京东公钥） 由京东江湖提供给【对接商户】

8.3 替换SDK，jdd_sdk_config.properties文件，配置替换jdd.esu.appId、jdd.esu.server、jdd.esu.openPublicKey、jdd.esu.appPrivateKey

数据传输加密配置jdd.esu.encryptType=3DES_RSA，无需加密可配置为jdd.esu.encryptType=NONE

8.4 配置完成后，调用sdk方法生产联调测试



商品推荐列表查询

9.1. 渠道-根据场景ID查询推荐商品

接口描述：根据江湖场景ID分页查询推荐商品信息

请求URI：/smapi/v1/jdtx/discoverSkusBySceneId

请求方式：POST

请求类型：application/json 响应类型：application/json

加密方式：NONE,RSA,ENV_RSA,3DES_RSA

签名方式：MD5_RSA,SHA256withRSA,SHA1withRSA

9.1.1. 请求公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-request-time string header 必填 请求时间
2 jrgw-enterprise-user-id string header 必填 用户ID
3 jrgw-user-id-type string header 必填 用户ID类型
4 gw-encrypt-type string header 必填 加密方式
5 gw-sign-type string header 必填 签名方式
6 gw-sign string header 必填 签名
7 jrgw-env-key string header 非必填 请求信封

9.1.2. 请求业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 sceneId string body 必填 江湖场景ID
1.2 pageSize integer body 必填 分页大小，最大20
1.3 jhProjectId string body 必填 江湖项目ID
1.4 lastId string body 必填 上次的lastId，透传即可,非第一页必传,否则导致重复数据

9.1.3. 响应公共参数

序号 参数 类型 位置 必填 描述
1 jrgw-resp-code string header 必填 返回码
2 jrgw-resp-msg string header 必填 返回码描述
3 jrgw-respond-time string header 必填 响应时间
4 jrgw-resp-env-key string header 非必填 响应信封
5 gw-encrypt-type string header 必填 加密方式
6 gw-sign-type string header 必填 签名方式
7 gw-sign string header 必填 签名

9.1.4. 响应业务参数

序号 参数 类型 位置 必填 描述
1 biz-content json body 必填 一级参数
1.1 resultCode string body 必填 业务响应码
1.2 resultMsg string body 必填 业务响应消息
1.3 value object body 必填 推荐数据信息
1.3.1 isEnd boolean body 必填 true是最后一页
1.3.2 lastId string body 必填 最后一条数据ID，查询下一页时的入参
1.3.3 sceneId string body 必填 场景ID
1.3.4 productList array body 必填 商品数据列表
1.3.4.1 productData object body 必填 商品对象
1.3.4.1.1 productId string body 必填 商品编码
1.3.4.1.2 productName string body 必填 商品名称
1.3.4.1.3 picture string body 必填 商品图片url
1.3.4.1.4 productPrice string body 必填 商品价格，isPointsSku==false时展示价格
1.3.4.1.5 productPoints string body 必填 商品积分，isPointsSku==true时展示积分
1.3.4.1.6 isPointsSku boolean body 必填 是否积分sku，true是积分sku
1.3.4.1.7 clickUrl string body 必填 跳转商详页URL
1.3.4.1.8 pointsName string body 必填 积分名称
最后更新: 3/28/2022, 3:48:58 PM

权益产品