mall4cloud第三方接口对接协议
S2B2C 白洞版 · mall4cloud第三方接口对接协议
mall4cloud第三方接口对接协议
Section titled “mall4cloud第三方接口对接协议”本文给第三方系统(CRM / ERP / WMS / 会员中心)对接商城使用。文中 IP、域名、appId、密钥等均为示例,请换成实际环境的值。
- 用签名调用开放接口(
/open/v1):查订单/支付/库存,查或调积分/余额/成长值。 - 接收商城出站回调:订单、支付、退款、库存、积分、余额、成长值变更。
- 用户端四个签名接口:注册用户、同步 token、改昵称、禁用用户。
- 商家/平台后台菜单接口(
/m/p/mp)也可用同一套签名调用,但不作为稳定对接契约,菜单一改路径就会变。稳定对接请只用/open/v1和回调。
- 在平台后台「系统密钥」创建密钥,拿到 appId(accessId)和 appSecret(accessKey)。
- 指定权限密钥:勾选要用的 URI。商家/平台若选「全部权限」(未勾 URI),该端路径都会放行。开放接口
/open/v1还要求密钥类型与接口所属端一致(见下方清单)。 - 商家密钥:绑定店铺。请求
data里的shopId必须与密钥店铺一致。调用/open/v1时data.sysType必须与密钥类型一致(商家1、平台2)。 - 需要实时通知:填写商城能访问的
notifyUrl,勾选事件(如order.status.changed),打开回调开关。字面量localhost会被拒绝,请用公网或穿透地址。 - 网关地址形如
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。
商家端、平台端对接
Section titled “商家端、平台端对接”商家端、平台端后台菜单接口均可用签名代替登录。 下面热搜、商品搜索只用来说明签名算法,路径会随菜单变化,不作为稳定对接契约。ERP / WMS 请用后文「开放平台 OpenAPI 与出站回调」。
接口报文结构及报文与签名生成
Section titled “接口报文结构及报文与签名生成”为了区分服务器调用还是普通的用户调用,需要携带请求头“grantType = sign”,grantType这个参数是Oauth2.0协议当中用来确定授权方式的,系统也利用同样的词汇来区分是否为签名验证的用户。同时根据http请求的content-type 不同,如果是application/json这种形式的,json的数据将会被data包裹(通常是post、put、delete请求)。如果只是普通的get请求或图片上传等请求,那么请求的数据不需要被包裹
接口报文规范
Section titled “接口报文规范”POST、PUT、DELETE 请求格式说明
Section titled “POST、PUT、DELETE 请求格式说明”请求头(Header)
Section titled “请求头(Header)”| 字段元素 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| 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
data参数构成
Section titled “data参数构成”| 字段元素 | 类型 | 必填条件 | 说明 |
|---|---|---|---|
| sysType | String | 是 | 0.用户端 1.商家端 2.平台端 3.供应商端 4.自提门店端 |
| userId | String | 否 | 调用用户端接口时必填,用户id,用于定位到具体的用户 |
| shopId | String | 否 | 调用商家端接口时必填,商家店铺id,用于定位到具体的店铺 |
| supplierId | String | 否 | 调用供应商端接口时必填,供应商店铺id,用于定位到具体的供应商 |
| stationId | String | 否 | 调用自提门店端接口时必填,自提门店id,用于定位到具体的自提点 |
| sysUserId | String | 否 | 调用平台端接口时必填,平台管理员的账号id,用于定位到具体的管理员账号 |
| 其他请求参数 | 接口的实际请求参数 | ||
下面以平台端新增热搜接口来做一个实例讲解:
Section titled “下面以平台端新增热搜接口来做一个实例讲解:”
接口地址为:/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请求的全部数据了
sign(签名)的生成流程:
Section titled “sign(签名)的生成流程:”- 拼接json数据,生成post请求签名用到的参数有 appSecret、timestamp和data,具体实例为:
{ "appSecret": "appSecret123456", "timestamp": "1683169451230", "data":{ "sysType": 2, "sysUserId": 1, "hotSearchId": 0, "title": "热搜标题", "content": "热搜内容", "seq": 0, "status": 1, "type": 1 }}- 对json参数重新进行排序,根据key的值按顺序进行排序,排序后的数据格式为:
{ "appSecret": "appSecret123456", "data": { "content": "热搜内容", "seq": 0, "status": 1, "sysType": "2", "sysUserId": "1", "title": "热搜标题", "type": 1 }, "timestamp": "1683169451230"}- 通过sha256的形式进行签名, 签名结果为:d724ced82e8d098461a7fefd5e4db8fa20acbc890d7facb9941b58b6158e75ba

在线加密地址:
java代码示例
Section titled “java代码示例”/*** 新增热搜接口*/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"); }}GET请求格式说明
Section titled “GET请求格式说明”请求头(Header)
Section titled “请求头(Header)”| 字段元素 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| 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 “下面以平台端商品搜索接口来做一个实例讲解:”
接口地址为:/mall4cloud_search/p/search/page
接口请求参数为:
current = 1size = 10实际的请求格式为:
curl --location --request GET 'http://localhost:8000/mall4cloud_search/p/search/page?sysType=2&sysUserId=1&pageNum=1&pageSize=10&appId=appId123456&sign=计算后的签名×tamp=1683167795211' \--header 'grantType: sign'appId:分配给应用的系统密钥id
timestamp: 请求的时间戳,根据当前时间生成
userId: 此次请求使用平台端id为1的管理员账号进行操作
sign: 签名,使用该请求参数生成,生成流程在下面有说明
current : 请求接口的参数,查询分页为1的数据
size: 请求接口的参数,每页数据大小为10
以上就是一个get请求的全部数据了
sign(签名)的生成流程:
Section titled “sign(签名)的生成流程:”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"}- 通过 sha256 签名。curl 里的
sign换成你本地算出的值,不要把appSecret放到 URL 上。

在线加密地址:
java代码示例
Section titled “java代码示例”/*** 查询商品接口*/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"); }}验签失败如何识别
Section titled “验签失败如何识别”第三方必须看外层 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。
开放平台 OpenAPI 与出站回调
Section titled “开放平台 OpenAPI 与出站回调”签名与上文相同:请求头 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。
订单查询示例:
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 }}'订单 get
Section titled “订单 get”请求: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 待付尾款。
订单 page
Section titled “订单 page”请求:startTime、endTime(下单时间,毫秒,必填,跨度最大 7 天)、status(否)、pageNum(从 1)、pageSize(最大 50)。
响应为分页:list、total、pages。用于对账补漏,不要当实时同步。实时用回调。
支付单 get
Section titled “支付单 get”请求:payId 或 orderId 二选一。
响应:payId、orderIds、payAmount(分)、payStatus、bizPayNo、payType。
支付 payStatus:0 未支付,1 已支付,-1 退款,-2 失败。
库存 get / set
Section titled “库存 get / set”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。
积分 / 余额 / 成长值 get
Section titled “积分 / 余额 / 成长值 get”请求:userId 为本系统用户 ID,不是第三方账号。
响应:
| 接口 | 字段 |
|---|---|
| score/get | userId、score 当前积分 |
| balance/get | userId、actualBalance 当前可用余额(分) |
| growth/get | userId、growth 当前成长值 |
积分 / 余额 / 成长值 adjust
Section titled “积分 / 余额 / 成长值 adjust”| 字段 | 必填 | 说明 |
|---|---|---|
| userId | 是 | 本系统用户 ID |
| ioType | 是 | 1 加,0 扣 |
| score / amount / growth | 是 | 变动绝对值(正数)。积分 score,余额 amount(分),成长值 growth |
| outBizNo | 是 | 同一密钥下相同则幂等,返回首次结果,不再加减 |
| source | 否 | 流水来源 |
| remark | 否 | 备注 |
扣减不足则整笔失败、账不变。成功会写流水;密钥订阅了对应事件会推回调。禁止用调账模拟支付成功。
成长值调账示例(加 10):
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 为调账后的当前值。
出站回调(商城 → 第三方)
Section titled “出站回调(商城 → 第三方)”在系统密钥上配置公网 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 分钟。
事件与 payload
Section titled “事件与 payload”| 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请求或图片上传等请求,那么请求的数据不需要被包裹
接口报文规范
Section titled “接口报文规范”POST、PUT 请求格式说明
Section titled “POST、PUT 请求格式说明”请求头(Header)
Section titled “请求头(Header)”| 字段元素 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| 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
注册用户接口
Section titled “注册用户接口”data参数构成
Section titled “data参数构成”| 字段元素 | 类型 | 必填条件 | 说明 |
|---|---|---|---|
| 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请求的全部数据了
sign(签名)的生成流程:
Section titled “sign(签名)的生成流程:”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"}- 通过 sha256 签名。curl 里的
sign换成你本地算出的值。不要把 appSecret 放到 HTTP 报文里。

在线加密地址:
java代码示例
Section titled “java代码示例”/** * 注册用户接口 * @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以及过期时间同步到商城接口”data参数构成
Section titled “data参数构成”| 字段元素 | 类型 | 必填条件 | 说明 |
|---|---|---|---|
| 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(签名)的生成流程(与注册用户接口一样)”java代码示例
Section titled “java代码示例” /** * 将用户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 “修改用户接口(用于修改用户昵称)”data参数构成
Section titled “data参数构成”| 字段元素 | 类型 | 必填条件 | 说明 |
|---|---|---|---|
| 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(签名)的生成流程(与注册用户接口一样)”java代码示例
Section titled “java代码示例”/** * 更新用户接口 * @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"); } }禁用用户接口
Section titled “禁用用户接口”data参数构成
Section titled “data参数构成”| 字段元素 | 类型 | 必填条件 | 说明 |
|---|---|---|---|
| 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(签名)的生成流程(与注册用户接口一样)”java代码示例
Section titled “java代码示例”/** * 禁用用户接口 * @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"); } }调用用户端其他接口演示
Section titled “调用用户端其他接口演示”前提:已经注册用户(调用注册用户接口)、并且将token同步到系统中(调用将用户token以及过期时间同步到商城接口)
下面我将通过一个获取用户详情接口(无请求参数)演示
请求头token: 拿上面已经同步到系统的接口token_test
接口请求参数: 具体参数查看接口文档,封装好参数即可

java代码示例
Section titled “java代码示例”/** * 获取用户详情接口 * @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")); }输出结果

按下面做通即算对接完成:
- 用错误 appSecret 调任意
/open/v1:外层code为A00001,msg为「签名错误,请检查密钥与签名」。 - 用正确密钥调
order/get(商家或平台)或score/get(平台):外层code为00000,能验签响应。 - 订阅
order.status.changed,完成一笔支付:notifyUrl收到status=2,应答SUCCESS。 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,指定店铺商家密钥收不到。
- 接口与回调一览:mall4cloud第三方接口与回调清单
- 当前目录索引:
README.md