跳转到内容

mall4cloud第三方接口对接协议

S2B2C 白洞版 · mall4cloud第三方接口对接协议

本文给第三方系统(CRM / ERP / WMS / 会员中心)对接商城使用。文中 IP、域名、appId、密钥等均为示例,请换成实际环境的值。

  • 用签名调用开放接口(/open/v1):查订单/支付/库存,查或调积分/余额/成长值。
  • 接收商城出站回调:订单、支付、退款、库存、积分、余额、成长值变更。
  • 用户端四个签名接口:注册用户、同步 token、改昵称、禁用用户。
  • 商家/平台后台菜单接口(/m /p /mp)也可用同一套签名调用,但不作为稳定对接契约,菜单一改路径就会变。稳定对接请只用 /open/v1 和回调。
  1. 在平台后台「系统密钥」创建密钥,拿到 appId(accessId)和 appSecret(accessKey)。
  2. 指定权限密钥:勾选要用的 URI。商家/平台若选「全部权限」(未勾 URI),该端路径都会放行。开放接口 /open/v1 还要求密钥类型与接口所属端一致(见下方清单)。
  3. 商家密钥:绑定店铺。请求 data 里的 shopId 必须与密钥店铺一致。调用 /open/v1 时 data.sysType 必须与密钥类型一致(商家 1、平台 2)。
  4. 需要实时通知:填写商城能访问的 notifyUrl,勾选事件(如 order.status.changed),打开回调开关。字面量 localhost 会被拒绝,请用公网或穿透地址。
  5. 网关地址形如 http://你的域名:8000,下文用 http://localhost:8000 举例。

不要把 appSecret 放到 HTTP 报文或 URL 里,只用于本地计算 sign。请求只传 appId、timestamp、sign,JSON 再加 data。

  • 已拿到可用的 appId、appSecret。
  • 已按实际环境替换文中示例。
  • 请求时间与商城误差不超过 10 分钟。

通讯使用 HTTP。请求头 grantType: sign 表示用密钥签名,而不是登录 token。

开放接口 /open/v1:第三方服务器对接订单、库存、会员资产,见「开放平台 OpenAPI 与出站回调」。

商家端、平台端后台接口:签名代替登录,路径与后台菜单相同,不承诺长期稳定。

用户端:先调四个签名接口注册用户并同步 token,之后用请求头 token 调用户端其它接口。

  • websocket 接口不支持
  • 免登接口不能用签名调用

密钥分商家、平台、用户。商家和平台可按菜单/URI 授权;商家密钥可限定全部店铺或指定店铺。开放接口 /open/v1 按原系统接口所属端限制密钥:订单/支付/库存允许商家与平台;积分/余额/成长值仅平台。用户端、供应商、门店密钥不能调 /open/v1。

商家端、平台端后台菜单接口均可用签名代替登录。 下面热搜、商品搜索只用来说明签名算法,路径会随菜单变化,不作为稳定对接契约。ERP / WMS 请用后文「开放平台 OpenAPI 与出站回调」。

接口报文结构及报文与签名生成

Section titled “接口报文结构及报文与签名生成”

为了区分服务器调用还是普通的用户调用,需要携带请求头“grantType = sign”,grantType这个参数是Oauth2.0协议当中用来确定授权方式的,系统也利用同样的词汇来区分是否为签名验证的用户。同时根据http请求的content-type 不同,如果是application/json这种形式的,json的数据将会被data包裹(通常是post、put、delete请求)。如果只是普通的get请求或图片上传等请求,那么请求的数据不需要被包裹

字段元素 类型 是否必填 说明
grantType String 是 固定为:sign
Content-Type String 是 固定为:application/json
data-type String 否 在参数为纯数组时传参:list
字段元素 类型 是否必填 说明
appId String 是 分配给应用的系统密钥id
timestamp Long 是 请求的时间戳,接入系统的时间误差不能超过 10 分钟,毫秒
sign String 是 签名,通过签名机制,防止应用的请求参数被非法篡改,业务系统必须保证该值不被泄露。
data Object 是 真正请求的数据(当且仅当content-type是application/json的时候,将真正的数据放入data)

为了方便起见,以下所有涉及到签名的,我们使用一个演示签名用的appId和appSecret

appId: appId123456

appSecret: appSecret123456

字段元素 类型 必填条件 说明
sysType String 是 0.用户端 1.商家端 2.平台端 3.供应商端 4.自提门店端
userId String 否 调用用户端接口时必填,用户id,用于定位到具体的用户
shopId String 否 调用商家端接口时必填,商家店铺id,用于定位到具体的店铺
supplierId String 否 调用供应商端接口时必填,供应商店铺id,用于定位到具体的供应商
stationId String 否 调用自提门店端接口时必填,自提门店id,用于定位到具体的自提点
sysUserId String 否 调用平台端接口时必填,平台管理员的账号id,用于定位到具体的管理员账号
其他请求参数 接口的实际请求参数
下面以平台端新增热搜接口来做一个实例讲解:
Section titled “下面以平台端新增热搜接口来做一个实例讲解:”

img.png

接口地址为:/mall4cloud_admin/mp/hot_search

接口请求参数为:

{
"hotSearchId": 0,
"shopId": 0,
"title": "",
"content": "",
"recDate": "",
"seq": 0,
"status": 0
}

实际的请求格式为:

curl --location --request POST 'http://localhost:8000/mall4cloud_admin/mp/hot_search' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
"appId": "appId123456",
"timestamp":1683169451230,
"data":{
"sysType": 2,
"sysUserId": 1,
"hotSearchId": 0,
"title": "热搜标题",
"content": "热搜内容",
"seq": 0,
"status": 1,
"type": 1
},
"sign":"d724ced82e8d098461a7fefd5e4db8fa20acbc890d7facb9941b58b6158e75ba"
}'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

sign: 签名,使用该请求参数生成,生成流程在下面有说明

data.userId : 此次请求使用平台端id为1的管理员账号进行操作

其他data参数为接口的参数

以上就是一个post请求的全部数据了

  1. 拼接json数据,生成post请求签名用到的参数有 appSecret、timestamp和data,具体实例为:
{
"appSecret": "appSecret123456",
"timestamp": "1683169451230",
"data":{
"sysType": 2,
"sysUserId": 1,
"hotSearchId": 0,
"title": "热搜标题",
"content": "热搜内容",
"seq": 0,
"status": 1,
"type": 1
}
}
  1. 对json参数重新进行排序,根据key的值按顺序进行排序,排序后的数据格式为:
{
"appSecret": "appSecret123456",
"data": {
"content": "热搜内容",
"seq": 0,
"status": 1,
"sysType": "2",
"sysUserId": "1",
"title": "热搜标题",
"type": 1
},
"timestamp": "1683169451230"
}
  1. 通过sha256的形式进行签名, 签名结果为:d724ced82e8d098461a7fefd5e4db8fa20acbc890d7facb9941b58b6158e75ba

img.png

在线加密地址:

/**
* 新增热搜接口
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装post请求数据 +++++++++++++++++++++++++++++++++
long timestamp = System.currentTimeMillis();
// 实际的接口数据
TreeMap<String,Object> dataMap = new TreeMap<>();
dataMap.put("content","热搜内容");
dataMap.put("seq", 0);
dataMap.put("type", 1);
dataMap.put("status", 1);
dataMap.put("title","热搜标题");
// 平台账号id
dataMap.put("sysUserId", "1");
dataMap.put("sysType", "2");
TreeMap<String, Object> param = new TreeMap<>();
param.put("timestamp", String.valueOf(timestamp));
param.put("appSecret", "appSecret123456");
param.put("data", dataMap);
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign", sign);
param.put("appId", "appId123456");
// +++++++++++++++++++++++++++++++++ 发送post请求 +++++++++++++++++++++++++++++++++
String result = HttpRequest.post("http://localhost:8000/mall4cloud_admin/mp/hot_search")
.header("grantType","sign")
.header("Accept", "*/*")
.header("Content-Type","application/json")
.body(Json.toJsonString(param))
.execute().body();
System.out.println(result);
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "appSecret123456");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {
System.out.println("success");
}
}
字段元素 类型 是否必填 说明
grantType String 是 固定为:sign
Accept String 是 固定为:/
字段元素 类型 是否必填 说明
appId String 是 分配给应用的系统密钥id
timestamp Long 是 请求的时间戳,接入系统的时间误差不能超过 10 分钟,毫秒
sign String 是 签名,通过签名机制,防止应用的请求参数被非法篡改,业务系统必须保证该值不被泄露。
sysType String 是 0.用户端 1.商家端 2.平台端 3.供应商端 4.自提门店端
userId String 否 调用用户端接口时必填,用户id,用于定位到具体的用户
shopId String 否 调用商家端接口时必填,商家店铺id,用于定位到具体的店铺
supplierId String 否 调用供应商端接口时必填,供应商店铺id,用于定位到具体的供应商
stationId String 否 调用自提门店端接口时必填,自提门店id,用于定位到具体的自提点
sysUserId String 否 调用平台端接口时必填,平台管理员的账号id,用于定位到具体的管理员账号
其他请求参数 接口的实际请求参数

下面以平台端商品搜索接口来做一个实例讲解:
Section titled “下面以平台端商品搜索接口来做一个实例讲解:”

img.png

接口地址为:/mall4cloud_search/p/search/page

接口请求参数为:

current = 1
size = 10

实际的请求格式为:

curl --location --request GET 'http://localhost:8000/mall4cloud_search/p/search/page?sysType=2&sysUserId=1&pageNum=1&pageSize=10&appId=appId123456&sign=计算后的签名&timestamp=1683167795211' \
--header 'grantType: sign'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

userId: 此次请求使用平台端id为1的管理员账号进行操作

sign: 签名,使用该请求参数生成,生成流程在下面有说明

current : 请求接口的参数,查询分页为1的数据

size: 请求接口的参数,每页数据大小为10

以上就是一个get请求的全部数据了

1.拼接json数据,生成get请求签名用到的参数有 appSecret、timestamp和接口中的参数,具体实例为:

注意:get请求的sign获取数据跟post请求相同都是json,不同的是value的值必须是字符串

{
"appSecret": "appSecret123456",
"timestamp": "1683167795211",
"sysType": "2",
"sysUserId": "1",
"pageNum": "1",
"pageSize": "10"
}

2.对json参数重新进行排序,根据key的值按顺序进行排序,排序后的数据格式为:

{
"appSecret": "appSecret123456",
"pageNum": "1",
"pageSize": "10",
"sysType": "2",
"sysUserId": "1",
"timestamp": "1683167795211"
}
  1. 通过 sha256 签名。curl 里的 sign 换成你本地算出的值,不要把 appSecret 放到 URL 上。

img.png

在线加密地址:

/**
* 查询商品接口
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装get请求数据 +++++++++++++++++++++++++++++++++
long timestamp = System.currentTimeMillis();
TreeMap<String, Object> param = new TreeMap<>();
// 平台账号id
param.put("sysType", "2");
param.put("sysUserId", "1");
param.put("timestamp", String.valueOf(timestamp));
param.put("appSecret", "appSecret123456");
// 接口请求参数
param.put("pageNum", "1");
param.put("pageSize", "10");
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign", sign);
param.put("appId","appId123456");
// +++++++++++++++++++++++++++++++++ 发送get请求 +++++++++++++++++++++++++++++++++
String result = HttpRequest.get("http://localhost:8000/mall4cloud_search/p/search/page")
.header("grantType","sign")
.header("Accept", "*/*")
.form(param)
.execute().body();
System.out.println(result);
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "appSecret123456");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {
System.out.println("success");
}
}

第三方必须看外层 code。验签失败、密钥错误、appId 不存在时,外层不是 00000。

场景 外层 code 外层 msg(中文)
accessKey 错、签名算错、报文被改 A00001 签名错误,请检查密钥与签名
appId 未传 A00001 缺少 appId
appId 不存在 A00001 appId 不存在或错误
时间戳超过 10 分钟 A00001 请求时间已超过十分钟
指定权限密钥未勾选该 URI A00004 未授权
密钥类型与接口所属端不符 A00004 未授权
调用 /open/v1 时 data.sysType 与密钥类型不一致 A00004 未授权

失败示例:

{
"code": "A00001",
"msg": "签名错误,请检查密钥与签名",
"data": null
}

请求体只传 appId、timestamp、sign、data。不要把 appSecret 放到 HTTP 报文里,appSecret 只用于本地计算 sign。


签名与上文相同:请求头 grantType: sign,POST JSON,data 包业务字段。签名原文为按 key 排序后的 appSecret、data、timestamp,再 SHA256。网关路径带服务名前缀。

金额单位一律为分。成功时外层 code 为 00000。

均为 POST。指定权限密钥须勾选对应 URI;商家/平台若选「全部权限」(未勾 URI),该端路径都会放行。调用 /open/v1 时 data.sysType 必须与密钥类型一致(旧 /m /p 不比这项)。用户端、供应商、门店密钥不能调 /open/v1。

Path 说明 密钥类型
/mall4cloud_order/open/v1/order/get 订单详情(同商家/平台订单) 商家、平台
/mall4cloud_order/open/v1/order/page 按下单时间翻页(补漏、对账) 商家、平台
/mall4cloud_payment/open/v1/payment/get 支付单 商家、平台
/mall4cloud_product/open/v1/stock/get SKU 库存 商家、平台
/mall4cloud_product/open/v1/stock/set 覆盖写入可售库存(须开通 URI,且配置开关,见下) 商家、平台
/mall4cloud_user/open/v1/score/get 本系统用户当前积分(同平台会员) 仅平台
/mall4cloud_user/open/v1/score/adjust 加减积分(同 /p/user_level/batch_user_score) 仅平台
/mall4cloud_user/open/v1/balance/get 本系统用户当前可用余额 仅平台
/mall4cloud_user/open/v1/balance/adjust 加减余额(同平台批量改余额) 仅平台
/mall4cloud_user/open/v1/growth/get 本系统用户当前成长值 仅平台
/mall4cloud_user/open/v1/growth/adjust 加减成长值(同 /p/user_level/update_growth) 仅平台

公共 data 字段:sysType 与密钥类型相同;商家必填 shopId。

订单查询示例:

Terminal window
curl --location --request POST 'http://localhost:8000/mall4cloud_order/open/v1/order/get' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
"appId": "appId123456",
"timestamp": 1683169451230,
"sign": "计算后的签名",
"data": {
"sysType": 1,
"shopId": 1001,
"orderId": 2025082500001
}
}'

请求:orderId(必填)。

响应 data:orderId、shopId、userId、status、actualTotal(实付,分)、total(总值,分)、payType、deliveryType(1 快递 2 自提 3 无需快递 4 同城)、payTime(毫秒)、deliveryTime(毫秒)、orderItems(skuId、spuId、count、price、skuName)。

无权限或不存在时失败,不会返回空对象冒充成功。商家只能查密钥店铺范围内的订单。

订单 status:1 待付款,2 待发货,3 待收货,5 成功,6 关闭/失败,7 待成团,8 待采购,9 待付尾款。

请求:startTime、endTime(下单时间,毫秒,必填,跨度最大 7 天)、status(否)、pageNum(从 1)、pageSize(最大 50)。

响应为分页:list、total、pages。用于对账补漏,不要当实时同步。实时用回调。

请求:payId 或 orderId 二选一。

响应:payId、orderIds、payAmount(分)、payStatus、bizPayNo、payType。

支付 payStatus:0 未支付,1 已支付,-1 退款,-2 失败。

get 请求:skuId。响应:skuId、spuId、stock(可售)、lockStock(锁定)、totalStock(总库存)。

set 请求:outBizNo(必填,幂等)、skuId、stock(覆盖写入该库存点的可售库存)、stockPointId(否,库存点/仓库 id;不传或 0 则用该店铺默认仓库)、reason(否)。成功响应带实际写入的 stockPointId。库存存在 Redis,按 skuId_库存点id 分区,不能写 stockPointId=0。仅在约定「以对接方库存为准」时使用。须同时满足:密钥勾选该 URI,且配置 mall4cloud.open.stock-set-enabled=true(默认关闭,只勾 URI 仍会失败)。开通后商城侧改库存也会推 stock.changed。

请求:userId 为本系统用户 ID,不是第三方账号。

响应:

接口 字段
score/get userId、score 当前积分
balance/get userId、actualBalance 当前可用余额(分)
growth/get userId、growth 当前成长值
字段 必填 说明
userId 是 本系统用户 ID
ioType 是 1 加,0 扣
score / amount / growth 是 变动绝对值(正数)。积分 score,余额 amount(分),成长值 growth
outBizNo 是 同一密钥下相同则幂等,返回首次结果,不再加减
source 否 流水来源
remark 否 备注

扣减不足则整笔失败、账不变。成功会写流水;密钥订阅了对应事件会推回调。禁止用调账模拟支付成功。

成长值调账示例(加 10):

Terminal window
curl --location --request POST 'http://localhost:8000/mall4cloud_user/open/v1/growth/adjust' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
"appId": "appId123456",
"timestamp": 1683169451230,
"sign": "计算后的签名",
"data": {
"sysType": 2,
"userId": 20001,
"ioType": 1,
"growth": 10,
"outBizNo": "growth-20250827-001"
}
}'

成功时 data 为调账后的当前值。

在系统密钥上配置公网 notifyUrl 并勾选事件。商城在业务落库后 POST 到该地址,签名算法与入站相同(用密钥的 appSecret,或订阅里单独配的推送密钥)。

接口返回给当前这次 HTTP 调用方;回调推给 notifyUrl(可以是另一套系统)。后台改积分、C 端下单抵扣等,第三方没调 OpenAPI 时,只能靠回调知道。

  • 方法:POST,Header:Content-Type: application/json、grantType: sign
  • 成功:HTTP 200,且 body 为纯文本 SUCCESS,或 JSON 含 "code":"00000"
  • 其它状态、超时、非成功码:失败。同一事件最多 6 次 HTTP(首次立刻,之后约 1s、5s、30s、2m、10m),第 6 次仍失败记死信
  • 先按 data.eventId 去重;已处理仍返回成功
  • 5 秒内应答;慢业务先落库再处理
  • 至少投递一次,允许乱序。以 occurredAt 和 OpenAPI 查询为准
  • 只推已勾选、且店铺与密钥范围匹配的事件。score.changed / balance.changed 的 shopId 固定为 0,指定店铺商家密钥收不到,仅不限店平台密钥能收到。growth.changed 按流水 shopId 匹配
  • 后台按日志手动补推可能不含 payload,不要当全量事件用
{
"appId": "appId123456",
"timestamp": 1730000000000,
"sign": "sha256...",
"data": {
"eventId": "evt_01HXYZ",
"event": "order.status.changed",
"shopId": 1001,
"occurredAt": 1730000000123,
"bizId": "2025082500001",
"payload": {}
}
}

客户验签:用 appSecret + data + timestamp 做 SHA256,与入站相同。时间误差不超过 10 分钟。

event 何时推 payload
order.status.changed 订单创建、支付待发货、发货、完成、关闭 见下
payment.success 支付成功 payId、orderIds、payAmount、payStatus
refund.success 退款/售后成功 refundId、orderId、shopId、userId、refundAmount、refundStatus(成功为 2)
stock.changed 可售库存变更(短时间同一 SKU 会合并为一条最新库存) skuId、stock、lockStock、totalStock、changeType(sale / lock / unlock / set)
score.changed 积分流水落库 userId、score(本次变动)、ioType、source、logId、currentScore(改完后总额)
balance.changed 余额已生效(未支付充值不推) userId、changeBalance(本次变动,分)、ioType、type、balanceLogId、actualBalance(改完后可用余额)
growth.changed 成长值流水落库 userId、changeGrowth(本次变动)、source、bizId、logId、currentGrowth(改完后总额)

order.status.changed 按 payload.status 区分:

  • 创建待付款 status=1:含 orderId、shopId、userId、actualTotal
  • 支付待发货 status=2:另含 payType、payTime
  • 发货 status=3:orderId、status、deliveryType
  • 完成 status=5:orderId、status
  • 关闭 status=6:orderId、status、closeType(1 超时未支付,4 买家取消)

支付成功进入待发货示例:

{
"eventId": "evt_01HXYZ",
"event": "order.status.changed",
"shopId": 1001,
"occurredAt": 1730000000123,
"bizId": "2025082500001",
"payload": {
"orderId": 2025082500001,
"shopId": 1001,
"userId": 20001,
"status": 2,
"actualTotal": 9900,
"payType": 1,
"payTime": 1730000000123
}
}

收到回调后若要全量,再调对应 /open/v1/.../get。

用户端提供四个用签名验签方式调用的接口

  • 注册用户接口
  • 将用户token以及过期时间同步到商城接口
  • 修改用户名称接口
  • 禁用用户接口

通过注册用户(调用注册用户接口)、将token同步到系统中(调用将用户token以及过期时间同步到商城接口),既可正常请求用户端其他接口(请求头传递token形式)

用签名验签方式调用的接口报文结构及报文与签名生成

Section titled “用签名验签方式调用的接口报文结构及报文与签名生成”

为了区分服务器调用还是普通的用户调用,需要携带请求头“grantType = sign”,grantType这个参数是Oauth2.0协议当中用来确定授权方式的,系统也利用同样的词汇来区分是否为签名验证的用户。同时根据http请求的content-type 不同,如果是application/json这种形式的,json的数据将会被data包裹(通常是post、put、delete请求)。如果只是普通的get请求或图片上传等请求,那么请求的数据不需要被包裹

字段元素 类型 是否必填 说明
grantType String 是 固定为:sign
Content-Type String 是 固定为:application/json
字段元素 类型 是否必填 说明
appId String 是 分配给应用的系统密钥id
timestamp Long 是 请求的时间戳,接入系统的时间误差不能超过 10 分钟,毫秒
sign String 是 签名,通过签名机制,防止应用的请求参数被非法篡改,业务系统必须保证该值不被泄露。
data Object 是 真正请求的数据(当且仅当content-type是application/json的时候,将真正的数据放入data)

下面四个涉及签名的接口,这里我是用一个演示的用户端签名

appId: 167633802736

appSecret:3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764

字段元素 类型 必填条件 说明
sysType String 必填 用户端固定为 0
userId String 必填 通信的用户唯一ID,可以随机uuid (建议自己服务端的用户唯一uid)
nickName String 必填 用户昵称,商城有些通知会需要用到

接口地址:/mall4cloud_user/ua/server/user/register

请求类型:post

接口请求参数

{
"sysType": 0,
"userId":"userId33",
"nickName" : "注册用户"
}

实际的请求格式为:

curl --location --request POST 'http://localhost:8000/mall4cloud_user/ua/server/user/register' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId":"167633802736",
    "timestamp":1640761421949,
    "data":{
"sysType": 0,
"userId":"userId33",
"nickName" : "注册用户"
},
    "sign":"计算后的签名"
}'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

sign: 签名,使用该请求参数生成,生成流程在下面有说明

data参数为接口的参数

以上就是一个post请求的全部数据了

1.拼接json数据,生成post请求签名用到的参数有 appSecret、timestamp和data,具体实例为:

{
"appSecret": "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764",
"timestamp": "1640761421949",
"data": {
"sysType": 0,
"nickName" : "注册用户",
"userId":"userId33"
}
}

2.对json参数重新进行排序,根据key的值按顺序进行排序,排序后的数据格式为:

{
"appSecret": "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764",
"data": {
"sysType": 0,
"nickName" : "注册用户",
"userId":"userId33"
},
"timestamp": "1640761421949"
}
  1. 通过 sha256 签名。curl 里的 sign 换成你本地算出的值。不要把 appSecret 放到 HTTP 报文里。

image_2

在线加密地址:

/**
* 注册用户接口
* @param args
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装post请求数据 +++++++++++++++++++++++++++++++++
// 获取时间戳
Long timestamp = System.currentTimeMillis();
// 设置时间戳和密钥
TreeMap<String,Object> param = new TreeMap<>();
param.put("timestamp",timestamp.toString());
param.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
// 实际的接口数据
TreeMap<String,Object> dataMap = new TreeMap<>();
dataMap.put("sysType", "0");
dataMap.put("userId", "userId33");
dataMap.put("nickName","注册用户");
param.put("data", dataMap);
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sysSign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign" , sysSign);
param.put("appId","167633802736");
String result = HttpRequest.post("http://localhost:8000/mall4cloud_user/ua/server/user/register")
.header("grantType","sign")
.header("Content-Type","application/json")
.body(JSONObject.toJSONString(param))
.execute().body();
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {
System.out.println("success");
}
}

将用户token以及过期时间同步到商城接口

Section titled “将用户token以及过期时间同步到商城接口”
字段元素 类型 必填条件 说明
sysType String 必填 用户端固定为 0
userId String 必填 通信的用户唯一ID,可以随机uuid (建议自己服务端的用户唯一uid)
accessToken String 必填 校验的token,随机uuid(建议使用自己服务端的用户的token)
expiresIn Long 必填 token在多少秒后过期
openId String 否 openId,如果当前是在小程序上,则传小程序的openid。如果是在微信浏览器上开打,则传公众号openid
socialType String 否 socialType, 1小程序登录,2公众号登录,0 其他

接口地址:/mall4cloud_user/ua/server/user/token

请求类型:post

接口请求参数

{
"sysType": 0,
"userId":"userId33",
"accessToken" : "token_test",
"expiresIn": "10000",
"openId": "xxxxxx",
"socialType": "1"
}

实际的请求格式为:

curl --location --request POST 'http://localhost:8000/mall4cloud_user/ua/server/user/token' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId":"appId123456",
    "timestamp":1640761421949,
    "data":{
"sysType": 0,
"userId":"userId33",
"accessToken" : "token_test",
"expiresIn": "10000",
"openId": "xxxxxx",
"socialType": "1"
},
    "sign":"计算后的签名"
}'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

sign: 签名,使用该请求参数生成,生成流程在下面有说明

data参数为接口的参数

sign(签名)的生成流程(与注册用户接口一样)
Section titled “sign(签名)的生成流程(与注册用户接口一样)”
/**
* 将用户token以及过期时间同步到商城
* @param args
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装post请求数据 +++++++++++++++++++++++++++++++++
// 获取时间戳
Long timestamp = System.currentTimeMillis();
// 设置时间戳和密钥
TreeMap<String,Object> param = new TreeMap<>();
param.put("timestamp",timestamp.toString());
param.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
// 实际的接口数据
TreeMap<String,Object> dataMap = new TreeMap<>();
dataMap.put("sysType", "0");
dataMap.put("userId", "userId33");
dataMap.put("accessToken","token_test");
dataMap.put("expiresIn",1000L);
dataMap.put("openId","xxxxxxx");
dataMap.put("socialType","1");
param.put("data", dataMap);
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sysSign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign" , sysSign);
param.put("appId","167633802736");
String result = HttpRequest.post("http://localhost:8000/mall4cloud_user/ua/server/user/token")
.header("grantType","sign")
.header("Content-Type","application/json")
.body(JSONObject.toJSONString(param))
.execute().body();
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {
System.out.println("success");
}
}

修改用户接口(用于修改用户昵称)

Section titled “修改用户接口(用于修改用户昵称)”
字段元素 类型 必填条件 说明
sysType String 必填 用户端固定为 0
userId String 必填 通信的用户唯一ID,可以随机uuid (建议自己服务端的用户唯一uid)
nickName String 必填 用户昵称,商城有些通知会需要用到

接口地址:/mall4cloud_user/ua/server/user/update

请求类型:put

接口请求参数

{
"sysType": 0,
"userId":"123",
"nickName": "修改名称"
}

实际的请求格式为:

curl --location --request PUT 'http://localhost:8000/mall4cloud_user/ua/server/user/update' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId":"167633802736",
    "timestamp":1640761421949,
    "data":{
"sysType": 0,
"userId":"123",
"nickName": "修改名称"
},
    "sign":"计算后的签名"
}'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

sign: 签名,使用该请求参数生成,生成流程在下面有说明

data参数为接口的参数

sign(签名)的生成流程(与注册用户接口一样)
Section titled “sign(签名)的生成流程(与注册用户接口一样)”
/**
* 更新用户接口
* @param args
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装put请求数据 +++++++++++++++++++++++++++++++++
// 获取时间戳
Long timestamp = System.currentTimeMillis();
// 设置时间戳和密钥
TreeMap<String,Object> param = new TreeMap<>();
param.put("timestamp",timestamp.toString());
param.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
// 实际的接口数据
TreeMap<String,Object> dataMap = new TreeMap<>();
dataMap.put("sysType", "0");
dataMap.put("userId", "userId33");
dataMap.put("nickName","修改名称");
param.put("data", dataMap);
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sysSign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign" , sysSign);
param.put("appId","167633802736");
String result = HttpRequest.put("http://localhost:8000/mall4cloud_user/ua/server/user/update")
.header("grantType","sign")
.header("Content-Type","application/json")
.body(JSONObject.toJSONString(param))
.execute().body();
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {
System.out.println("success");
}
}
字段元素 类型 必填条件 说明
sysType String 必填 用户端固定为 0
userId String 必填 通信的用户唯一ID,可以随机uuid (建议自己服务端的用户唯一uid)

接口地址:/mall4cloud_user/ua/server/user/disable

请求类型:put

接口请求参数

{
"sysType": 0,
"userId":"123"
}

实际的请求格式为:

curl --location --request PUT 'http://localhost:8000/mall4cloud_user/ua/server/user/disable' \
--header 'grantType: sign' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId":"167633802736",
    "timestamp":1640761421949,
    "data":{
"sysType": 0,
"userId":"123"
},
    "sign":"计算后的签名"
}'

appId:分配给应用的系统密钥id

timestamp: 请求的时间戳,根据当前时间生成

sign: 签名,使用该请求参数生成,生成流程在下面有说明

data参数为接口的参数

sign(签名)的生成流程(与注册用户接口一样)
Section titled “sign(签名)的生成流程(与注册用户接口一样)”
/**
* 禁用用户接口
* @param args
*/
public static void main(String[] args) {
// +++++++++++++++++++++++++++++++++ 组装put请求数据 +++++++++++++++++++++++++++++++++
// 获取时间戳
Long timestamp = System.currentTimeMillis();
// 设置时间戳和密钥
TreeMap<String,Object> param = new TreeMap<>();
param.put("timestamp",timestamp.toString());
param.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
// 实际的接口数据
TreeMap<String,Object> dataMap = new TreeMap<>();
dataMap.put("sysType", "0");
dataMap.put("userId", "userId33");
param.put("data", dataMap);
// 签名(appSecret 只参与本地算签)
Digester sha256 = new Digester(DigestAlgorithm.SHA256);
String sysSign = sha256.digestHex(Json.toJsonString(param));
param.remove("appSecret");
param.put("sign" , sysSign);
param.put("appId","167633802736");
String result = HttpRequest.put("http://localhost:8000/mall4cloud_user/ua/server/user/disable")
.header("grantType","sign")
.header("Content-Type","application/json")
.body(JSONObject.toJSONString(param))
.execute().body();
// +++++++++++++++++++++++++++++++++ 响应数据验签 +++++++++++++++++++++++++++++++++
// 结果验签
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
TreeMap<String, Object> map = new TreeMap<>();
map.put("appSecret", "3bf5e9951ee3406e109389a3118a6f7be15d0339b57dbe2a9db0b0a9149cdf131702370796764");
map.put("data", responseMap.get("data"));
map.put("timestamp", responseMap.get("timestamp"));
// 验签
if (Objects.equals(responseMap.get("sign").toString(), sha256.digestHex(Json.toJsonString(map)))) {System.out.println("success");
}
}

前提:已经注册用户(调用注册用户接口)、并且将token同步到系统中(调用将用户token以及过期时间同步到商城接口)

下面我将通过一个获取用户详情接口(无请求参数)演示

请求头token: 拿上面已经同步到系统的接口token_test

接口请求参数: 具体参数查看接口文档,封装好参数即可 image

/**
* 获取用户详情接口
* @param args
*/
public static void main(String[] args) {
// 请求接口
String result = HttpRequest.get("http://localhost:8000/mall4cloud_user/user/userInfo")
.header("Content-Type","application/json")
// 设置请求头,传已经同步到系统的token
.header("Authorization", "token_test")
.execute().body();
// +++++++++++++++++++++++++++++++++ 获取响应数据+++++++++++++++++++++++++++++++++
// 响应数据
TreeMap<String, Object> responseMap = JSONObject.parseObject(result, TreeMap.class);
System.out.println(responseMap.get("data"));
}

输出结果 img.png

按下面做通即算对接完成:

  1. 用错误 appSecret 调任意 /open/v1:外层 code 为 A00001,msg 为「签名错误,请检查密钥与签名」。
  2. 用正确密钥调 order/get(商家或平台)或 score/get(平台):外层 code 为 00000,能验签响应。
  3. 订阅 order.status.changed,完成一笔支付:notifyUrl 收到 status=2,应答 SUCCESS。
  4. score/adjust 或 growth/adjust 同一 outBizNo 调两次:第二次不重复加减。
  • 密钥或签名错误:看外层 code 是否为 A00001。不要只看 HTTP 200。
  • 指定权限密钥未勾选 URI、用户端/商家密钥调积分等平台接口、调用 /open/v1 时 data.sysType 与密钥类型不一致:外层 A00004。勾选后重新保存密钥。商家/平台「全部权限」密钥不勾 URI 也会放行该端路径。
  • 商家未带 shopId 或店铺与密钥不一致:验签或业务失败。
  • 调账必须带 outBizNo。成长值字段是 growth,不是 score。库存覆盖写入还须配置 mall4cloud.open.stock-set-enabled=true。
  • notifyUrl 请填商城能访问的公网地址。字面量 localhost 会被拒绝。
  • 回调只有摘要:要订单明细再调 /open/v1/order/get。后台手动补推可能没有 payload。
  • 积分/余额回调 shopId 为 0,指定店铺商家密钥收不到。