# 智慧零售商家开放平台API接入说明文档
| 版本号 | 修改时间 | 备注 |
|---|---|---|
| v1.0.0 | 2020/11/20 | 初始版本 |
| v1.1.0 | 2020/11/24 | 1.增加系统时间接口 2.敏感数据加解密约定 |
| v1.2.0 | 2020/11/26 | 增加售后API |
| v1.3.0 | 2020/12/02 | 1.增加API限流频次说明 2.订单API增加收货人邮编字段 3.增加运费字段及商品价格说明 |
| v1.3.1 | 2020/12/11 | 1.订单列表增加更新时间字段 2.增加预发布环境地址 3.售后单用户提交图片过期时间说明 4.请求参数中时间字段更改为LONG类型 |
| v1.3.2 | 2020/12/16 | 1.增加售后单商家审核拒绝原因码 2.售后单类型变更 3.API接口错误码说明 |
| v1.4.0 | 2021/01/18 | 1.一单多物流发货API(物流信息录入/修改/移除 5.3.2~5.3.4) 2.订单列表和增量查询接口返回字段新增用户催发货时间和多物流快递单列表字段 3.新增业务错误码说明 |
| v1.5.0 | 2021/02/03 | 1.商品库存增减接口 2.订单列表新增SKU条形码返回字段 3.订单列表增加买家购买商品实付金额字段 4. 售后单增加商家退款金额、平台补贴金额 |
| v1.5.1 | 2021/02/23 | 1.商品库存查询接口返回字段新增智慧零售skuId 2.商品库存更新接口入参统一输入智慧零售skuId 3.订单列表查询接口状态字段更新为非必填 |
| v1.6.0 | 2021/03/02 | 1.增加商品API 2.商品库存查询和修改接口协议调整 3.移除预发布环境接口地址 |
| v1.6.1 | 2021/03/10 | 1.订单和售后单列表支持按单号单个查询 |
| v1.7.0 | 2021/04/15 | 1.增加售后单全量列表（按创建时间查询）2.针对PHP客户端调用升级请求签名算法 3.增加PHP客户端请求和数据解密样例供参考 |
| v1.7.1 | 2021/04/22 | 1.增加订单详情、售后单详情接口 2.订单信息列表、订单增量查询接口增加物流关联sku信息 3.售后单列表、售后单全量列表接口增加售后商品关联物流单信息 |
| v1.7.2 | 2021/09/27 | 1.订单列表/增量/详情接口增加merchantRemark返回字段 2.API请求签名算法在PHP/C#环境兼容性说明 |
| v1.7.3 | 2021/10/13 | 1.API请求签名字段排序在C#环境的注意事项说明 2.删除废弃的发货和物流信息移除接口说明文档 |
| v1.7.4 | 2021/10/20 | 1.订单详情接口增加platformSubsidyAmount、merchantCouponAmount返回字段 |
| v1.7.5 | 2021/10/25 | 1.新增商品增加属性attrList字段 2.更新商品新增属性attrList字段 3.商品增删改增加version版本字段 |
| v1.7.6 | 2021/11/26 | 1.订单列表/订单增量查询增加platformSubsidyAmount、merchantCouponAmount返回字段 2.商家实收款定义修改：商家实收款=运费+sum(商品结算价)-sum(商家优惠金额) |
| v1.7.7 | 2021/12/14 | 1.订单列表/订单增量查询/订单详情增加riskFlag返回字段 |
| v1.7.8 | 2022/02/14 | 1.订单列表 & 订单增量查询 & 订单详情：增加商品级deliverStatus、deliverStatusName返回字段 |
| v1.7.9 | 2022/02/17 | 1.订单列表 & 订单增量查询 & 订单详情：增加订单级deliverStatus、deliverStatusName返回字段 |
| v1.7.10 | 2022/02/28 | 1.一单多物流-发货接口增加forceDeliver入参 |
| v1.7.11 | 2022/03/03 | 1.商品SKU增加吊牌价 |
| v1.7.12 | 2022/05/24 | 1.订单列表/订单增量查询/订单详情：增加优惠券信息和订单交易成功时间、不可售后时间返回字段 |
| v1.7.13 | 2022/05/09 | 1.新增商品增加分期支付installments字段 2.更新商品新增installments字段 |
| v1.7.14 | 2022/06/14 | 1.新增时效规则服务API |
| v1.7.15 | 2022/06/20 | 1.新增O2O配送轨迹接口API |
| v1.7.16 | 2022/06/21 | 1.新增商家优惠券列表、详情、保存草稿、提交、取消发放、停止发放接口 |
| v1.7.17 | 2022/07/27 | 1.新增订单分账金额，商家实收款逻辑调整 2.新增查询订单分账详情接口 |
| v1.7.18 | 2022/08/10 | 1.新增订单计费查询接口 |
| v1.7.19 | 2022/09/27 | 1.订单列表 & 订单增量查询 & 订单详情：增加支付类型、平台补贴信息、微信支付信息、分期支付信息 |
| v1.7.20 | 2022/10/20 | 1.新增电子面单API & 新增打印组件API |
| v1.7.21 | 2022/11/18 | 1.电子面单API-查询面单接口新增服务商相关字段 |
| v1.7.22 | 2022/11/21 | 1.售后单数据字典增加 payType、refundInfoList 返回字段 |
# 1. 概述
腾讯智慧零售入口小程序开放API用于和商家后端系统进行数据交换，目前主要有订单、物流、售后、商品、库存相关接口。该文档适用于商家或服务商系统基于HTTP协议接入。
# 2. 名词解释
- 开放API: 本文档特指腾讯智慧零售入口小程序后端开放接口，主要和商家进行数据交换
- appId: 开放API后台分配给商家的唯一标识，请妥善保管
- appSecret: 密钥，开放API后台分配给商家调用开放API计算签名时的密钥，请妥善保管
- dataKey: 数据解密密钥，开放API后台分配给商家用户解密约定的密文字段列表中的数据，请妥善保管，使用方法参考附录6.10部分
商家管理员登录腾讯荟聚商家管理平台从 [API身份信息] 菜单可获取以上3个参数内容
# 3. 调用流程
商家或服务商后端系统需按照开放API协议规范传递正确的请求参数，通过https请求到开放API即能获取到所需数据。主要流程包含：
- 填写参数
- 生成签名
- 拼装HTTPS请求
- 发起请求
- 得到响应结果
- 解析结果
# 4. 通用规范
# 4.1 协议
- 请求协议采用HTTPS传输数据
- 接口请求统一POST方法提交
- 接口调用方设置请求头Content-Type: application/json
- 所有的接口请求和响应数据统一采用UTF-8字符集编码
- 接口调用失败根据错误码采取适当的间隔重试策略，一般重试超过2次仍然失败建议调用方记录错误日志并告警。
# 4.2 调用地址
- 测试环境 https://qytest.sr.qq.com/openapi/v1
- 正式环境 https://qy.sr.qq.com/openapi/v1
# 4.3 调用方式
目前开放API支持的数据交换方式有以下2种:
- 轮询: 商家侧后端系统定时调用开放API从智慧零售侧拉取数据
- 回调: 商家侧后端系统主动调用开放API同步相关数据给智慧零售侧
# 4.4 公共参数
调用任何API都必须传入的参数，目前支持的公共参数有
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| requestId | STRING | 是 | 请求ID，每个请求唯一标识，可参考UUID随机字符串用法 |
| appId | STRING | 是 | 开放API后台分配给商家的appId |
| timestamp | STRING | 是 | 当前时间戳，精确到毫秒（13位数字） |
| nonceStr | STRING | 是 | 字符和数字混合的随机字符串，长度6位 |
| sign | STRING | 是 | API输入参数签名结果，签名算法参照下面介绍 |
# 4.5 业务参数
API调用除了上面必须包含的公共参数外，如果API本身有业务参数也须传入，每个API的业务参数参考下面API列表说明。公共参数和业务参数都放在请求体内用POST方式提交。
# 4.6 请求签名
为防止API在调用过程中被恶意者拦截随意篡改，调用API需要传入签名参数，开放API服务端根据请求参数对签名进行验证，判断请求参数是否合法，对于校验不通过的请求将拒绝处理，并返回鉴权失败错误。签名信息由接口请求参数和应用密钥（appSecret）根据下面的签名算法生成。
# 4.6.1 签名步骤
- 将<key, value>请求参数对(参数sign除外)按key的字典升序排序，得到有序的参数对列表N
- 将列表N中的参数对按key1=value1&key2=value2的方式拼接成字符串T，其中value部分需要urlencode编码
- 将appSecret实际值按括号内格式附加到字符串T后面（key1=value1&key2=value2&appSecret={密钥}）得到字符串S
- 对字符串S做MD5运算，将得到的MD5值转换成大写，得到接口请求签名
# 4.6.2 注意事项
- 不同接口请求的参数对不一样，计算签名按实际业务接口参数为准
- 参数名区分大小写，参数值为空不参与签名
- 参数对拼接过程中value部分需要urlencode
1.由于PHP和C#环境中的urlencode编码对某些字符计算的结果可能和JAVA环境不一致，主调方可去掉urlencode编码逻辑，同时增加请求头x-sr-sign-version:v2告知腾讯荟聚后台也去掉该编码逻辑。
2.C#环境中定义字典数据结构时，默认不区分大小写，会导致拼接字段的顺序和JAVA环境不一致从而影响最终签名结果，可加上StringComparer.Ordinal让系统排序时区分大小写：
SortedDictionary<string, string> dic = new SortedDictionary<string, string>(StringComparer.Ordinal); - appSecret只参与签名计算，不放入请求参数
# 4.6.3 JAVA版客户端调用示例
以下代码仅供生成请求签名参考，正式环境请调用方结合各自实际情况编码实现。
- 签名工具
/**
* 计算签名
*
* @param params Map
* 请求参数，包括公共和业务请求字段（不包括sign参数）
* @param appSecret String
* 开放平台分配的应用密钥,各调用方不同
*/
public static String genSignature(Map<String, Object> params, String appSecret)
throws UnsupportedEncodingException {
//参数key按自然升序
Map<String, Object> sortedParams = new TreeMap<>(Comparator.naturalOrder());
sortedParams.putAll(params);
//如果传递了sign参数则移除
sortedParams.entrySet()
.removeIf(entry -> CommonParam.sign.name().equals(entry.getKey()));
//appSecret参数不用传，以免泄漏
sortedParams.entrySet()
.removeIf(entry -> CommonParam.appSecret.name().equals(entry.getKey()));
//参数value为空的不参与签名
sortedParams.entrySet()
.removeIf(entry -> StringUtils.isEmpty(entry.getValue()));
//编码后的参数串
StringBuilder paramStr = new StringBuilder(256);
int index = 0;
for (Map.Entry<String, Object> entry : sortedParams.entrySet()) {
paramStr.append(entry.getKey())
.append("=")
.append(URLEncoder.encode(String.valueOf(entry.getValue()),
"UTF-8"));
if (index < sortedParams.size() - 1) {
paramStr.append("&");
}
index++;
}
//拼接密钥
paramStr.append("&")
.append(CommonParam.appSecret.name()).append("=")
.append(appSecret);
return Objects.requireNonNull(MD5Utils.digest(paramStr.toString()))
.toUpperCase();
}
- MD5Utils
public class MD5Utils {
/**
* 使用 MessageDigest 加密字符串
*
* @param source 需要加密的字符串
* @return 加密后字符串
*/
public static String digest(String source) {
try {
//首先生成一个 MessageDigest 类 , 确定计算方法
MessageDigest messageDigest = MessageDigest.getInstance("MD5");
// 添加要进行计算摘要的信息:通过使用 update 方法处理数据,使指定的byte数组更新摘要
messageDigest.update(source.getBytes(StandardCharsets.UTF_8));
//计算出摘要: ( 对于 MD5 是 16 位 ,SHA 是 20 位 )
byte[] digestByte = messageDigest.digest();
// 转十六进制字符串
return byte2hex(digestByte);
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
}
return null;
}
/**
* 二进制数组转十六进制字符串
*
* @param bytes 二进制数组
* @return 十六进制字符串
*/
public static String byte2hex(byte[] bytes) {
StringBuilder strBuilder = new StringBuilder();
String hexString;
for (byte aByte : bytes) {
int temp = 0XFF & aByte;
hexString = Integer.toHexString(temp);
if (hexString.length() == 1) {
strBuilder.append("0").append(hexString);
} else {
strBuilder.append(hexString);
}
}
return strBuilder.toString();
}
}
# 4.7 响应格式
| 参数名 | 参数类型 | 参数说明 |
|---|---|---|
| code | INTEGER | 响应码，参考附录《错误码说明》 |
| message | STRING | 响应提示 |
| data | OBJECT | 响应数据集 |
# 5. 通用API列表
# 5.1 工具API
# 5.1.1 获取智慧零售系统时间
- 接口名
/time
- 使用场景
- 商家侧获取智慧零售后台系统时间，便于调用订单列表等接口时校准时间窗口
商家限流qps: 30
请求参数
无
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx", //string 请求ID
"timestamp": 0 //long 毫秒时间戳
}
}
# 5.2 订单API
# 5.2.1 订单数据字典
| 字段名 | 字段类型 | 字段说明 |
|---|---|---|
| orderId | STRING | 智慧零售侧订单ID |
| orderType | STRING | 订单类型（SINGLE-普通订单; O2O-O2O订单） |
| orderStatus | STRING | 订单状态，参考附录 《订单状态列表》 |
| orderStatusName | STRING | 订单状态描述 |
| totalItemQuantity | INTEGER | 订单商品总数量（订单所有商品购买数量总和） |
| totalOriginalPrice | INTEGER | 订单商品总价（订单所有商品总价总和，即总原价），单位：分 |
| discountFee | INTEGER | 订单优惠金额（订单所有商品优惠金额总和），单位：分 |
| payFee | INTEGER | 订单买家实付款（订单所有商品买家实付款总和+订单运费），单位：分 |
| deliverFee | INTEGER | 运费，单位：分 |
| platformSubsidyAmount | INTEGER | 订单平台补贴（订单所有商品平台补贴金额总和），单位：分 |
| settlementFee | INTEGER | 订单商家实收款（订单商家实收款 = 订单买家实付款+订单平台补贴-分账金额），单位：分 |
| totalSharingBillAmount | INTEGER | 订单预估分账金额（估计值仅供参考和展示，实际结算以计费单为准，异步计算，初次查询到订单可能为空，建议利用增量订单做更新） |
| orderTime | LONG | 下单时间，毫秒时间戳 |
| updateTime | LONG | 订单更新时间 |
| payTime | LONG | 支付时间，毫秒时间戳 |
| deliverList | LIST | 多物流快递单号列表 |
| deliverTime | LONG | 发货时间，毫秒时间戳 |
| deliverCompany | STRING | 快递公司编码 |
| deliverCompanyName | STRING | 快递公司名称 |
| deliverNumber | STRING | 快递单号 |
| urgeDeliverTime | LONG | 用户催发货时间 |
| userName | STRING | 收货人姓名 |
| telNumber | STRING | 收货手机号 |
| nationalCode | STRING | 国家码 |
| provinceName | STRING | 省 |
| cityName | STRING | 市 |
| countyName | STRING | 区 |
| detailInfo | STRING | 详细地址 |
| postalCode | STRING | 邮编 |
| remark | STRING | 订单备注 |
| merchantId | STRING | 商家ID （智慧零售侧定义） |
| merchantName | STRING | 商家名称 |
| merchantRemark | STRING | 商家备注 |
| deliverStatus | INTEGER | 订单级发货状态：0-未发货 1-全部发货 3-部分发货 |
| riskFlag | INTEGER | 疑似风险订单标识：0-默认 1-疑似风险订单 |
| itemList | List | 订单商品信息 |
| - orderItemId | STRING | 订单商品行ID |
| - quantity | INTEGER | 商品购买数量 |
| - outerSkuId | STRING | 商家SKU ID |
| - skuId | STRING | 智慧零售侧SKU ID |
| - skuVersion | STRING | 智慧零售侧SKU版本 |
| - skuImg | STRING | 商品图片 |
| - skuSpec | STRING | 商品规格 |
| - spuId | STRING | 智慧零售侧SPU ID |
| - spuName | STRING | 商品名称 |
| - spuVersion | STRING | 智慧零售侧SPU版本 |
| - barCode | STRING | sku条形码 |
| - originalPrice | INTEGER | 商品单价（商品不参与任何活动时的单件商品原价，即商品单买价），单位：分 |
| - settlementPrice | INTEGER | 单件结算价（智慧零售与商家约定的结算价格），单位：分 |
| - payPrice | INTEGER | 单件买家实付款（当前商品单件买家最终支付的金额），单位：分 |
| - totalOriginalPrice | INTEGER | 商品总价（商品总价=单件原价x购买数量），单位：分 |
| - discountAmount | INTEGER | 商品优惠金额（包含所有活动优惠及优惠券抵扣），单位：分 |
| - totalPayAmount | INTEGER | 买家实付款（当前商品买家实付总金额=单件买家实付款x购买数量），单位：分 |
| - platformSubsidyAmount | INTEGER | 平台补贴金额，单位：分 |
| - merchantCouponAmount | INTEGER | 商家优惠金额（优惠金额中商家承担部分），单位：分 |
| - settlementFee | INTEGER | 商家实收款（商家实收款=买家实付款+平台补贴金额-分账金额），单位：分 |
| - sharingBillAmount | INTEGER | 商品预估分账金额（估计值仅供参考和展示，实际结算以计费单为准，异步计算，初次查询到订单可能为空，建议利用增量订单做更新） |
| - deliverStatus | INTEGER | 商品级发货状态：0-未发货 1-已发货 |
| - couponList | List | 商品对应优惠信息明细 |
| -- stockId | STRING | 商品优惠券批次ID |
| -- outerStockId | STRING | 商品外部优惠券批次ID（外发内核券特有字段，若无返回，可重新拉取） |
| -- couponType | INTEGER | 商品优惠券类型：1-满减券 2-外发内核满减券 4-店铺满减券 6-渠道满减券 |
| -- couponAmount | INTEGER | 商品优惠券金额，单位：分 |
| confirmTime | LONG | 交易成功时间，毫秒时间戳 |
| aftersaleExpireTime | LONG | 不可售后时间，毫秒时间戳 |
| payType | INTEGER | 支付类型：0-微信支付 10-分期支付 |
| wxPayInfoList | List | 微信支付信息（payType = 0时返回） |
| - transactionId | STRING | 微信支付订单号 |
| - payTime | LONG | 支付时间 |
| - payFee | INTEGER | 支付金额，单位：分 |
| subsidyInfoList | List | 平台补贴信息 |
| - transactionId | STRING | 补贴支付订单号 |
| - subsidyId | STRING | 补贴支付业务单号 |
| - payTime | LONG | 补贴支付时间 |
| - payFee | INTEGER | 补贴金额，单位：分 |
| installmentInfoList | List | 分期信息（payType = 10时返回） |
| - installmentPayId | STRING | 分期支付订单号 |
| - payTime | LONG | 支付时间 |
| - bankName | STRING | 机构名称 |
| - installmentNum | INTEGER | 分期期数 |
| - totalPayAmount | INTEGER | 总还款金额，单位：分 |
| - totalInterest | INTEGER | 分期利息，单位：分 |
| - payerInterest | INTEGER | 买家承担利息，单位：分 |
| - merchantInterest | INTEGER | 商家承担利息，单位：分 |
| - platformInterest | INTEGER | 平台补贴金额，平台针对商家承担利息部分补贴的金额，商家实际承担利息=商家承担利息-平台补贴，单位分 |
- 商家实收款(settlementFee)：当前订单下，订单运费+(商品A settlementFee + 商品B settlementFee)
# 5.2.2 订单信息列表
- 接口名
/order/list
- 使用场景
- 商家侧可根据订单创建时间初始化全量订单，同步完后可用5.2.3增量接口查询有变更订单
- 只能获取到成交时间3个月以内的数据
调用方式: 轮询
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | LONG | 否 | 订单ID，若传值则精确查询当前订单信息 |
| startCreateTime | LONG | 是 | 成交开始时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 PS：开始时间结束时间间距不超过 24 小时 |
| endCreateTime | LONG | 是 | 成交结束时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 |
| orderStatus | STRING | 否 | 订单状态，如不填写默认查询附录订单状态列表所有枚举对应订单数据 |
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "xxx", //请求ID
"totalCount":1,//当前查询条件下的订单列表总数
"orderList":[
{
"orderId":"1",
"orderType": "SINGLE",
"orderStatus":"xxx",
"orderStatusName": "待付款",
"payFee":100,
"deliverFee":50,
"totalSharingBillAmount":100,
"orderTime":0,
"updateTime":0,
"payTime":0,
"deliverTime":0, //支持多物流功能后，此处字段废弃
"deliverCompany":"xxx", //支持多物流功能后，此处字段废弃
"deliverNumber":"xxx",//支持多物流功能后，此处字段废弃
"userName":"张小萌",
"telNumber": "xxx",
"nationalCode": "国家码",
"provinceName": "省",
"cityName": "市",
"countyName": "区",
"detailInfo": "详细地址",
"postalCode": "xxx",
"remark": "订单备注",
"merchantRemark": "商家备注",
"deliverStatus":0,
"deliverStatusName":"未发货",
"itemList":[
{
"quantity":1,
"outerSkuId": "xxx",
"skuId":"xxxx",
"skuVersion":"xxx",
"skuImg":"1",
"skuSpec":"1",
"spuId": "xxx",
"spuName":"1",
"spuVersion":"xxx",
"barCode": "SKU条形码",
"originalPrice":100,
"salePrice": 100,
"settlementPrice": 100,
"payPrice": 100,
"totalPayAmount": 100,
"platformSubsidyAmount": 100,
"merchantCouponAmount": 100,
"sharingBillAmount":100,
"deliverStatus":0,
"deliverStatusName":"未发货",
"couponList":[
{
"stockId":"123456789",
"outerStockId":"123456789",
"couponId":"123456",
"couponType":1,
"couponAmount":900
}
]
}
],
"urgeDeliverTime":0,
"deliverList": [
{
"deliverCompany": "快递公司编码密文,datakey解密",
"deliverCompanyName": "快递公司密文,datakey解密",
"deliverNumber": "快递单号密文,datakey解密",
"deliverTime": 0,
"deliverItems":[
{
"skuId":"xxxxxx",
"qty":1
}
]
}
],
"settlementFee": 100,
"riskFlag":0,
"confirmTime":0,
"aftersaleExpireTime":0,
"payType": 10,
"subsidyInfoList": [
{
"transactionId":"xxxxxxx",
"subsidyId":"xxxxxxxx",
"payTime":1652065107000,
"payFee":10000
}
],
"installmentInfoList": [
{
"installmentPayId": "xxxxxxxxxxxxxxx",
"payTime": 1652065107000,
"bankName": "广发银行",
"installmentNum": 3,
"totalPayAmount": 31000,
"totalInterest": 930,
"payerInterest": 0,
"merchantInterest": 930,
"platformInterest": 0
}
]
}
]
}
}
# 5.2.3 订单增量查询
- 接口名
/order/list/increment
- 使用场景
- 商家侧增量查询有状态变更的订单列表，只能获取到成交时间3个月以内的数据
- 一次请求只能查询时间跨度为30分钟内的增量订单数据，即endUpdateTime - startUpdateTime <= 30min
- 通过从后往前翻页的方式以及结束时间不小于智慧零售侧系统前5min(300秒)，避免漏单，比如endUpdateTime=System.currentTimeMillis/1000+300；startUpdateTime=System.currentTimeMillis/1000+300-1800
调用方式: 轮询
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | LONG | 否 | 订单ID，若传值则精确查询当前订单信息 |
| startUpdateTime | LONG | 是 | 最后更新时间 开始时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 |
| endUpdateTime | LONG | 是 | 最后更新时间 结束时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 PS：开始时间结束时间间距不超过30分钟 |
| orderStatus | STRING | 否 | 订单状态，如不填写默认查询附录订单状态列表所有枚举对应订单数据 |
| pageNum | INTEGER | 是 | 返回页码，默认1，页码从1开始 PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值；注：必须采用倒序的分页方式（从最后一页往回取）以避免漏单问题。 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "xxx",
"totalCount":1,//当前查询条件下的订单列表总数
"orderList":[
{
"orderId":"1",
"orderType": "SINGLE",
"orderStatus":"xxx",
"orderStatusName": "待付款",
"payFee":100,
"deliverFee":50,
"orderTime":0,
"updateTime":0,
"payTime":0,
"deliverTime":0, //支持多物流功能后，此处字段废弃
"deliverCompany":"xxx", //支持多物流功能后，此处字段废弃
"deliverNumber":"xxx", //支持多物流功能后，此处字段废弃
"userName":"张小萌",
"telNumber": "xxx",
"nationalCode": "国家码",
"provinceName": "省",
"cityName": "市",
"countyName": "区",
"detailInfo": "详细地址",
"postalCode": "xxx",
"remark": "订单备注",
"merchantRemark": "商家备注",
"deliverStatus":0,
"deliverStatusName":"未发货",
"itemList":[
{
"quantity":1,
"outerSkuId": "xxx",
"skuId":"xxxx",
"skuVersion":"xxx",
"skuImg":"1",
"skuSpec":"1",
"spuId": "xxx",
"spuName":"1",
"spuVersion":"xxx",
"barCode": "SKU条形码",
"originalPrice":100,
"salePrice": 100,
"settlementPrice": 100,
"payPrice": 100,
"totalPayAmount": 100,
"platformSubsidyAmount": 100,
"merchantCouponAmount": 100,
"sharingBillAmount":100,
"deliverStatus":0,
"deliverStatusName":"未发货",
"couponList":[
{
"stockId":"123456789",
"outerStockId":"123456789",
"couponId":"123456",
"couponType":1,
"couponAmount":900
}
]
}
],
"urgeDeliverTime":0,
"deliverList": [
{
"deliverCompany": "快递公司编码密文,datakey解密",
"deliverCompanyName": "快递公司密文,datakey解密",
"deliverNumber": "快递单号密文,datakey解密",
"deliverTime": 0,
"deliverItems":[
{
"skuId":"xxxxxx",
"qty":1
}
]
}
],
"settlementFee": 100,
"riskFlag":0,
"confirmTime":0,
"aftersaleExpireTime":0,
"totalSharingBillAmount":100,
"payType": 0,
"subsidyInfoList": [
{
"transactionId":"xxxxxxx",
"subsidyId":"xxxxxxxx",
"payTime":1652065107000,
"payFee":10000
}
],
"wxPayInfoList": [
{
"transactionId":"xxxxxxx",
"payTime":1652065107000,
"payFee":10000
}
]
}
]
}
}
# 5.2.4 订单详情
- 接口名
/order/detail
- 使用场景
- 商家侧查询单个订单详情，没有订单时间限制
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | LONG | 是 | 订单ID |
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "xxx",
"detail": {
"orderId":"1",
"orderType": "SINGLE",
"orderStatus":"xxx",
"orderStatusName": "待付款",
"payFee":100,
"deliverFee":50,
"totalSharingBillAmount":100,
"orderTime":0,
"updateTime":0,
"payTime":0,
"deliverTime":0, //支持多物流功能后，此处字段废弃
"deliverCompany":"xxx", //支持多物流功能后，此处字段废弃
"deliverNumber":"xxx", //支持多物流功能后，此处字段废弃
"userName":"张小萌",
"telNumber": "xxx",
"nationalCode": "国家码",
"provinceName": "省",
"cityName": "市",
"countyName": "区",
"detailInfo": "详细地址",
"postalCode": "xxx",
"remark": "订单备注",
"merchantRemark": "商家备注",
"deliverStatus":0,
"deliverStatusName":"未发货",
"itemList":[
{
"quantity":1,
"outerSkuId": "xxx",
"skuId":"xxxx",
"skuVersion":"xxx",
"skuImg":"1",
"skuSpec":"1",
"spuId": "xxx",
"spuName":"1",
"spuVersion":"xxx",
"barCode": "SKU条形码",
"originalPrice":100,
"salePrice": 100,
"settlementPrice": 100,
"payPrice": 100,
"totalPayAmount": 100,
"platformSubsidyAmount": 100,
"merchantCouponAmount": 100,
"sharingBillAmount":100,
"deliverStatus":0,
"deliverStatusName":"未发货",
"couponList":[
{
"stockId":"123456789",
"outerStockId":"123456789",
"couponId":"123456",
"couponType":1,
"couponAmount":900
}
]
}
],
"urgeDeliverTime":0,
"deliverList": [
{
"deliverCompany": "快递公司编码密文,datakey解密",
"deliverCompanyName": "快递公司密文,datakey解密",
"deliverNumber": "快递单号密文,datakey解密",
"deliverTime": 0,
"deliverItems":[
{
"skuId":"xxxxxx",
"qty":1
}
]
}
],
"settlementFee": 100,
"riskFlag":0,
"confirmTime":0,
"aftersaleExpireTime":0,
"payType": 10,
"subsidyInfoList": [
{
"transactionId":"xxxxxxx",
"subsidyId":"xxxxxxxx",
"payTime":1652065107000,
"payFee":10000
}
],
"installmentInfoList": [
{
"installmentPayId": "xxxxxxxxxxxxxxx",
"payTime": 1652065107000,
"bankName": "广发银行",
"installmentNum": 3,
"totalPayAmount": 31000,
"totalInterest": 930,
"payerInterest": 0,
"merchantInterest": 930,
"platformInterest": 0
}
]
}
}
}
# 5.2.5 订单分账详情
- 接口名
/order/profitSharingInfo
- 使用场景
- 商家侧查询单个订单的分账信息
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | LONG | 是 | 订单ID |
| skuId | STRING | 否 | skuID |
- 响应结果
{
"code":0,
"message":"success",
"data": {
"orderId":424338972095511169,
"profitSharingAmount":10, //订单分账总金额 单位:分
"profitSharingReturnAmount":0, //订单分账回退总金额 单位:分
"billVOList": [
{
"billDetailId":"36000401412022070544009359189", //支付机构分账流水单号
"billType":"CPS", //CPS - CPS佣金 INTERESTS-分期手续费
"billChannel":"WX", //分账渠道 WX-微信支付 ZJ-中金支付
"billSharingAmount":10, //分账单分账金额 单位:分
"billSharingReturnAmount":0, //分账单分账回退金额 单位:分
"skuVOList":[
{
"skuId":"k95364869125",
"outSkuId":"k95364869125",
"skuSharingAmount":20, //分账单下sku分账金额 单位:分
"skuSharingReturnAmount":0 //分账单下sku分账回退金额 单位:分
}
]
}
]
}
}
# 5.2.6 订单计费查询
- 接口名
/order/feeDetail
- 使用场景
- 商家侧查询单个订单平台所需收取的费用，以订单支付和售后退款维度进行基准计算，并最终分账收费（平台实收）是两者轧差金额。
- 可查询到订单号商品行计费参数。
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | LONG | 是 | 订单ID |
- 响应结果
{
"code":0,
"message":"success",
"data":{
"orderId":424339839678904632,
"orderFeeList":[ //订单计费科目列表
{
"feeType":1, //订单计费科目类型(1=CPS佣金 2=分期手续费)
"costOrderFee":3500, //订单对应的计费金额，单位：分
"orderSkuList":[ //多个商品行的计费信息
{
"outerSkuId":"o1261791213850", //商家SKU ID
"skuId":"k1261791213850", //智慧零售侧SKU ID
"costOrderSkuFee":3500 //该商品行对应的计费金额，单位：分
}
]
},
{
"feeType":2,
"costOrderFee":700,
"orderSkuList":[
{
"outerSkuId":"o1261791213850",
"skuId":"k1261791213850",
"costOrderSkuFee":700
}
]
}
],
"refundFeeList":[ //订单对应售后订单列表
{
"feeType":1, //订单计费科目类型(1=CPS佣金 2=分期手续费)
"afterSaleOrderId":478298381402125290, //智慧零售侧售后单号
"costOrderSkuFee":3500, //售后订单对应退回的计费金额，单位：分
"refundSkuList":[ //多个商品行的售后退回计费信息
{
"outerSkuId":"o1261791213850", //商家SKU ID
"skuId":"k1261791213850", //智慧零售侧SKU ID
"costRefundSkuFee":3500 //商品行对应的售后退回计费金额，单位：分
}
]
},
{
"feeType":2,
"afterSaleOrderId":478298381402125290,
"costOrderSkuFee":700,
"refundSkuList":[
{
"outerSkuId":"o1261791213850",
"skuId":"k1261791213850",
"costRefundSkuFee":700
}
]
}
]
}
}
# 5.3 售后API
# 5.3.1 售后单数据字典
| 字段名 | 字段类型 | 字段说明 |
|---|---|---|
| afterSaleOrderId | STRING | 智慧零售侧售后单号 |
| orderId | STRING | 智慧零售侧订单号 |
| afterSaleType | STRING | 售后类型 参考附录6.2 |
| status | STRING | 售后状态 参考附录6.3和6.4 |
| statusName | STRING | 售后状态描述 |
| deliverFee | INTEGER | 运费 单位:分 |
| refundFee | INTEGER | 退款金额 单位:分 |
| createTime | STRING | 售后单申请时间 毫秒时间戳 |
| updateTime | STRING | 售后单更新时间 毫秒时间戳 |
| itemList | List | 售后商品列表 |
| - spuName | STRING | 商品名称 |
| - outerSkuId | STRING | 商家SKU ID |
| - skuSpec | STRING | 商品规格 |
| - skuImg | STRING | 商品图片 |
| - totalPayAmount | INTEGER | 买家实付金额 单位:分 |
| - orderItemId | STRING | 订单商品行ID |
| - quantity | INTEGER | 数量 |
| - price | INTEGER | 价格 单位: 分 |
| refundReason | STRING | 退款原因 |
| extraReason | STRING | 补充描述 |
| imgCertificate | List(STRING) | 图片描述 |
| auditResult | INTEGER | 售后单审核结果 0-未审核 1-拒绝 2-同意 |
| auditTime | LONG | 售后单审核时间 毫秒时间戳 |
| merchantRefundFee | INTEGER | 商家退款金额 单位:分 |
| subsidyReturnFee | INTEGER | 补贴退款金额 单位:分 |
| refuseReason | STRING | 售后单审核拒绝原因 |
| refundAuditResult | INTEGER | 退款审核结果(退货退款单) 0-未审核 1-拒绝 2-同意 |
| refundAuditTime | LONG | 退款单审核时间(退货退款单) 毫秒时间戳 |
| refundRefuseReason | STRING | 退款审核拒绝原因(退货退款单) |
| returnName | STRING | 商家侧收货人姓名（退货退款单） |
| returnMobile | STRING | 商家侧收货人手机（退货退款单） |
| returnAddress | STRING | 商家侧收货人地址（退货退款单） |
| deliverCompany | STRING | 物流公司（退货退款单） |
| deliverNumber | STRING | 物流单号（退货退款单） |
| deliverTime | LONG | 退货时间（退货退款单）毫秒时间戳 |
| payType | INTEGER | 支付方式：0-微信支付 10-分期支付 |
| refundInfoList | List | 退款信息 |
| - refundId | STRING | 支付退款单号 |
| - refundBusinessId | STRING | 支付退款业务单号 |
| - userReceivedAccount | STRING | 退款入账账户 |
| - refundFee | INTEGER | 退款金额/荟聚豆退豆数量，单位：分（金额）/个（荟聚豆） |
| - refundTime | LONG | 退款时间 |
| - remark | STRING | 备注 |
imgCertificate字段是用户提交售后的辅助图片链接，目前设置的有效期为7天，商家侧可结合实际情况在有效期内处理图片。
# 5.3.2 售后单列表
- 接口名
/aftersale/list/increment
- 使用场景
- 用户在智慧零售侧发起售后申请生成售后单后，商家侧调用该接口获取售后单数据, 起始时间窗口不超过30min
调用方式: 轮询
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | LONG | 否 | 售后单ID，若传值则精确查询当前售后单信息 |
| startUpdateTime | LONG | 是 | 最后更新时间 开始时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 |
| endUpdateTime | LONG | 是 | 最后更新时间 结束时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 PS: 开始时间结束时间间距不超过 30 分钟 |
| afterSaleType | STRING | 否 | 售后单类型，参考附录6.2 |
| status | STRING | 否 | 售后单状态，参考附录6.3和6.4 |
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 响应结果
{
"code":0,
"message":"success",
"data":{
"requestId":"4eae8828-9bed-42e3-b7a1-eccca5ff2777",
"totalCount": 1,
"list":[
{
"afterSaleOrderId":"27390114548351568",
"orderId":27390114548351024,
"afterSaleType":"AFTER_SALE_RETURN",
"refundReason":"快递/物流一直未送到",
"deliverFee":0,
"refundFee":1,
"extraReason":"",
"imgCertificate":["url1","url2"],
"status":"AUDIT_FAIL",
"statusName":"拒绝退款，待与买家协商",
"auditResult":1,
"refuseReason":"不能退款",
"auditTime":0,
"returnName":"",
"returnMobile":"",
"returnAddress":"",
"deliverCompany":"",
"deliverNumber":"",
"deliverTime":0,
"refundAuditResult":0,
"refundAuditTime":0,
"refundRefuseReason":"",
"refundNo":"xxx",
"createTime":0,
"updateTime":0,
"itemList":[
{
"spuName":"Apple/苹果 iPhone 12",
"outerSkuId":"iphonesku001",
"quantity":1,
"price":1,
"skuSpec":"xxx",
"skuImg":"https://xxx.jpg",
"totalPayAmount": 3,
"deliverInfo":[
{
"deliverCompany":"shunfeng",
"deliverCompanyName":"顺丰快运",
"deliverNumber":"xxxxxx"
}
]
}
],
"merchantRefundFee": 6,
"subsidyReturnFee": 3
}
]
}
}
# 5.3.3 售后单审核
- 接口名
/aftersale/audit
- 使用场景
- 商家审核(同意或者拒绝)用户售后申请单(退款单、退货退款单)
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | STRING | 是 | 售后单号 |
| auditResult | INTEGER | 是 | 审核结果 1-拒绝 2-同意 |
| returnName | STRING | 是 | 收货人姓名（退货退款单审核同意时填写） |
| returnMobile | STRING | 是 | 收货人手机（退货退款单审核同意时填写） |
| returnAddress | STRING | 是 | 退货地址 （退货退款单审核同意时填写） |
| refuseReason | STRING | 是 | 拒绝原因码，参考附录6.5和6.6 |
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx" //string 请求ID
}
}
# 5.3.4 审核退款（退货退款单）
- 接口名
/aftersale/refund/audit
- 使用场景
- 商家收到用户退货后调用该接口确认退款
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | STRING | 是 | 售后单号 |
| refundAuditResult | INTEGER | 是 | 审核结果 1-拒绝 2-同意 |
| refundRefuseReason | STRING | 是 | 拒绝原因码，参考附录6.7 |
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx" //string 请求ID
}
}
# 5.3.5 重新发起退款
- 接口名
/aftersale/refund/again
- 使用场景
- 可能因为商家账户余额不足导致退款失败后，商家侧需重新发起退款
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | STRING | 是 | 售后单号 |
| refundNo | STRING | 是 | 退款单号 |
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx" //string 请求ID
}
}
# 5.3.6 售后单全量列表
- 接口名
/aftersale/list
- 使用场景
- 用户在智慧零售侧发起售后申请生成售后单后，商家侧可调用该接口一次性初始化完所有售后单，之后用增量查询接口5.4.2轮询更新
调用方式: 轮询
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | LONG | 否 | 售后单ID，若传值则精确查询当前售后单信息 |
| startCreateTime | LONG | 是 | 创建时间 开始时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 |
| endCreateTime | LONG | 是 | 创建时间 结束时间戳，指格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒) 起至现在的总秒数 PS: 开始时间结束时间间距不超过24小时 |
| afterSaleType | STRING | 否 | 售后单类型，参考附录6.2 |
| status | STRING | 否 | 售后单状态，参考附录6.3和6.4 |
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 响应结果
{
"code":0,
"message":"success",
"data":{
"requestId":"4eae8828-9bed-42e3-b7a1-eccca5ff2777",
"totalCount": 1,
"list":[
{
"afterSaleOrderId":"27390114548351568",
"orderId":27390114548351024,
"afterSaleType":"AFTER_SALE_RETURN",
"refundReason":"快递/物流一直未送到",
"deliverFee":0,
"refundFee":1,
"extraReason":"",
"imgCertificate":["url1","url2"],
"status":"AUDIT_FAIL",
"statusName":"拒绝退款，待与买家协商",
"auditResult":1,
"refuseReason":"不能退款",
"auditTime":0,
"returnName":"",
"returnMobile":"",
"returnAddress":"",
"deliverCompany":"",
"deliverNumber":"",
"deliverTime":0,
"refundAuditResult":0,
"refundAuditTime":0,
"refundRefuseReason":"",
"refundNo":"xxx",
"createTime":0,
"updateTime":0,
"itemList":[
{
"spuName":"Apple/苹果 iPhone 12",
"outerSkuId":"iphonesku001",
"quantity":1,
"price":1,
"skuSpec":"xxx",
"skuImg":"https://xxx.jpg",
"totalPayAmount": 3,
"deliverInfo":[
{
"deliverCompany":"shunfeng",
"deliverCompanyName":"顺丰快运",
"deliverNumber":"xxxxxx"
}
]
}
],
"merchantRefundFee": 6,
"subsidyReturnFee": 3
}
]
}
}
# 5.3.7 售后单详情
- 接口名
/aftersale/detail
- 使用场景
- 商家侧查询单个售后单详情，没有申请时间限制
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| afterSaleOrderId | LONG | 否 | 售后单ID |
- 响应结果
{
"code":0,
"message":"success",
"data":{
"requestId":"4eae8828-9bed-42e3-b7a1-eccca5ff2777",
"detail":
{
"afterSaleOrderId":"27390114548351568",
"orderId":27390114548351024,
"afterSaleType":"AFTER_SALE_RETURN",
"refundReason":"快递/物流一直未送到",
"deliverFee":0,
"refundFee":1,
"extraReason":"",
"imgCertificate":["url1","url2"],
"status":"AUDIT_FAIL",
"statusName":"拒绝退款，待与买家协商",
"auditResult":1,
"refuseReason":"不能退款",
"auditTime":0,
"returnName":"",
"returnMobile":"",
"returnAddress":"",
"deliverCompany":"",
"deliverNumber":"",
"deliverTime":0,
"refundAuditResult":0,
"refundAuditTime":0,
"refundRefuseReason":"",
"refundNo":"xxx",
"createTime":0,
"updateTime":0,
"itemList":[
{
"spuName":"Apple/苹果 iPhone 12",
"outerSkuId":"iphonesku001",
"quantity":1,
"price":1,
"skuSpec":"xxx",
"skuImg":"https://xxx.jpg",
"totalPayAmount": 3,
"deliverInfo":[
{
"deliverCompany":"shunfeng",
"deliverCompanyName":"顺丰快运",
"deliverNumber":"xxxxxx"
}
]
}
],
"merchantRefundFee": 6,
"subsidyReturnFee": 3
}
}
}
# 5.4 兑换码API
# 5.4.1 兑换码列表
- 接口名
/teller/cdkey/list
- 使用场景
- 商家侧可根据批次号分页查询兑换码列表
调用方式: 轮询
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| cdkeySeqNum | STRING | 是 | 兑换码批次号 |
| pageNum | INTEGER | 是 | 页码，最小值为 1 |
| pageSize | INTEGER | 是 | 每页查询数量，取值范围：[1, 200] |
- 业务请求参数示例
{
"cdkeySeqNum": "314582268255949049",
"pageNum": 1,
"pageSize": 100
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据，code 为 0 时该属性有值 |
| - requestId | STRING | 回传本次请求的 requestId |
| - totalPages | INTEGER | 当前查询条件下，总页数 |
| - totalCount | LONG | 当前查询条件下，总记录数 |
| - cdkeyList | ARRAY | 当前查询条件下，兑换码列表 |
| -- redeemCode | STRING | 兑换码密文 Base64 编码值。 需 Base64 decode 后，再使用 dataKey 解密。 解密示例：AESUtils.decrypt(Base64.getDecoder().decode(redeemCode), dataKey); |
| -- redeemStatus | INTEGER | 兑换状态：10-未兑换，11-兑换中，20-已兑换，30-已作废 |
| -- startValidTime | LONG | 兑换码有效期起始时间，13 位时间戳(豪秒级) |
| -- endValidTime | LONG | 兑换码有效期结束时间，13 位时间戳(豪秒级) |
| -- redeemTime | LONG | 兑换时间，兑换成功时返回该属性，13 位时间戳(豪秒级) |
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "5b0d2bc9-3d96-4ea7-8815-ab6456bb9526",
"totalPages": 11,
"totalCount": 21,
"cdkeyList": [
{
"redeemCode": "bB7MOh6DYaIDCT6SUYG+ViYf/cUj2S/C/ohNXHF/6rKXbLXMQJhmNY2RYPak4Y3E",
"redeemStatus": 10,
"startValidTime": 1641955552148,
"endValidTime": 1644547552148
},
{
"redeemCode": "cDMrkcOF+rclXBum7ldEKp+UqwczH0TwGQ0iyqsrSATZWgSLWGNL575MGcZbKDB5",
"redeemStatus": 20,
"startValidTime": 1641955552148,
"endValidTime": 1644547552148,
"redeemTime": 1641955560148
}
]
}
}
# 5.5 优惠券API
# 5.5.1 属性描述
| 属性名称 | 属性类型 | 属性描述 |
|---|---|---|
| stockId | LONG | 优惠券批次 ID |
| stockName | STRING | 优惠券批次名称 |
| status | INTEGER | 优惠券批次状态，枚举值见下方 |
| couponType | INTEGER | 优惠券类型：4-腾讯荟聚商家券 |
| threshold | INTEGER | 优惠使用门槛金额，单位：分。如：满 10 元减 5 元，threshold=1000。 |
| moneyOf | INTEGER | 优惠券面额，单位：分。如：满 10 元减 5 元，moneyOf=500。 电商商家：threshold - moneyOf => 1。 O2O商家：threshold - moneyOf => 50。 |
| maxCoupons | INTEGER | 发放数量，1-20,000,000 |
| maxCouponsPerUser | INTEGER | 每人可领数量，1 <= maxCouponsPerUser <= maxCoupons |
| dailyMaxCouponsPerUser | INTEGER | 每人每天可领数量，1 <= dailyMaxCouponsPerUser <= maxCouponsPerUser |
| availableBeginTime | DATETIME | 领券的开始时间，格式：2022-06-20 00:00:00 |
| availableEndTime | DATETIME | 领券的结束时间，格式：2023-06-15 23:59:59 |
| availableUseType | INTEGER | 用券时间类型： 0-固定时间，availableUseBeginTime 至 availableUseEndTime。 1-领券当日起 availableUsePeriod 天可用。 3-领券当日起 availableUseBeginPeriod 天后开始可用，availableUsePeriod 天后结束可用。 示例见下方枚举值 |
| availableUseBeginTime | DATETIME | 用券开始时间，用券开始时间>=领券开始时间，格式：2022-06-20 00:00:00 availableUseType=0 时，必传。 |
| availableUseEndTime | DATETIME | 用券结束时间，用券结束时间>=领券结束时间，格式：2023-06-15 23:59:59 availableUseType=0 时，必传 |
| availableUsePeriod | INTEGER | availableUseType=1 或 3，必传，单位：天 |
| availableUseBeginPeriod | INTEGER | availableUseType=3，必传，单位：天 |
| scopeType | INTEGER | 适用范围类型，31-部门商品可用，32-全部商品可用 |
| scopeDescription | STRING | 适用范围描述 |
| scopes | ARRAY | 可用商品 spuId 列表，scopeType=31时，必传。[6.3.1 商品列表查询](#6.3.1 商品列表查询) |
| storeType | INTEGER | 可用门店范围：0-全部门店可用（默认值），1-部分门店可用 |
| storeScopes | ARRAY | 可用门店 storeId 列表，storeType=1时，必传。[7.1.8 门店信息详情查询](#7.1.8 门店信息详情查询) |
| storeNum | INTEGER | 门店数量 |
| channel | STRING | 优惠券发放渠道：0-不限制；1-指定CPS商品推广渠道 |
| placement | STRING | 展示位置： 120-默认展示（在商品详情页、购物车、店铺页等页面展示） 121-抽奖奖品 122-裂变活动奖品 123-互动任务奖品 124-平台合作（由平台运营配置展示位置；商品详情页等无法展示） 125-自定义（仅限搭建页发放，商品详情页等无法展示） |
| description | STRING | 备注 |
| acquireNum | INTEGER | 已领取数量 |
| usedNum | INTEGER | 已使用数量 |
| creator | STRING | 创建者 |
| createTime | DATETIME | 创建时间，格式：2022-06-20 00:00:00 |
| operator | STRING | 操作者/更新者 |
| updateTime | DATETIME | 更新时间，格式：2022-06-20 00:00:00 |
# 5.5.2 枚举值
availableUseType：用券时间类型
0-固定时间
开始时间：availableUseBeginTime
结束时间：availableUseEndTime
1-领券当日起 availableUsePeriod 天可用
开始时间：领取时间
结束时间：领取时间 + availableUsePeriod 天
示例：2021-02-01 21:00:00 领取，领券当日起 1 天内可用；券的可用时间为：2021-02-01 21:00:00 ~ 2021-02-02 20:59:59；
3-领券当日起 availableUseBeginPeriod 天后开始可用，availableUsePeriod 天后结束可用
开始时间：领取时间 + availableUseBeginPeriod 天
结束时间：开始时间 + availableUsePeriod 天
示例：2021-02-01 21:00:00 领取，领券当日起 3 天后开始可用，1 天后结束可用；券的可用时间为：2021-02-04 21:00:00 ~ 2021-02-05 20:59:59；
status：优惠券批次状态
0-草稿
2-待激活
4-激活中
5-进行中手动停止
6-已结束
7-未开始
8-进行中
9-未开始取消
10-下线
# 5.5.3 优惠券列表查询
- 接口名
/promote/report/stock/page
- 使用场景
- 查询商家在智慧零售侧的优惠券分页列表
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。 |
| pageSize | INTEGER | 是 | 每页查询数量，最大 100。 |
- 业务请求参数示例
{
"pageNum": 1,
"pageSize": 10
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "e0c9e4d8-762e-4cff-abc9-70f59d7c2d9d",
"total": 35,
"stocks": [
{
"stockId": 424334668538277065,
"stockName": "测试大额",
"couponType": 4,
"scopeType": 32,
"scopeDescription": "店铺内全部商品可用",
"storeType": 1,
"storeNum": 2,
"status": 2,
"threshold": 5000000,
"moneyOf": 1111111,
"acquireNum": 0,
"usedNum": 0,
"availableBeginTime": "2022-06-16 00:00:00",
"availableEndTime": "2023-06-15 23:59:59",
"availableUseBeginTime": null,
"availableUseEndTime": null,
"availableUseType": 1,
"availableUsePeriod": 1,
"availableUseBeginPeriod": 0,
"creator": "E95281",
"createTime": "2022-06-16 13:45:54",
"description": "这是备注"
}
]
}
}
# 5.5.4 优惠券详情查询
- 接口名
/promote/report/stock/detail
- 使用场景
- 通过优惠券 id 查询详情信息
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| stockId | LONG | 是 | 优惠券 id |
- 业务请求参数示例
{
"stockId": 424337537576440551
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "4feb3762-8034-4318-8845-67bc0b2969a0",
"stock": {
"stockId": 424334668538277065,
"stockName": "测试大额",
"status": 2,
"couponType": 4,
"scopeType": 32,
"scopes": null,
"scopeDescription": "店铺内全部商品可用",
"maxCouponsPerUser": 1,
"dailyMaxCouponsPerUser": 1,
"threshold": 5000000,
"moneyOf": 1111111,
"maxCoupons": 1,
"acquireNum": 0,
"usedNum": 0,
"availableBeginTime": "2022-06-16 00:00:00",
"availableEndTime": "2023-06-15 23:59:59",
"availableUseBeginTime": null,
"availableUseEndTime": null,
"availableUseType": 1,
"availableUsePeriod": 1,
"availableUseBeginPeriod": 0,
"creator": "E95281",
"createTime": "2022-06-16 13:45:54",
"description": "这是备注",
"storeType": 1,
"storeScopes": [
"1e9PoMGPv9A",
"VJdr84gjmAg"
],
"storeNum": 2,
"channel": "1",
"placement": "124"
}
}
}
# 5.5.5 优惠券草稿保存
- 接口名
/promote/report/stock/draft
- 使用场景
- 保存草稿
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| stockId | LONG | 否 | 新建时无需传递 stockId。 修改时需要传递 stockId。 |
| stockName | STRING | 是 | 优惠券名称 |
| couponType | INTEGER | 是 | 优惠券类型：4-腾讯荟聚商家券 |
| threshold | INTEGER | 是 | 优惠使用门槛金额，单位：分。如：满 10 减 5，threshold=1000。 |
| moneyOf | INTEGER | 是 | 优惠券面额，单位：分。如：满 10 减 5，moneyOf=500。 |
| maxCoupons | INTEGER | 是 | 优惠券总库存 |
| maxCouponsPerUser | INTEGER | 是 | 每人可领数量 |
| dailyMaxCouponsPerUser | INTEGER | 是 | 每人每天可领数量 |
| availableBeginTime | DATETIME | 是 | 领券的开始时间，"2022-06-20 00:00:00" |
| availableEndTime | DATETIME | 是 | 领券的结束时间，"2023-06-15 23:59:59" |
| availableUseType | INTEGER | 是 | 用券时间类型： 0-固定时间。 1-领券当日起 N 天可用。 3-领券当日起 M 天后开始可用，N 天后结束可用。 |
| availableUseBeginTime | DATETIME | 否 | 核销的开始时间，"2022-06-20 00:00:00" availableUseType=0 时，必传 |
| availableUseEndTime | DATETIME | 否 | 核销的结束时间，"2023-06-15 23:59:59" availableUseType=0 时，必传 |
| availableUsePeriod | INTEGER | 否 | 领取后 availableUsePeriod 天可用，单位：天 availableUseType=1或3，必传 |
| availableUseBeginPeriod | INTEGER | 否 | 领券当日起 availableUseBeginPeriod 天后开始可用 availableUsePeriod 天后结束可用，单位：天 availableUseType=3，必传 |
| scopeType | INTEGER | 是 | 适用范围类型，31-部门商品可用，32-全部商品可用 |
| scopes | ARRAY | 否 | 可用商品列表，scopeType=31时，必传 |
| storeType | INTEGER | 是 | 可用门店范围：0-全部门店可用（默认值），1-部分门店可用 |
| storeScopes | ARRAY | 否 | 可用门店列表，storeType=1时，必传 |
| channel | STRING | 是 | 优惠券发放渠道：0-不限制；1-指定CPS商品推广渠道 |
| placement | STRING | 是 | 展示位置： 120-优惠券可在商详、购物车、店铺页等页面展示，并支持领券。 124-优惠券提交后状态为：待激活，需要将券批次ID给到平台运营绑定展示的位置，用户才能看到并领取。 |
| description | STRING | 否 | 备注 |
| creator | STRING | 是 | 创建者 |
| operator | STRING | 是 | 操作者/更新者 |
- 业务请求参数示例
{
"stockId": 1,
"stockName": "测试",
"couponType": 4,
"threshold": 50000,
"moneyOf": 11111,
"maxCoupons": 10,
"maxCouponsPerUser": 2,
"dailyMaxCouponsPerUser": 1,
"availableBeginTime": "2022-06-16 00:00:00",
"availableEndTime": "2023-06-15 23:59:59",
"availableUseType": 1,
"availableUseBeginTime": null,
"availableUseEndTime": null,
"availableUsePeriod": 7,
"availableUseBeginPeriod": 0,
"scopeType": 31,
"scopes": [
"p1219492331789",
"p1321000713988",
"p1321000713986"
],
"storeType": 1,
"storeScopes": [
"1e9PoMGPv9A",
"VJdr84gjmAg"
],
"channel": "1",
"placement": "124",
"description": "备注",
"creator": "张三",
"operator": "张三"
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "03e7250e-967d-4774-83c2-50029afd2fff",
"stockId": 424334702898018689
}
}
# 5.5.5 优惠券提交
- 接口名
/promote/report/stock/submit
- 使用场景
- 提交优惠券，使其生效。如果 stockId 存在，提交时只修改优惠券状态。
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| stockId | LONG | 否 | 新建时无需传递 stockId。 修改时需要传递 stockId。 |
| stockName | STRING | 是 | 优惠券名称 |
| couponType | INTEGER | 是 | 优惠券类型：4-腾讯荟聚商家券 |
| threshold | INTEGER | 是 | 优惠使用门槛金额，单位：分。如：满 10 减 5，threshold=1000。 |
| moneyOf | INTEGER | 是 | 优惠券面额，单位：分。如：满 10 减 5，moneyOf=500。 |
| maxCoupons | INTEGER | 是 | 优惠券总库存 |
| maxCouponsPerUser | INTEGER | 是 | 每人可领数量 |
| dailyMaxCouponsPerUser | INTEGER | 是 | 每人每天可领数量 |
| availableBeginTime | DATETIME | 是 | 领券的开始时间，"2022-06-20 00:00:00" |
| availableEndTime | DATETIME | 是 | 领券的结束时间，"2023-06-15 23:59:59" |
| availableUseType | INTEGER | 是 | 用券时间类型： 0-固定时间。 1-领券当日起 N 天可用。 3-领券当日起 M 天后开始可用，N 天后结束可用。 |
| availableUseBeginTime | DATETIME | 否 | 核销的开始时间，"2022-06-20 00:00:00" availableUseType=0 时，必传 |
| availableUseEndTime | DATETIME | 否 | 核销的结束时间，"2023-06-15 23:59:59" availableUseType=0 时，必传 |
| availableUsePeriod | INTEGER | 否 | 领取后 availableUsePeriod 天可用，单位：天 availableUseType=1或3，必传 |
| availableUseBeginPeriod | INTEGER | 否 | 领券当日起 availableUseBeginPeriod 天后开始可用 availableUsePeriod 天后结束可用，单位：天 availableUseType=3，必传 |
| scopeType | INTEGER | 是 | 适用范围类型，31-部门商品可用，32-全部商品可用 |
| scopes | ARRAY | 否 | 可用商品列表，scopeType=31时，必传 |
| storeType | INTEGER | 是 | 可用门店范围：0-全部门店可用（默认值），1-部分门店可用 |
| storeScopes | ARRAY | 否 | 可用门店列表，storeType=1时，必传 |
| channel | STRING | 是 | 优惠券发放渠道：0-不限制；1-指定CPS商品推广渠道 |
| placement | STRING | 是 | 展示位置： 120-优惠券可在商详、购物车、店铺页等页面展示，并支持领券。 124-优惠券提交后状态为：待激活，需要将券批次ID给到平台运营绑定展示的位置，用户才能看到并领取。 |
| description | STRING | 否 | 备注 |
| creator | STRING | 是 | 创建者 |
| operator | STRING | 是 | 操作者/更新者 |
- 业务请求参数示例
{
"stockId": 100,
"stockName": "测试",
"couponType": 4,
"threshold": 50000,
"moneyOf": 11111,
"maxCoupons": 10,
"maxCouponsPerUser": 2,
"dailyMaxCouponsPerUser": 1,
"availableBeginTime": "2022-06-16 00:00:00",
"availableEndTime": "2023-06-15 23:59:59",
"availableUseType": 1,
"availableUseBeginTime": null,
"availableUseEndTime": null,
"availableUsePeriod": 7,
"availableUseBeginPeriod": 0,
"scopeType": 31,
"scopes": [
"p1219492331789",
"p1321000713988",
"p1321000713986"
],
"storeType": 1,
"storeScopes": [
"1e9PoMGPv9A",
"VJdr84gjmAg"
],
"channel": "1",
"placement": "124",
"description": "备注",
"creator": "张三",
"operator": "张三"
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "03e7250e-967d-4774-83c2-50029afd2fxxx",
"stockId": 424334702898018689
}
}
# 5.5.6 优惠券取消发放
- 接口名
/promote/report/stock/cancel
- 使用场景
- 优惠券已提交但未开始，才允许取消，即领券开始时间（availableBeginTime）必须大于当前时间。如果已经开始，不能取消，只能停止。
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| stockId | LONG | 是 | 优惠券批次 id |
- 业务请求参数示例
{
"stockId": 424337537576440660
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "282882910sdjjs0193901990"
}
}
# 5.5.7 优惠券停止发放
- 接口名
/promote/report/stock/stop
- 使用场景
- 优惠券已提交且生效，才允许停止发放
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| stockId | LONG | 是 | 优惠券批次 id |
- 业务请求参数示例
{
"stockId": 424334668538277637
}
- 响应结果
{
"code": 0,
"message": "success",
"data": {
"requestId": "282882910sdjjs0193901990"
}
}
# 6. 普通商家专用API列表
# 6.1 物流API
# 6.1.1 一单多物流 - 发货
- 接口名
/logistics/delivery/save
- 使用场景
- 商家需要对不同sku用不同快递发货 (支持同一sku分不同物流单录入)
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | STRING | 是 | 智慧零售侧订单号 |
| deliverPackages | STRING | 是 | 多物流快递信息，JSON格式 |
| forceDeliver | Integer | 否 | 如遇待审核售后单是否继续发货：0-默认，不执行发货 1-自动关闭售后单，同时继续执行发货 |
- 业务请求参数示例
{
"orderId": "智慧零售订单号",
"deliverPackages": "[
{
\"deliverNumber\": \"商家发货快递单号\",
\"deliverCompany\": \"智慧零售快递公司编码\",
\"deliverItems\": [
{
\"skuId\": \"智慧零售skuId\",
\"spuId\": \"智慧零售spuId\",
\"outerSkuId\": \"商家skuId\",
\"qty\": 1
},
{
\"skuId\": \"智慧零售skuId\",
\"spuId\": \"智慧零售spuId\",
\"outerSkuId\": \"商家skuId\",
\"qty\": 2
}
]
}
]",
"forceDeliver":0
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx" //string 请求ID
}
}
# 6.1.2 一单多物流 - 修改发货信息
- 接口名
/logistics/delivery/update
- 使用场景
- 商家需对已录入多物流信息修改(比如物流单号或发货数量需要更正)
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | STRING | 是 | 智慧零售侧订单号 |
| updateDeliverPackages | STRING | 是 | 商家要修改的物流信息，JSON格式oldPackage对应修改前数据，newPackage对应修改后数据 |
- 业务请求参数示例
{
"orderId": "智慧零售订单号",
"updateDeliverPackages": "{
\"oldPackage\": {
\"deliverNumber\":\"智慧零售订单号\",
\"deliverCompany\":\"智慧零售定义的快递公司编码\",
\"deliverItems\": [
{
\"skuId\":\"智慧零售skuId\",
\"spuId\":\"智慧零售spuId\",
\"outerSkuId\":\"商家skuId\",
\"qty\":1
}
]
},
\"newPackage\":{
\"deliverNumber\":\"773051332313336\",
\"deliverCompany\":\"shentong\",
\"deliverItems\":[
{
\"skuId\":\"智慧零售skuId\",
\"spuId\":\"智慧零售spuId\",
\"outerSkuId\":\"商家skuId\",
\"qty\":2
}
]
}
}"
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx" //string 请求ID
}
}
# 6.2 商品库存API
# 6.2.1 商品库存查询
- 接口名
/goods/stock/list
- 使用场景
- 商家修改sku库存之前先查询智慧零售侧该商品库存信息
- 调用方式: 回调
- 商家限流qps: 30
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| outerSkuIds | STRING | 是 | 商家skuId列表(最大50个) List结构格式化为JSON |
- 业务请求参数示例
{
"outerSkuIds": [
\"商家skuId1\",
\"商家skuId2\"
]
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "请求ID回传",
"list": [
{
"outerSkuId": "商家skuId",
"skuId": "智慧零售skuId",
"qty": 1, //当前库存
"lockedQty": 2 //订单锁定库存,为用户下单后，未支付订单锁定的库存；
}
]
}
}
# 6.2.2 商品库存修改
- 接口名
/goods/stock/update
- 使用场景
- 商家增量修改智慧零售侧sku库存
- 增量修改时不能让最终总库存为负数
- 库存同步为 “智慧零售侧sku库存”，商家在更新商品库存时,必须保证 商家侧当前可售库存 - 订单锁定库存 =智慧零售侧sku库存数量(用户可购买的数量)；
- 调用方式: 回调
- 商家限流qps: 30
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| actionType | INTEGER | 是 | 库存修改类型 1:全量修改 2:调增 3:调减 |
| stockList | STRING | 是 | 商家修改sku库存对象列表(最大50个)，List结构格式化为JSON |
- 业务请求参数示例
{
"actionType": 2,
"stockList": [
{
\"skuId\": \"智慧零售skuId\",
\"qty\": 100 //库存加100
},
{
\"skuId\": \"智慧零售skuId\",
\"qty\": 200 //库存加200
},
]
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "请求ID回传",
"failedSkuIds": [
"更新失败的智慧零售skuId1",
"更新失败的智慧零售skuId2"
],
"failedMsg": "更新失败原因"
}
}
# 6.3 商品API
# 6.3.1 商品列表查询
- 接口名
/goods/list
使用场景
- 查询商家在智慧零售侧的商品信息
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuIds | STRING | 非必填 | 平台 SPU ID，支持多个，用逗号隔开，最多20个 |
| outSpuIds | STRING | 非必填 | 商家 SPU 编码，支持多个，用逗号隔开，最多20个 |
| state | INTEGER | 非必填 | 状态(1 待上架, 2 在售中，3 已售罄，4 已下架， 5 审核中， 6 审核失败) |
| updateBegin | LONG | 非必填 | 更新时间-起始。大于等于。毫秒时间戳。 |
| updateEnd | LONG | 非必填 | 更新时间-止于。小于等于。毫秒时间戳。 |
| pageNum | INTEGER | 非必填 | 页码，默认1 |
| pageSize | INTEGER | 非必填 | 每页大小，默认15，最大100 |
- 请求示例
{
"spuIds": "xxx1,xxx2",
"outSpuIds": "xx1",
"state": 1,
"updateBegin": 1603714767000,
"updateEnd": 1603714867000,
"pageNum": 2,
"pageSize": 20
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - total | INTEGER | 总数 |
| - spuList | ARRAY | SPU 列表 |
| -- spuId | STRING | 平台 SPU ID |
| -- outSpuId | STRING | 商家 SPU 编码 |
| -- merchantId | STRING | 商家 ID |
| -- name | STRING | 商品名称 |
| -- brandId | NUMBER | 品牌 ID |
| -- brandName | STRING | 品牌名称 |
| -- spuImg | STRING | 商品主图 |
| -- carousel | STRING | 商品轮播图 |
| -- content | STRING | 商品详情图 |
| -- marketPrice | INTEGER | 商品吊牌价（分为单位） |
| -- referencePrice | INTEGER | 商品市场参考价（分为单位） |
| -- categoryId1 | NUMBER | 一级类目 ID |
| -- categoryName1 | STRING | 一级类目名称 |
| -- categoryId2 | NUMBER | 二级类目 ID |
| -- categoryName2 | STRING | 二级类目名称 |
| -- categoryId3 | NUMBER | 三级类目 ID |
| -- categoryName3 | STRING | 三级类目名称 |
| -- reduceType | INTEGER | 库存计件（1 用户下单减库存，2 用户付款减库存 ） |
| -- shippingTemplateId | LONG | 运费模板 ID |
| -- weight | INTEGER | 物流重量（含包装），单位克 |
| -- state | NUMBER | 状态(1 待上架, 2 在售中，3 已售罄，4 已下架， 5 审核中， 6 审核失败) |
| -- onTime | LONG | 定时上架时间（毫秒时间戳） |
| -- offTime | LONG | 定时下架时间（毫秒时间戳） |
| -- updateTime | LONG | 更新时间（毫秒时间戳） |
| -- createTime | LONG | 创建时间（毫秒时间戳） |
| -- limitCount | INTEGER | 商品限购数量（1-10000）0或null不限购 |
| -- skuList | ARRAY | SKU 列表 |
| --- skuId | STRING | 平台 SKU ID |
| --- outSkuId | STRING | 商家 SKU 编码 |
| --- barCode | STRING | 条形码 |
| --- skuImg | STRING | SKU 图片 |
| --- styles1 | STRING | 规格1 |
| --- styles1name | STRING | 规格1名称 |
| --- styles2 | STRING | 规格2 |
| --- styles2name | STRING | 规格2名称 |
| --- stock | NUMBER | 库存 |
| --- freezingStock | NUMBER | 活动冻结库存 |
| --- settlementPrice | NUMBER | 结算价（分为单位） |
| --- state | STRING | 状态（1上架，2下架） |
| --- marketPrice | NUMBER | 划线价/吊牌价（分为单位） |
| --- marketPriceCertificate | STRING | 划线价/吊牌价凭证 |
| --- referencePrice | NUMBER | 参考价 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "回传的RequestId",
"total": 50,
"spuList": [
{
"spuId": "平台 SPU ID",
"outSpuId": "商家 SPU 编码",
"merchantId": "商家 ID",
"name": "商品名称",
"brandId": 1,
"brandName": "品牌名称",
"spuImg": "https://img.zhls.qq.com/0/商品主图.jpg",
"carousel": ["https://img.zhls.qq.com/1/商品轮播图.jpg"],
"content": ["https://img.zhls.qq.com/1/商品详情图1.jpg"],
"marketPrice": 700,
"referencePrice": 700,
"categoryId1": 122,
"categoryName1": "服饰内衣",
"categoryId2": 122205,
"categoryName2": "女装",
"categoryId3": 122205989,
"categoryName3": "仿皮皮衣",
"reduceType": 1,
"shippingTemplateId": 1,
"weight": 21000,
"state": 4,
"onTime": 1603710993000,
"offTime": 0,
"updateTime": 1603714867000,
"createTime": 1603710891000,
"skuList": [
{
"skuId": "平台 SKU ID",
"outSkuId": "商家 SKU 编码",
"barCode": "SKU 条形码",
"skuImg": "https://img.zhls.qq.com/0/SKU图片.jpg",
"styles1": "尺寸",
"styles1name": "203*230CM",
"styles2": "颜色",
"styles2name": "粉",
"stock": 11,
"freezingStock": 11,
"settlementPrice": 100,
"marketPrice": 100,
"marketPriceCertificate": "https://img.zhls.qq.com/0/SKU图片.jpg",
"referencePrice": 200,
"state": 1
}
]
}
]
}
}
# 6.3.2 运费模板查询
- 接口名
/goods/shipping/list
使用场景
- 新增、修改 spu，查询商家可使用的运费模版
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| templateIds | STRING | 非必填 | 运费模板id，支持多个，用逗号隔开，最多15个 |
| pageNum | STRING | 非必填 | 页码，默认1 |
| pageSize | STRING | 非必填 | 每页大小，默认15，最大15 |
- 请求示例
{
"templateIds": 1,
"pageNum": 2,
"pageSize": 20
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - total | INTEGER | 总数 |
| - list | ARRAY | 运费模板列表 |
| -- templateId | NUMBER | 运费模板 ID |
| -- templateName | STRING | 模板名称 |
| -- type | NUMBER | 模板类型（0:官方模版，1:自定义模版） |
| -- merchantId | STRING | 商家ID（官方模版，商家 ID 为 0） |
| -- shipRegion | OBJECT | 发货地区 |
| --- regionId | STRING | 地区 ID |
| --- regionName | STRING | 地区名称 |
| -- feeType | Number | 计费方式（0：按件数计费，1：按重量计费） |
| -- freeRegions | ARRAY | 包邮区域 |
| --- regionId | STRING | 地区 ID |
| --- regionName | STRING | 地区名称 |
| -- noRegions | ARRAY | 不配送区域 |
| --- regionId | STRING | 地区 ID |
| --- regionName | STRING | 地区名称 |
| -- payFees | ARRAY | 不包邮区域/买家付邮费区域 |
| --- feeId | Number | 运费 ID |
| --- region | OBJECT | 运费地区 |
| ----- regionId | STRING | 地区 ID |
| ----- regionName | STRING | 地区名称 |
| --- baseCount | Number | 基础计量（根据模版的计费方式，单位为克或件） |
| --- basePrice | Number | 基础价格（分为单位） |
| --- incrCount | Number | 递增计量（根据模版的计费方式，单位为克或件） |
| --- incrPrice | Number | 递增价格（分为单位） |
| --- isConditionFree | Number | 指定条件包邮（0否1是） |
| --- conditionCount | Number | 包邮计量 |
| --- conditionUnit | Number | 包邮单位（1:价钱-分，2:件） |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"total": 50,
"list": [
{
"templateId": 1,
"templateName": "运费模板名称",
"type": 0,
"merchantId": "0",
"shipRegion": {
"regionId": 130102,
"regionName": "河北省/石家庄市/长安区"
},
"feeType": 0,
"freeRegions": [
{
"regionId": 110000,
"regionName": "北京市"
}
],
"noRegions": [
{
"regionId": 330102,
"regionName": "浙江省杭州市上城区"
}
],
"payFees": [
{
"feeId": 440,
"region": {
"regionId": 110000,
"regionName": "河北省"
},
"baseCount": 1,
"basePrice": 1400,
"incrCount": 1,
"incrPrice": 0,
"isConditionFree": 1,
"conditionCount": 3,
"conditionUnit": 2
}
]
}
]
}
}
# 6.3.3 规格查询
- 接口名
/goods/style/list
使用场景
- 新增、修改 spu，查询商家可使用的规格
调用方式: 回调
商家限流qps: 30
请求参数
无
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - list | ARRAY | 规格列表 |
| -- templateId | NUMBER | 模板 ID |
| -- name | STRING | 规格模板名 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"list": [
{
"templateId": 1,
"name": "颜色"
},
{
"templateId": 2,
"name": "尺码"
}
]
}
}
# 6.3.4 类目查询
- 接口名
/goods/category/list
使用场景
- 新增、修改 spu，查询商家可使用的类目
调用方式: 回调
商家限流qps: 30
请求参数
无
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - list | ARRAY | 类目列表 |
| -- id | NUMBER | 类目 ID |
| -- name | STRING | 类目名称 |
| -- parentId | NUMBER | 父类目ID |
| -- children | ARRAY | 子类目 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"list": [
{
"id": 102,
"name": "全屋定制",
"parentId": 0,
"children": [
{
"id": 102102,
"name": "地暖暖气片散热器",
"parentId": 102,
"children": [
{
"id": 102102102,
"name": "低温电热辐射地暖系统",
"parentId": 102102,
"children": null
}
]
}
]
}
]
}
}
# 6.3.5 品牌查询
- 接口名
/goods/brand/list
使用场景
- 新增、修改 spu，查询商家可使用的品牌
调用方式: 回调
商家限流qps: 30
请求参数
无
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - list | ARRAY | 品牌列表 |
| -- id | NUMBER | 品牌 ID |
| -- name | STRING | 品牌名称 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"list": [
{
"id": 1,
"name": "花王"
},
{
"id": 2,
"name": "资生堂集团"
}
]
}
}
# 6.3.6 新增 SPU(包括 SKU)
- 接口名
/goods/add
使用场景
- 新增 spu
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| version | STRING | 非必填 | 默认v1.6.0, 参考版本编号 |
| outSpuId | STRING | 必填 | 商家商品编码。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| name | STRING | 必填 | 商品名称。最多输入60个字。 |
| brandId | Long | 必填 | 品牌 ID。通过【品牌查询接口】获取到商家可设置的品牌ID |
| categoryId | LONG | 必填 | 叶子类目 ID（三级类目 ID）。通过【类目查询接口】获取到商家可设置的类目，并取三级类目 ID |
| marketPrice | INTEGER | 必填 | 商品吊牌价（分为单位）。大于0。大于等于SKU结算价。指的是商品的原价，一般与商品吊牌上的价格一致；也叫在其他电商平台上划线价，或者市场价； |
| referencePrice | INTEGER | 非必填 | 商品市场参考价（分为单位）。大于0。指商家在其他渠道上的销售价格 |
| reduceType | INTEGER | 必填 | 库存计件（1 用户下单减库存，2 用户付款减库存 ）。现阶段暂只支持 1 |
| shippingTemplateId | LONG | 必填 | 运费模板。通过【运费模板查询接口】获取到商家已设置的运费模板ID，并传入运费模板ID |
| weight | INTEGER | 必填 | 物流重量（含包装），单位克。大于等于0.01千克，小于等于999千克。 |
| onTime | LONG | 非必填 | 定时上架时间（毫秒时间戳）。商品发布审核通过后，会根据此时间判断是否上架；不传系统会默认商品创建时间为开始时间 |
| offTime | LONG | 非必填 | 定时下架时间（毫秒时间戳）。商品发布审核通过后，会根据此时间判断是否下架；不传系统会默认2029-01-01 08:00:00为结束时间，即下架时间 |
| carousel | STRING | 必填 | 商品轮播图。最多5张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG，第一张商品图片默认为商品主图；图片尺寸长宽比1：1且单张图片大小不超过2M，建议尺寸为800px*800px；图片url不要带参数；需要将 OBJECT[] 类型转为 STRING 类型的 JSON 字符串 |
| content | STRING | 必填 | 商品详情图。最多30张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M，图片宽度建议750px；图片url不要带参数；需要将 OBJECT[] 类型转为 STRING 类型的 JSON 字符串 |
| skuList | STRING | 必填 | sku 对象列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - style1TemplateId | NUMBER | 必填 | 规格1模版id。可输入值：通过【规格查询接口】查询 |
| - style1name | STRING | 必填 | 规格1名称。规格名称不超过40个字； |
| - style2TemplateId | NUMBER | 非必填 | 规格2模版id。规格1已经选择的规格值，规格2不能再次选择； |
| - style2name | STRING | 非必填 | 规格2名称。上述规格2有值，则规格2名称为必填；规格名称不超过40个字；说明：在规格1、规格2都有值的情况下，需要按所需的【规格1，规格2】组合传入SKU，系统不会通过笛卡尔乘积自动组合；比如：规格1为：黑色、白色；规格2为：L、M；可只传入组合为：【黑色，L】、【白色，M】； |
| - outSkuId | STRING | 必填 | 商家 SKU 编码。商家自身判断商品sku的唯一标识，sku维度。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - barCode | STRING | 非必填 | 条形码。不能为0。仅能包含：字母、数字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - skuImg | STRING | 非必填 | SKU 图片。通过【图片上传接口】上传。图片长宽比1:1，大小不超过2M；建议尺寸为：350px*350px；图片url不要带参数； |
| - stock | NUMBER | 非必填 | 库存。大于等于0，小于99999999。不填则默认为0，初始库存通过商品新增接口传入，后续对库存修改，则通过【库存增减接口】调整库存； |
| - settlementPrice | NUMBER | 必填 | 结算价（分为单位）。大于0。小于等于SPU吊牌价。指智慧零售与商家协商，商品销售后，需要结算给商家的价格； |
| - marketPrice | NUMBER | 必填 | 划线价/吊牌价（分为单位）。大于0。大于等于SKU结算。 |
| - marketPriceCertificate | STRING | 必填 | 划线价/吊牌价凭证，吊牌价大于等于2倍的SKU结算价时，必须填写 |
| - referencePrice | NUMBER | 非必填 | 参考价, 选填 |
| - state | INTEGER | 必填 | 状态（1上架，2下架） |
| shipPledgeHours | INTEGER | 非必填 | 商品发货时间承诺（小时为单位）。默认值72，可选值72,120,168,240,360,720,1440 |
| whiteImage | STRING | 必填 | 商品白底图。图片必须为纯白底，图片长宽比要求为1:1，单张图片大小不能大于2M，建议图片尺寸为800*800像素，无logo、无水印，建议将素材抠图、边缘处理干净 |
| limitCount | INTEGER | 非必填 | 商品限购数量。大于0，小于等于10000 |
| attrList | STRING | 必填 | v1.7.5以上版本支持，属性列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - attributeId | NUMBER | 必填 | 属性项ID；可输入值：通过【属性项列表查询接口】查询 |
| - attrItems | ARRAY | 非必填 | 单/多选时，选中的属性值ID(itemId)的列表 |
| - attrValue | STRING | 非必填 | 输入框时。填写的属性值； |
| installments | INTEGER | 非必填 | v1.7.13以上版本支持，是否支持分期支付，1否，2是，默认否 |
- 业务请求参数示例
{
"version": "v1.7.5",
"outSpuId": "商家 SPU 编码",
"name": "商品名称",
"brandId": 1,
"categoryId": 122,
"marketPrice": 700,
"referencePrice": 700,
"reduceType": 1,
"shippingTemplateId": 1,
"weight": 21000,
"onTime": 1603710993000,
"offTime": 0,
"carousel": "[\"https://img.zhls.qq.com/1/商品轮播图.jpg\"]",
"content": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]",
"skuList": "[{\"outSkuId\":\"商家SKU编码\",\"barCode\":\"SKU条形码\",\"skuImg\":\"https://img.zhls.qq.com/0/SKU图片.jpg\",\"style1TemplateId\":1,\"style1name\":\"203*230CM\",\"style2TemplateId\":2,\"style2name\":\"粉\",\"stock\":11,\"settlementPrice\":100,\"state\":1,\"marketPrice\":100,\"marketPriceCertificate\":\"https://img.zhls.qq.com/1/吊牌价凭证.jpg\"}]",
"shipPledgeHours": 72,
"whiteImage": "https://img.zhls.qq.com/1/商品白底图.jpg",
"attrList": "[{\"templateId\":509101101001,\"attrItems\":[5091011010011],\"attrValue\":null},{\"templateId\":509101101004,\"attrItems\":null,\"attrValue\":\"十万个为什么\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - spuId | STRING | 平台 SPU ID |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"spuId": "p123456789"
}
}
# 6.3.7 修改 SPU(包括 SKU)
注: spu 没有单独的状态字段，“spu状态”其实就是综合“定时上下架时间”和“库存”得到的综合状态。
5.6.7 里面可以改是“定时上下架时间”的，等效于改了“spu状态”。
5.6.8 这个只是一个修改“spu状态”的便捷接口，实际改动也是变更“定时上下架时间”。
- 接口名
/goods/update
使用场景
- 在商品提交审核后，商品状态为：审核不通过、已下架状态下，允许编辑修改商品中的相关字段；
- 目前只允许部分字段修改；
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| version | STRING | 非必填 | 默认v1.6.0, 文档版本编号 |
| spuId | STRING | 必填 | 平台 SPU ID |
| outSpuId | STRING | 必填 | 商家商品编码。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| name | STRING | 必填 | 商品名称。最多输入60个字。 |
| marketPrice | INTEGER | 必填 | 商品吊牌价（分为单位）。大于0。大于等于SKU结算价。指的是商品的原价，一般与商品吊牌上的价格一致；也叫在其他电商平台上划线价，或者市场价； |
| referencePrice | INTEGER | 非必填 | 商品市场参考价（分为单位）。大于0。指商家在其他渠道上的销售价格 |
| reduceType | INTEGER | 必填 | 库存计件（1 用户下单减库存，2 用户付款减库存 ）。现阶段暂只支持 1 |
| shippingTemplateId | LONG | 必填 | 运费模板。通过【运费模板查询接口】获取到商家已设置的运费模板ID，并传入运费模板ID |
| weight | INTEGER | 必填 | 物流重量（含包装），单位克。大于等于0.01千克，小于等于999千克。 |
| onTime | LONG | 非必填 | 定时上架时间（毫秒时间戳）。商品发布审核通过后，会根据此时间判断是否上架；不传系统会默认商品创建时间为开始时间 |
| offTime | LONG | 非必填 | 定时下架时间（毫秒时间戳）。商品发布审核通过后，会根据此时间判断是否下架；不传系统会默认2029-01-01 08:00:00为结束时间，即下架时间 |
| carousel | STRING | 必填 | 商品轮播图。最多5张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG，第一张商品图片默认为商品主图；图片尺寸长宽比1：1且单张图片大小不超过2M，建议尺寸为800px*800px；图片url不要带参数； |
| content | STRING | 必填 | 商品详情图。最多30张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M，图片宽度建议750px；图片url不要带参数； |
| skuList | STRING | 必填 | sku 对象列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - skuId | STRING | 非必填 | 平台 SKU ID。传则认为是修改，不传则认为是新增 |
| - style1name | STRING | 非必填 | 规格1名称。如该spu规格1有值，则必填。规格名称不超过40个字； |
| - style2name | STRING | 非必填 | 规格2名称。如该spu规格2有值，则必填。规格名称不超过40个字；说明：在规格1、规格2都有值的情况下，需要按所需的【规格1，规格2】组合传入SKU，系统不会通过笛卡尔乘积自动组合；比如：规格1为：黑色、白色；规格2为：L、M；可只传入组合为：【黑色，L】、【白色，M】； |
| - outSkuId | STRING | 必填 | 商家 SKU 编码。商家自身判断商品sku的唯一标识，sku维度。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - barCode | STRING | 非必填 | 条形码。不能为0。仅能包含：字母、数字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - skuImg | STRING | 非必填 | SKU 图片。通过【图片上传接口】上传。图片长宽比1:1，大小不超过2M；建议尺寸为：350px*350px；图片url不要带参数； |
| - settlementPrice | NUMBER | 必填 | 结算价（分为单位）。大于0。小于等于SPU吊牌价。参加活动期间不能修改。指智慧零售与商家协商，商品销售后，需要结算给商家的价格； |
| - state | INTEGER | 必填 | 状态（1上架，2下架） |
| - marketPrice | NUMBER | 必填 | 划线价/吊牌价（分为单位）。大于0。大于等于SKU结算。 |
| - marketPriceCertificate | STRING | 必填 | 划线价/吊牌价凭证，吊牌价大于等于2倍的SKU结算价时，必须填写 |
| - referencePrice | NUMBER | 非必填 | 参考价, 选填 |
| shipPledgeHours | INTEGER | 非必填 | 商品发货时间承诺（小时为单位）。默认值72，可选值72,120,168,240,360,720,1440 |
| whiteImage | STRING | 必填 | 商品白底图。图片必须为纯白底，图片长宽比要求为1:1，单张图片大小不能大于2M，建议图片尺寸为800*800像素，无logo、无水印，建议将素材抠图、边缘处理干净 |
| limitCount | INTEGER | 非必填 | 商品限购数量。大于0，小于等于10000 |
| attrList | STRING | 必填 | v1.7.5以上版本支持， 属性列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - attributeId | NUMBER | 必填 | 属性项ID；可输入值：通过【属性项列表查询接口】查询 |
| - attrItems | ARRAY | 非必填 | 单/多选时，选中的属性值ID(itemId)的列表 |
| - attrValue | STRING | 非必填 | 输入框时。填写的属性值； |
| installments | INTEGER | 非必填 | v1.7.13以上版本支持，是否支持分期支付，1否，2是，默认否 |
- 业务请求参数示例
{
"version": "v1.7.5",
"spuId": "平台 SPU ID",
"outSpuId": "商家 SPU 编码",
"name": "商品名称",
"marketPrice": 700,
"referencePrice": 700,
"reduceType": 1,
"shippingTemplateId": 1,
"weight": 21000,
"onTime": 1603710993000,
"offTime": 0,
"carousel": "[\"https://img.zhls.qq.com/1/商品轮播图.jpg\"]",
"content": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]",
"skuList": "[{\"skuId\":\"平台SKUID\",\"outSkuId\":\"商家SKU编码\",\"barCode\":\"SKU条形码\",\"skuImg\":\"https://img.zhls.qq.com/0/SKU图片.jpg\",\"style1name\":\"203*230CM\",\"style2name\":\"粉\",\"settlementPrice\":100,\"state\":1,\"marketPrice\":100,\"marketPriceCertificate\":\"https://img.zhls.qq.com/1/吊牌价凭证.jpg\"}]",
"shipPledgeHours": 72,
"whiteImage": "https://img.zhls.qq.com/1/商品白底图.jpg",
"attrList": "[{\"templateId\":509101101001,\"attrItems\":[5091011010011],\"attrValue\":null},{\"templateId\":509101101004,\"attrItems\":null,\"attrValue\":\"十万个为什么\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.8 修改 SPU 状态
- 接口名
/goods/update/spu/state
使用场景
- SPU 上下架
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuIds | STRING | 必填 | 平台 SPU ID。支持多个，用逗号隔开，最多20个 |
| state | INTEGER | 必填 | 状态（1上架，2下架）；上架前置条件：商品状态为：已下架；下架前置条件：商品状态为：待上架、在售中、已售罄 |
- 业务请求参数示例
{
"spuIds": "平台_SPU_ID_1,平台_SPU_ID_2",
"state": 1
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.9 修改 SKU 状态
- 接口名
/goods/update/sku/state
使用场景
- SKU 上下架
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| skuIds | STRING | 必填 | 平台 SKU ID。支持多个，用逗号隔开，最多20个 |
| state | INTEGER | 必填 | 状态（1上架，2下架）；上架前置条件：商品状态为：下架；下架前置条件：商品状态为：上架 |
- 业务请求参数示例
{
"skuIds": "平台SKUID_1,平台SKUID_2",
"state": 1
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.10 修改 SPU 价格
- 接口名
/goods/update/spu/price
使用场景
- 请从sku/price接口进行价格调整
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuId | STRING | 必填 | 平台 SPU ID |
| marketPrice | INTEGER | 非必填 | 商品吊牌价（分为单位）。大于0。大于等于SKU结算价。至少选填一个。指的是商品的原价，一般与商品吊牌上的价格一致；也叫在其他电商平台上划线价，或者市场价； |
| referencePrice | INTEGER | 非必填 | 商品市场参考价（分为单位）。大于0。至少选填一个。指商家在其他渠道上的销售价格 |
- 业务请求参数示例
{
"spuId": "平台 SPU ID",
"marketPrice": 700,
"referencePrice": 700
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.11 修改 SKU 价格
- 接口名
/goods/update/sku/price
使用场景
- 在商品提交审核通过后，商品价格的修改，需要通过此接口进行调整，也可通过商品编辑接口进行修改；
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuId | STRING | 必填 | 平台 SPU ID |
| skuList | STRING | 必填 | sku 对象列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - skuId | STRING | 必填 | 平台 SKU ID |
| - settlementPrice | NUMBER | 必填 | 结算价（分为单位）。大于0。小于等于SPU吊牌价。参加活动期间不能修改。指智慧零售与商家协商，商品销售后，需要结算给商家的价格； |
| - marketPrice | NUMBER | 必填 | 划线价/吊牌价（分为单位）。大于0。大于等于SKU结算。 |
| - marketPriceCertificate | STRING | 必填 | 划线价/吊牌价凭证，吊牌价大于等于2倍的SKU结算价时，必须填写 |
- 业务请求参数示例
{
"spuId": "平台 SPU ID",
"skuList": "[{\"skuId\":\"平台SKUID\",\"settlementPrice\":100,\"marketPrice\":100,\"marketPriceCertificate\":\"https://img.zhls.qq.com/1/吊牌价凭证.jpg\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.12 修改 SPU 图片
- 接口名
/goods/update/spu/img
使用场景
- 在商品提交审核通过后，SPU 图片的修改，需要通过此接口进行调整，也可通过商品编辑接口进行修改；
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuId | STRING | 必填 | 平台 SPU ID |
| carousel | STRING | 非必填 | 商品轮播图，JSON数组转字符串。最多5张。至少选填一个，全量替换。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG，第一张商品图片默认为商品主图；图片尺寸长宽比1：1且单张图片大小不超过2M，建议尺寸为800px*800px；图片url不要带参数； |
| content | STRING | 非必填 | 商品详情图。JSON数组转字符串。最多30张。至少选填一个，全量替换。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M，图片宽度建议750px；图片url不要带参数； |
| whiteImage | STRING | 非必填 | 商品白底图。图片必须为纯白底，图片长宽比要求为1:1，单张图片大小不能大于2M，建议图片尺寸为800*800像素，无logo、无水印，建议将素材抠图、边缘处理干净 |
- 业务请求参数示例
{
"spuId": "平台 SPU ID",
"carousel": "[\"https://img.zhls.qq.com/1/商品轮播图.jpg\"]",
"content": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]",
"whiteImage": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.13 修改 SKU 图片
- 接口名
/goods/update/sku/img
使用场景
- 在商品提交审核通过后，SKU 图片的修改，需要通过此接口进行调整，也可通过商品编辑接口进行修改；
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuId | STRING | 必填 | 平台 SPU ID |
| skuList | STRING | 必填 | sku 对象列表。一次最多20个。需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - skuId | STRING | 必填 | 平台 SKU ID |
| - skuImg | STRING | 必填 | SKU 图片。全量替换。通过【图片上传接口】上传。图片长宽比1:1，大小不超过2M；建议尺寸为：350px*350px；图片url不要带参数； |
- 业务请求参数示例
{
"spuId": "平台 SPU ID",
"skuList": "[{\"skuId\":\"平台SKUID\",\"skuImg\":\"https://img.zhls.qq.com/0/SKU图片.jpg\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 6.3.14 上传图片
- 接口名
/goods/image/upload
使用场景
- 先上传图片到平台图片服务器，获取平台图片url之后，再输入到商品接口
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| url | STRING | 必填 | 外部图片URL。图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M |
- 业务请求参数示例
{
"url": "http://xxx.com/1.pic"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - url | STRING | 返回图片 url |
| - height | INTEGER | 返回图片高度 |
| - width | INTEGER | 返回图片宽度 |
| - size | INTEGER | 返回图片大小，单位:字节 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b",
"url": "https://img.zhls.qq.com/0/商品主图.jpg",
"height": 449,
"width": 600,
"size": 367252
}
}
# 6.3.15 商品属性列表查询
- 接口名
/goods/attribute/list
使用场景
- 查询商家在智慧零售侧的商品属性信息
调用方式: 回调
商家限流频次: 300次/60秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| categoryId3 | LONG | 必填 | 三级类目ID |
- 请求示例
{
"categoryId3": 509101101
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - list | ARRAY | SPU 列表 |
| -- attributeId | Long | 属性项Id |
| -- name | STRING | 属性项名称 |
| -- style | INTEGER | 属性样式：1下拉选项-单选，2选项罗列-单选，3选项罗列-多选，4文本框，5下拉选项-多选 |
| -- type | INTEGER | 属性值校验类型：-1不校验，0纯文本，1时间，2数字，3.ISBN，4图书套装 |
| -- attrItems | ARRAY | 可选属性值 （只有选项框类型的属性项才返回） |
| -- itemId | Long | 属性值ID |
| -- name | STRING | 属性值名称 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "4de57944-2f1d-4cb0-a6fd-f3bc7e7fb81e",
"list": [
{
"attributeId": 509101101001,
"name": "是否是套装",
"style": 2,
"type": 4,
"attrItems": [
{
"itemId": 5091011010011,
"name": "原版套装"
},
{
"itemId": 5091011010012,
"name": "非套装"
}
]
},
{
"attributeId": 509101101002,
"name": "出版社名称",
"style": 1,
"type": 0,
"attrItems": [
{
"itemId": 5091011010021,
"name": "北京联合出版公司"
}
]
},
{
"attributeId": 509101101003,
"name": "作者地区",
"style": 1,
"type": 0,
"attrItems": [
{
"itemId": 5091011010038,
"name": "中国大陆"
}
]
},
{
"attributeId": 509101101004,
"name": "书名",
"style": 4,
"type": 0,
"attrItems": null
},
{
"attributeId": 509101101005,
"name": "ISBN编号",
"style": 4,
"type": 3,
"attrItems": null
},
{
"attributeId": 509101101007,
"name": "页数",
"style": 4,
"type": 2,
"attrItems": null
},
{
"attributeId": 509101101009,
"name": "出版时间",
"style": 4,
"type": 1,
"attrItems": null
},
{
"attributeId": 509101101010,
"name": "作者",
"style": 4,
"type": 0,
"attrItems": null
},
{
"attributeId": 509101101012,
"name": "编者",
"style": 4,
"type": 0,
"attrItems": null
},
{
"attributeId": 509101101014,
"name": "字数",
"style": 4,
"type": 2,
"attrItems": null
}
]
}
}
# 6.4 电子面单API
# 6.4.1 已绑定账号查询
- 接口名
/waybill/account/list
使用场景：
- 获取商户全量的绑定账户信息，非必须接入
商家限流qps: 30
请求参数：无
返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - list | ARRAY | 已绑定成功的账号列表 |
| - deliverCompany | STRING | 快递公司编码 |
| - deliverCompanyName | STRING | 快递公司名称 |
| - manageType | STRING | 管理模式（DIRECT-直营 JOIN-加盟） |
| - bindCode | STRING | 绑定客户编码 |
| - balance | NUMBER | 电子面单余额（剩余单数） |
| - balanceUpdateTime | NUMBER | 账号余额更新时间（毫秒时间戳） |
| - serviceType | ARRAY | 已绑定的服务类型 |
| -- serviceType | STRING | 服务类型 |
| -- serviceName | STRING | 服务名称 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "123-234-595",
"list": [
{
"deliverCompany": "zhongtong",
"deliverCompanyName": "中通快递",
"manageType": "JOIN",
"bindCode": "客户编码",
"balance": 0,
"balanceUpdateTime": 1622736000000,
"serviceType": [
{
"serviceName": "普通快递",
"serviceType": "1"
}
]
}
]
}
}
# 6.4.2 账号单号余量查询
- 接口名
/waybill/account/balance/get
使用场景
- 获取商户单个账号单号余量查询，非必须接入
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| deliverCompany | STRING | 必填 | 物流公司编码 |
| bindCode | STRING | 必填 | 客户编码 |
- 请求示例
{
"deliverCompany": "zhongtong",
"bindCode": "客户编码"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - balance | NUMBER | 电子面单余额（剩余单数） |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "123-234-595",
"balance": 210
}
}
# 6.4.3 物流公司面单类型查询
- 接口名
/waybill/express/print/type/get
使用场景
- 查询支持的物流公司信息，非必须接入
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| deliverCompany | STRING | 必填 | 物流公司编码 |
- 请求示例
{
"deliverCompany": "zhongtong"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestIdd | STRING | 回传本次请求的 requestId |
| - printTypeInfoList | ARRAY | 快递公司支持的面单打印类型列表 |
| -- deliverCompany | STRING | 快递公司code |
| -- printTypeId | NUMBER | 面单打印类型id，用以查询面单html的printTypeId |
| -- printTypeName | STRING | 面单打印类型名称 |
| -- width | NUMBER | 宽（单位mm，可能有小数） |
| -- height | NUMBER | 高（单位mm，可能有小数） |
| -- cosUrl | STRING | 标准区cos链接（可直接访问） |
| -- editorConfig | OBJECT | 自定义区配置信息 |
| --- width | STRING | 自定义区宽（单位mm，可能有小数） |
| --- height | STRING | 自定义区高（单位mm，可能有小数） |
| --- x | STRING | 自定义区在整个面单横坐标（单位mm，可能有小数） |
| --- y | STRING | 自定义区在整个面单纵坐标（单位mm，可能有小数） |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "123-234-595",
"printTypeInfoList": [
{
"printTypeId": 3,
"printType": 0,
"width": 100.00,
"height": 180.00,
"printTypeName": "二联单 100*180",
"cosUrl": "https://waybill.lingshou.qq.com/base_template/double_form/zto_template.html",
"editorConfig": {
"width": "95.09",
"height": "30.91",
"x": "5",
"y": "149.27"
}
},
{
"printTypeId": 4,
"printType": 1,
"width": 76.00,
"height": 130.00,
"printTypeName": "一联单 76*130",
"cosUrl": "https://waybill.lingshou.qq.com/base_template/single_form/zto_template.html",
"editorConfig": {
"width": "75.95",
"height": "35.03",
"x": "0",
"y": "95.59"
}
}
]
}
}
# 6.4.4 生成电子面单（取号）
- 接口名
/waybill/data/create
- 使用场景
- 商家使用惠聚或isv电子面单模版进行复杂排版打印电子面单
其他说明
- 带*的为使用惠聚商家后台电子面单模版或者使用printOrderInfo简单指定打印样式时需要
- 使用电子面单模版进行打印时，需要按照打印组件需要的数据进行拼接后传给打印组件进行打印
- data字段数据为加密过后的json数据，需要商家先使用解密data key解密为明文json在传给打印组件
- data字段内容主要为惠聚侧电子面单模版数据，如果使用了惠聚侧电子面单模版， 需要将改字段内容使用openapi敏感数据加解密方式进行解密（可以根据场景修改部分内容信息）， 然后按照打印组件交互协议组装给到打印组件，如果使用非惠聚侧电子面单，需要根据面单模版需要的字段内容进行组装数据
- isv需要根据自己定义的模版信息拼接对应的数据，然后替换掉data字段的内容
- 使用打印模版进行打印时，
printOrderInfo字段可不传，如果传了则在打印组件没有接收到响应的自定义区模版信息时，将会使用该字段的配置进行兜底展示 - 如果用第三方订单信息进行取号并使用惠聚商家后台定义的模版进行打印，则需要传入对应的商品信息，否则打印模版对应的打印项为空
- 调用方式: 回调
- 商家限流频次: 30次/秒
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderChannel | STRING | true | 订单渠道(见下方说明) |
| thirdMerchantName* | STRING | false | 商家名称 (HJ不用传，用于展示其他渠道商家名称) |
| waybillInfo | STRING | true | 运单信息 (OBJECT转为STRING类型) |
| - openId | STRING | false | 用户openid（发送微信物流消息）, HJ渠道不用传，以惠聚订单为准 |
| - deliverCompany | STRING | true | 惠聚侧快递公司ID（调用4.1接口获取） |
| - bindCode | STRING | true | 快递客户编码或者现付编码，需先在惠聚商家后台绑定（调用4.1接口获取） |
| - sender | OBJECT | true | 地址信息（寄件人） |
| -- name | STRING | true | 发件人姓名，不超过64字节 |
| -- tel | STRING | false | 发件人座机号码，若不填写则必须填写 mobile，不超过32字节 |
| -- mobile | STRING | false | 发件人手机号码，若不填写则必须填写 tel，不超过32字节 |
| -- company | STRING | false | 发件人公司名称，不超过64字节 |
| -- postCode | STRING | false | 发件人邮编，不超过10字节 |
| -- country | STRING | false | 发件人国家，不超过64字节 |
| -- province | STRING | true | 发件人省份，比如："广东省"，不超过64字节 |
| -- city | STRING | true | 发件人市/地区，比如："广州市"，不超过64字节 |
| -- area | STRING | true | 发件人区/县，比如："海珠区"，不超过64字节 |
| -- address | STRING | true | 发件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节 |
| - receiver | OBJECT | false | 地址信息（收件人）, HJ渠道以惠聚订单数据为准，可以不传 |
| -- name | STRING | true | 收件人姓名，不超过64字节 |
| -- tel | STRING | false | 收件人座机号码，若不填写则必须填写 mobile，不超过32字节 |
| -- mobile | STRING | false | 收件人手机号码，若不填写则必须填写 tel，不超过32字节 |
| -- company | STRING | false | 收件人公司名称，不超过64字节 |
| -- postCode | STRING | false | 收件人邮编，不超过10字节 |
| -- country | STRING | false | 收件人国家，不超过64字节 |
| -- province | STRING | true | 收件人省份，比如："广东省"，不超过64字节 |
| -- city | STRING | true | 收件人市/地区，比如："广州市"，不超过64字节 |
| -- area | STRING | true | 收件人区/县，比如："海珠区"，不超过64字节 |
| -- address | STRING | true | 收件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节 |
| - cargo | OBJECT | false | 包裹信息 |
| -- weight | STRING | false | 包裹重量， 单位cm, 默认1 |
| -- spaceX | STRING | false | 包裹长， 单位cm, 默认1 |
| -- spaceY | STRING | false | 包裹宽， 单位cm, 默认1 |
| -- spaceZ | STRING | false | 包裹高， 单位cm, 默认1 |
| - insured | OBJECT | true | 保价信息（不传默认不保价） |
| -- useInsured | INTEGER | true | 是否保价，0 表示不保价，1 表示保价 |
| -- insuredValue | INTEGER | false | 保价金额，单位是分，比如: 10000 表示 100 元 |
| - service | OBJECT | true | 物流服务信息（调用4.1接口获取快递公司对应的服务类型） |
| -- serviceType | INTEGER | true | 服务类型ID |
| -- serviceName | STRING | true | 服务名称 |
| orderInfo | STRING | true | 订单信息 (List类型，需要转为STRING） |
| - orderId* | STRING | false | 订单id，（HJ订单必填） |
| - goods | ARRAY | false | 商品信息, HJ订单不填写该字段则会自动查询订单下所有商品信息,填了则只使用指定商品生成运单，其他渠道必填 |
| -- skuId* | STRING | false | 商品skuId (发货部分商品则必填) （主要用于电子面单自定义备注字段展示） |
| -- outSpuId* | STRING | false | 商家商品编码, HJ订单不用传，以惠聚侧订单数据为准（主要用于电子面单自定义备注字段展示） |
| -- name | STRING | true | 商品名, HJ订单不用传，以惠聚侧订单数据为准（用于物流通知和电子面单自定义备注区展示） |
| -- imgUrl | STRING | true | 商品缩略图url, HJ订单不用传，以惠聚侧订单数据为准（用于物流通知展示） |
| -- goodsSpec* | STRING | false | 商品规格简写, HJ订单不用传，以惠聚侧订单数据为准（电子面单自定义备注字段展示） |
| -- count | INTEGER | true | 商品数量, HJ订单不用传，以惠聚侧订单数据为准 |
| - buyerRemark* | STRING | false | 买家留言, HJ订单不用传，以惠聚侧订单数据为准（电子面单自定义备注字段展示） |
| - sellerRemark* | STRING | false | 卖家备注, HJ订单不用传，以惠聚侧订单数据为准（电子面单自定义备注字段展示） |
| printOrderInfo* | STRING | false | 打印信息配置(OBJECT转为STRING),不传默认全部false，目前该字段用于自定义区解析失败时的一个后备打印说明 |
| - printOrderId | BOOLEAN | false | 是否展示订单Id， 默认false（orderId存在才展示） |
| - printMerchantName | BOOLEAN | false | 是否展示卖家店铺名称， 默认false（其他渠道thirdMerchantName存在才展示） |
| - printGoodsSumQuantity | BOOLEAN | false | 是否展示商品总数量，订单中本次发货商品的总数量， 默认false |
| - printGoodsOutSpuId | BOOLEAN | false | 是否展示商家商品编码，订单中本次发货商品对应每个商品的编码， 默认false(其他渠道spuId存在才展示) |
| - printGoodsName | BOOLEAN | false | 是否展示商品名称， 默认false(其他渠道商品名存在才展示) |
| - printGoodsSpecification | BOOLEAN | false | 是否展示商品规格， 默认false (其他渠道商品规格简写存在才展示) |
| - printGoodsQuantity | BOOLEAN | false | 是否展示单品数量， 默认false(其他渠道商品数量存在才展示) |
| - printBuyerRemark | BOOLEAN | false | 是否展示买家留言， 默认false(其他渠道买家留言存在才展示) |
| - printSellerRemark | BOOLEAN | false | 是否展示卖家备注， 默认false(其他渠道卖家备注存在才展示) |
订单渠道
HJ（惠聚），PDD（拼多多），TB（淘宝），TM（天猫），JD（京东），ALBB（阿里巴巴），YZ（有赞），WD（微店），MGJ（蘑菇街），YJ（云集），BB（贝贝网），ZZ（转转），KS（快手小店），DD（当当网），XMYP（小米有品），SK（寺库），JM（聚美优品），MY（蜜芽），XHS（小红书），MT（萌推），WPH（唯品会），PP（拍拍），EBAY（ebay），AMAZON（亚马逊），SN（苏宁），GM（国美），YHD（1号店），VANCL（凡客），YL（邮乐），YG（优购），LF（乐蜂），JS（聚尚），PX（拍鞋），YT（银泰），OTHERS(" 其他")
请求示例
{
"orderChannel": "HJ",
"waybillInfo": "{\"deliverCompany\":\"SMS\",\"bindCode\":\"mock-bindCode\",\"sender\":{\"name\":\"张三\",\"mobile\":\"18888888888\",\"province\":\"广东省\",\"city\":\"广州市\",\"area\":\"海珠区\",\"address\":\"XX路XX号XX大厦XX\"},\"cargo\":{\"weight\":\"1\",\"spaceX\":\"1\",\"spaceY\":\"1\",\"spaceZ\":\"1\"},\"insured\":{\"useInsured\":1,\"insuredValue\":10000},\"service\":{\"serviceType\":1,\"serviceName\":\"普通\"}}",
"orderInfo": "[{\"orderId\":\"196\",\"goods\":[{\"skuId\":\"mock-12341\"}]}]",
"printOrderInfo": "{\"printOrderId\":true,\"printMerchantName\":true,\"printGoodsSumQuantity\":true,\"printGoodsOutSpuId\":true,\"printGoodsName\":true,\"printGoodsSpecification\":true,\"printGoodsQuantity\":true,\"printBuyerRemark\":true,\"printSellerRemark\":true}"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | request-id |
| - version | STRING | 请求id |
| - standard | STRING | 标准区数据（不可解密，打印组件用） |
| - data | STRING | 订单信息，（加密，可解密，打印组件用） |
| - deliverNumber | STRING | 快递单号 |
| - timestamp | LONG | 数据生成时间戳 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "xxx",
"version": "1.0",
"standard": "m5zg33==",
"data": "enc-data==",
"timestamp": 1651721604226
}
}
# 6.4.5 面单模板查询
- 接口名
/waybill/express/print/template/list
使用场景
- 查询商家在惠聚后台配置的模板，可以根据返回的模板信息调用电子面单取号接口
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| page | INTEGER | 否 | 页码（默认1，从1开始） |
| size | INTEGER | 否 | 页大小（默认50，上限50） |
- 请求示例
{
"page": 1,
"size": 50
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 请求id，用于定位请求数据 |
| -totalCount | NUMBER | 模板总数 |
| -list | ARRAY | 模板列表 |
| --id | STRING | 模板id |
| --name | STRING | 模板名称 |
| --bindExpressInfo | OBJECT | 物流账户绑定信息 |
| ---bindCode | STRING | 客户编码 |
| ---deliverCompany | STRING | 快递公司编码 |
| ---deliverCompanyName | STRING | 快递公司名称 |
| ---serviceType | ARRAY | 已绑定的服务类型 |
| ----serviceName | STRING | 服务名称 |
| ----serviceType | STRING | 服务类型 |
| --printTypeInfo | OBJECT | 打印信息配置 |
| ---printTypeId | NUMBER | 面单打印类型id，用以查询面单html的printTypeId |
| ---printType | NUMBER | 面单打印类型（0-二联单，1-一联单） |
| ---printTypeName | STRING | 面单打印类型名称 |
| ---width | NUMBER | 宽（单位mm，可能有小数） |
| ---height | NUMBER | 高（单位mm，可能有小数） |
| ---cosUrl | STRING | 标准区链接 |
| --printOrderInfo | STRING | 系统打印项-打印信息配置（自定义区打印类型为系统打印项才会返回） |
| ---printOrderId | BOOLEAN | 是否展示订单Id |
| ---printMerchantName | BOOLEAN | 是否展示卖家店铺名称 |
| ---printGoodsSumQuantity | BOOLEAN | 是否展示商品总数量，订单中本次发货商品的总数量 |
| ---printGoodsOutSpuId | BOOLEAN | 是否展示商家商品编码，订单中本次发货商品对应每个商品的编码 |
| ---printGoodsName | BOOLEAN | 是否展示商品名称 |
| ---printGoodsSpecification | BOOLEAN | 是否展示商品规格 |
| ---printGoodsQuantity | BOOLEAN | 是否展示单品数量 |
| ---printBuyerRemark | BOOLEAN | 是否展示买家留言 |
| ---printSellerRemark | BOOLEAN | 是否展示卖家备注 |
| --isDefault | BOOLEAN | 是否为默认模板 |
| --isPagination | BOOLEAN | 是否分页 |
| --customAreaPrintType | STRING | 自定义区打印类型（默认-系统打印项-SYSTEM_DEFAULT,自定义编辑模板-CUSTOM_EDIT） |
| --customAreaCosUrl | STRING | 自定义编辑模板访问链接 |
| --keys | ARRAY | 自定义编辑模板内部value列表 |
| ---key | STRING | 内部value解析后的值，具体可看实例响应结果 |
| --isvId | STRING | 自定义区绑定的服务商id |
| --isvName | STRING | 自定义区绑定的服务商名称 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "reqId",
"totalCount": 50,
"list": [
{
"name": "模板名称",
"bindExpressInfo": {
"bindCode": "客户编码",
"expressCompanyName": "中通",
"expressCompanyCode": "zhongtong",
"serviceType": [
{
"serviceName": "普通快递",
"serviceType": "1"
}
]
},
"printTypeInfo": {
"id": 1,
"printType": 0,
"printTypeName": "标准二联单 100*180mm",
"cosUrl": "标准区链接",
"width": 100,
"height": 180
},
// 打印订单信息
"printOrderInfo": {
// 订单编号
"printOrderId": false,
// 卖家店铺名称
"printMerchantName": false,
// 商品总数量：订单中本次发货商品的总数量
"printGoodsSumQuantity": false,
// 商家商品编码
"printGoodsOutSpuId": false,
// 商品名称
"printGoodsName": false,
// 商品规格
"printGoodsSpecification": false,
// 单品数量
"printGoodsQuantity": false,
// 买家留言
"printBuyerRemark": false,
// 卖家备注
"printSellerRemark": false
},
// 是否为默认模板
"isDefault": true,
// 是否分页，默认为否
"isPagination": false,
// 自定义区打印类型（默认-系统打印项-SYSTEM_DEFAULT,自定义编辑模板-CUSTOM_EDIT）
"customAreaPrintType": "CUSTOM_EDIT",
// 自定义编辑模板访问链接
"customAreaCosUrl": "",
// 自定义编辑模板内部value
"keys": [
{
// <%=data.a.goodsInfo%> 会解析成a.goodsInfo
"key": "a.goodsInfo"
}
],
// 自定义区绑定的服务商id
"isvId": "4",
// 自定义区绑定的服务商名称
"isvName": "腾讯荟聚"
}
]
}
}
# 6.4.6 物流轨迹查询
- 接口名
/express/trace/search
使用场景
- 查询商家录入物流的轨迹信息，非实时数据，非必须接入
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| deliverCompany | STRING | 必填 | 物流公司编码 |
| deliverNumber | STRING | 必填 | 快递单号 |
- 请求示例
{
"deliverCompany": "yuantong",
"deliverNumber": "YT123456789"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 请求id，用于定位请求数据 |
| -deliverCompany | STRING | 快递公司编码 |
| -deliverNumber | STRING | 快递单号 |
| -status | NUMBER | 物流状态 |
| -statusName | STRING | 物流状态中文名称 |
| -traceList | ARRAY | 轨迹列表 |
| --traceStatus | NUMBER | 轨迹状态（同物流状态） |
| --traceStatusName | STRING | 轨迹状态中文名 |
| --traceTimestamp | STRING | 轨迹时间戳，单位毫秒 |
| --detail | STRING | 轨迹详情 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"requestId": "reqId",
"deliverCompany": "yuantong",
"deliverNumber": "YT123456789",
"status": 1,
"statusName": "已揽收",
"traceList": [
{
"traceStatus": 1,
"traceStatusName": "已揽收",
"traceTimestamp": "1655195213000",
"detail": "快递已揽收"
}
]
}
}
# 6.5 打印组件API
说明
打印组件API主要为接入电子面单API打单需要接入打印组件时用到的相关API
# 6.5.1 打印组件简介
打印组件安装之后会在本地启动websocket服务
# 6.5.2 打印协议 - JSON
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| event | STRING | 是 | 事件名 |
| mod | STRING | 是 | 模块，如打印模块 print |
| type | STRING | 是 | 模块方法，如获取打印 getPrinters |
| reqId | STRING | 是 | 请求ID，客户端自己实现的uuid，因为调度的请求返回是异步，可能导致乱序，reqId 会跟随返回到客户端 |
| args | OBJECT | 否 | 方法参数 |
# 6.5.3 协议事件
- apiSuccess - 请求成功返回
- apiFail - 请求失败返回
# 6.5.4 返回模版
{
"event": "apiSuccess",
"reqId": "${request_reqId}",
// 其他信息字段
}
# 6.5.5 方法调用模版
# 6.5.5.1 初始化
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| customLog | STRING | 否 | 传入服务商对应的信息，可以附加在本地日志中【1.1.0版本以上支持】 |
| envType | INT | 否 | 1- 正式环境解密支持，0- 测试环境解密支持，默认 1 |
请求示例
{ "event": "api", "mod": "system", "type": "init", "reqId": "${uuid()}", "args": { "customLog": "logString", "envType": 1 } }
# 6.5.5.2 获取打印机列表
请求示例
{ "event": "api", "mod": "printer", "type": "getPrinters", "reqId": "${uuid()}" }
# 6.5.5.3 打印
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| printerName | STRING | 是 | 打印机名称 |
| documents | Array[document] | 是 | 面单内容（参见下表） |
| pageSize.height | INT | 是 | 打印纸张规格，高度 |
| pageSize.width | INT | 是 | 打印纸张规格，宽度 |
说明
- documents： 可以多张连打（有效提升打印流畅度），建议分批在100以内一组
- documents：由于每个任务的 pageSize 是 1对多，同一批的打印模版建议保持一致
- pageSize： 可以从 4.5 查询面单模板接口中的 printTypeInfo （width、height）获取
- document参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| customUrl | STRING | 否 | 自定义打印模版URL |
| data | Object | 否 | customUrl模版配对的数据 |
| bsAddressInfo | Object | 否 | 服务商定义寄件信息（参见下面例子） |
| standardUrl | STRING | 是 | 标准打印模版URL |
| standard | STRING | 是 | standardUrl模版配对的数据 |
| timestamp | STRING | 是 | 当前时间戳 |
| version | STRING | 是 | 填1.0 |
- 请求示例
{
"event": "api",
"mod": "printer",
"type": "print",
"reqId": "${uuid()}",
"args": {
"printerName": "PRINTER-S1(黑白)",
"documents": [
{
customUrl: 'https://waybi***.xml',
bsAddressInfo: {
// 服务商定义寄件信息
sender: {
"city": "深圳市",
"address": "科兴科学园",
"area": "南山区",
"province": "广东省",
"mobile": "12333311123",
"tel": "010-233739551",
"name": "张三"
}
},
data: {
"merchantName": "kc",
"orderId": "387046",
"goods": [
{
"skuId": "k505226582553",
"outSpuId": "1231",
"name": "测试不到阈值可以成功发布商品",
"imgUrl": "https://image.zhls.qq.com/1/0882188785174bd89ca8c19f28bfec88.png?imageMogr2/thumbnail/630x630!",
"goodsSpec": "1",
"count": 1
}
],
"totalCount": 1,
"buyerRemark": "",
"sellerRemark": ""
},
standard: "${api返回数据}",
// jSKE+GRDEyP+Jaat/F2EnVSbcJZhoZM13EKq+OUWJJEVt3ZRl8=
standardUrl: 'https://waybill.lin***mplate.html',
timestamp: 1651804964854,
version: "1.0"
}
],
"pageSize": {
"height": 180,
"width": 100
}
}
}
# 7. O2O商家专用API列表
# 7.1 商家门店API
# 7.1.1 查询城市列表
- 接口名
/merchant/subStore/city/getCityList
使用场景
- 查询腾讯荟聚门店支持的城市列表
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| code | INTEGER | 非必填 | 不传区域编码查全量城市信息列表，传区域编码查询对应子城市信息列表 |
- 请求示例
{
"code":139002
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | INTEGER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - items | ARRAY | 城市 列表 |
| - provName | STRING | 省名称 |
| - provCode | INTEGER | 省编码 |
| - cityName | STRING | 市名称 |
| - cityCode | INTEGER | 市编码 |
| - countyName | STRING | 区县名称 |
| - countyCode | INTEGER | 区县编码 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "11111111",
"items": [
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "辛集镇",
"countyCode": 139002100
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "旧城镇",
"countyCode": 139002101
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "张古庄镇",
"countyCode": 139002102
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "位伯镇",
"countyCode": 139002103
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "新垒头镇",
"countyCode": 139002104
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "新城镇",
"countyCode": 139002105
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "南智邱镇",
"countyCode": 139002106
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "王口镇",
"countyCode": 139002107
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "天宫营乡",
"countyCode": 139002200
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "前营乡",
"countyCode": 139002201
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "马庄乡",
"countyCode": 139002202
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "和睦井乡",
"countyCode": 139002203
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "田家庄乡",
"countyCode": 139002204
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "中里厢乡",
"countyCode": 139002205
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "小辛庄乡",
"countyCode": 139002206
},
{
"provName": "河北省",
"provCode": 130000,
"cityName": "辛集市",
"cityCode": 139002,
"countyName": "辛集经济开发区",
"countyCode": 139002500
}
]
}
}
# 7.1.2 商家创建门店
- 接口名
/merchant/subStore/create
使用场景
- 商家门店入驻腾讯荟聚创建门店
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreName | STRING | 必填 | 商家门店：门店名称不能超过13个字 |
| extSubStoreId | STRING | 非必填 | 商家自定义编码 |
| mobilePhone | STRING | 非必填 | 门店手机号码，其中座机和手机两者必填一个 |
| telePhone | STRING | 非必填 | 门店座机号码，其中座机和手机两者必填一个 |
| provCode | INTEGER | 必填 | 省编码 |
| cityCode | INTEGER | 必填 | 城编码 |
| countyCode | INTEGER | 必填 | 区县编码 |
| photos | STRING | 必填 | 门店门头照片地址-JSON数组 |
| address | STRING | 必填 | 门店地址 |
| openTimes | STRING | 必填 | 营业时间-JSON数组 |
| -openBeginTime | LONG | 必填 | 营业开始时间 |
| -openEndTime | LONG | 必填 | 营业结束时间 |
| longitude | DOUBLE | 必填 | 门店经度 |
| latitude | DOUBLE | 必填 | 门店纬度 |
| bulletin | STRING | 非必填 | 门店公告 |
| remark | STRING | 非必填 | 门店备注 |
| subStoreDeliveryAreas | STRING | 必填 | 配送范围-JSON数组 |
| -rangeType | INTEGER | 必填 | 配送范围类型：1： 半径类型 2：电子围栏 |
| -mapType | INTEGER | 必填 | 地图类型：1:腾讯地图 2：高德地图 3：百度地图 |
| -rangeRadius | INTEGER | 非必填 | 单位米，配送范围类型为1，服务配送半径必填 |
| -coordinatePoints | STRING | 非必填 | 配送范围类型为2，电子围栏坐标必填，不规则多边形，此字段必填每个点以英文;隔开 |
- 请求示例
{
"subStoreName": "腾讯荟聚门店",
"extSubStoreId": "HJ123",
"mobilePhone": "18122329811",
"telePhone": "020-43198888",
"provCode": 110000,
"cityCode": 110100,
"countyCode": 110101,
"photos":"[\"http://srcode\"]",
"address": "腾讯滨海大厦",
"openTimes":"[{\"openBeginTime\":40689000,\"openEndTime\":40789000}]",
"longitude": 10.0,
"latitude": 10.0,
"bulletin": "营业开始",
"remark": "测试",
"subStoreDeliveryAreas": "[{\"rangeType\":1,\"mapType\":1,\"rangeRadius\":100,\"coordinatePoints\":coordinatePoints\"\"}]",
"requestId": "lQOeKjv5-5yjD-4mTR-2k56-AQ2fbDZ7P3ik",
"merchantId": "E95281",
"version": "v1.6.0",
"versionCode": 1
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - subStoreId | STRING | 门店标识 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "lQOeKjv5-5yjD-4mTR-2k56-AQ2fbDZ7P3ik",
"subStoreId": "VJm1D4Y7Q9V"
}
}
# 7.1.3 修改商家门店
- 接口名
/merchant/subStore/update
使用场景
- 商家修改门店基础信息
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 必填 | 门店标识 |
| subStoreName | STRING | 非必填 | 商家门店：门店名称不能超过13个字 |
| extSubStoreId | STRING | 非必填 | 商家自定义编码 |
| photos | ARRAY | 非必填 | 门店门头地址 |
| mobilePhone | STRING | 非必填 | 门店手机号码，其中座机和手机两者必填一个 |
| telePhone | STRING | 非必填 | 门店座机号码，其中座机和手机两者必填一个 |
| provCode | INTEGER | 非必填 | 省编码 |
| cityCode | INTEGER | 非必填 | 城编码 |
| countyCode | INTEGER | 非必填 | 区县编码 |
| address | STRING | 非必填 | 门店地址 |
| openTimes | STRING | 非必填 | 营业时间 JSON数组字符串 |
| -openBeginTime | LONG | 必填 | 营业开始时间 |
| -openEndTime | LONG | 必填 | 营业结束时间 |
| longitude | DOUBLE | 非必填 | 门店经度 |
| latitude | DOUBLE | 非必填 | 门店纬度必填 |
| openState | INTEGER | 非必填 | 门店营业状态：1-正常营业 2-闭店 3-打烊 |
| bulletin | STRING | 非必填 | 门店公告 |
| remark | STRING | 非必填 | 门店备注 |
| subStoreDeliveryAreas | STRING | 非必填 | 配送范围 JSON数组字符串 |
| -rangeType | INTEGER | 必填 | 配送范围类型：1： 半径类型 2：电子围栏 |
| -mapType | INTEGER | 必填 | 地图类型：枚举值待定 |
| -rangeRadius | INTEGER | 必填 | 单位米，配送范围类型为1，服务配送半径必填 |
| -coordinatePoints | STRING | 必填 | 配送范围类型为2，电子围栏坐标必填，不规则多边形，此字段必填每个点以英文;隔开 |
- 请求示例
{
"subStoreId": "Kz3d7A5gRmv",
"subStoreName": "测试门店",
"extSubStoreId": "1111",
"mobilePhone": "18122329825",
"telePhone": "18122329825",
"photos":"[\"http://11111\"]",
"provCode": 110000,
"cityCode": 110100,
"countyCode": 110101,
"address": "深圳科兴",
"longitude": 10.0,
"latitude": 10.0,
"subStoreDeliveryAreas": "[{\"rangeType\":1,\"mapType\":1,\"rangeRadius\":100,\"coordinatePoints\":coordinatePoints\"\"}]",
"openTimes":"[{\"openBeginTime\":40689000,\"openEndTime\":40789000}]",
"bulletin": "测试",
"remark": "测试",
"requestId": "lQOeKjv5-5yjD-4mTR-2k56-AQ2fbDZ7P3ik",
"merchantId": "E95281",
"version": "v1.6.0",
"versionCode": 1
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820"
}
}
# 7.1.4 提交门店资质
- 接口名
/merchant/subStore/submitQualify
使用场景
提交入驻门店的资质信息
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 必填 | 门店标识 |
| categories | STRING | 必填 | 类目-JSON数组字符串 |
| - bigCategoryId | LONG | 必填 | 品牌大类 |
| - categoryId1 | LONG | 非必填 | 一级类目 |
| - categoryId2 | LONG | 非必填 | 二级类目 |
| - categoryId3 | LONG | 非必填 | 三级类目 |
| busiLicenses | STRING | 必填 | 营业执照 JSON数组字符串 |
| - licenseUrl | STRING | 必填 | 营业执照上传路径地址 |
| - legalPerson | STRING | 必填 | 企业法人名称 |
| - licenseNumber | STRING | 必填 | 营业执照编码 |
| - licenseType | INTEGER | 必填 | 营业执照类型枚举1:营业执照 |
| - companyName | STRING | 必填 | 公司名称 |
| - address | STRING | 必填 | 公司地址 |
| - validityStart | LONG | 必填 | 营业执照有效开始时间 |
| - validityEnd | LONG | 必填 | 营业执照有效结束时间 |
| - registerCapitalNum | LONG | 非必填 | 注册资本 |
| permitLicenses | STRING | 必填 | 经营许可证-JSON数组字符串 |
| - licenseUrl | STRING | 必填 | 许可证上传路径地址 |
| - qualificationId | INTEGER | 必填 | 许可证类型不可为空，填写门店需要上传资质标识 |
| - licenseNumber | STRING | 非必填 | 营业执照编码 |
| - validityStart | LONG | 非必填 | 营业执照有效开始时间 |
| - validityEnd | LONG | 非必填 | 营业执照有效结束时间 |
| legalPersons | STRING | 必填 | 企业法人-JSON数组字符串 |
| - idNumber | STRING | 必填 | 身份证编码 |
| - name | STRING | 必填 | 法人名称 |
| - frontUrl | STRING | 必填 | 身份证头像面图片 |
| - backUrl | STRING | 必填 | 身份证背面图片 |
| - validityStart | LONG | 非必填 | 营业执照有效开始时间 |
| - validityEnd | LONG | 非必填 | 营业执照有效结束时间 |
| managers | STRING | 必填 | 门店负责人-JSON数组字符串 |
| - idNumber | STRING | 必填 | 身份证编码 |
| - managerName | STRING | 必填 | 门店负责人名称 |
| STRING | 必填 | 邮箱 | |
| - frontUrl | STRING | 必填 | 身份证头像面图片 |
| - backUrl | STRING | 必填 | 身份证背面图片 |
| - validityStart | LONG | 非必填 | 营业执照有效开始时间 |
| - validityEnd | LONG | 非必填 | 营业执照有效结束时间 |
| authLetters | STRING | 必填 | 门店经营授权书-JSON数组字符串 |
| - authLetterUrls | ARRAY | 必填 | 数组链接地址 |
| - validityStart | LONG | 非必填 | 营业执照有效开始时间 |
| - validityEnd | LONG | 非必填 | 营业执照有效结束时间 |
- 请求示例
{
"subStoreId": "xnaNzWDzp4w",
"busiLicenses":"[{\"licenseUrls\":[\"http://11111\"],\"legalPerson\":\"张欣\",\"licenseNumber\":\"12121\",\"licenseType\":1,\"companyName\":\"腾讯\",\"address\":\"科兴\",\"validityStart\":1644478434000,\"validityEnd\":1644564834000,\"registerCapitalNum\":0}]",
"permitLicenses":"[{\"licenseUrls\":[\"http://11111\"],\"qualificationId\":39,\"validityStart\":1644478434000,\"validityEnd\":1644564834000},{\"licenseUrls\":[\"http://11111\"],\"qualificationId\":65,\"validityStart\":1644478434000,\"validityEnd\":1644564834000}]",
"legalPersons":"[{\"idNumber\":\"4201110292920\",\"name\":\"张欣\",\"frontUrl\":\"http://***\",\"backUrl\":\"http://***\",\"validityStart\":1644478434000,\"validityEnd\":1644564834000}]",
"managers":"[{\"idNumber\":\"4201110292920\",\"managerName\":\"测试\",\"email\":\"418367716@qq.com\",\"mobileNumber\":\"1812221211\",\"frontUrl\":\"http://***\",\"backUrl\":\"http://***\",\"validityStart\":1644478434000,\"validityEnd\":1644564834000}]",
"authLetters":"[{\"authLetterUrls\":[\"http://***\",\"http://***\"],\"validityStart\":1644478434000,\"validityEnd\":1644564834000}]",
"categories":"[{\"bigCategoryId\":1034,\"categoryId1\":106,\"categoryId2\":106121,\"categoryId3\":106121294}]",
"requestId": "282882910sdjjs0193901820",
"merchantId": "E95281",
"version": "v1.6.0",
"versionCode": 1.0
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820"
}
}
# 7.1.5 查询门店资质审核状态
- 接口名
/merchant/subStore/qryQualifyApplyState
- 使用场景 1：查询入驻门店资质审核状态
- 调用方式: 回调
- 商家限流频次: 30次/秒
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 必填 | 门店标识 |
- 请求示例
{
"subStoreId": "QGWDpPBoan9"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 流水标识 |
| - subStoreWorkFlowItems | ARRAY | 门店审核状态 |
| -workFlowId | STRING | 流程标识 |
| -merchantId | STRING | 商家标识 |
| -subStoreId | STRING | 门店标识 |
| -extSubStoreId | STRING | 外部门店标识 |
| -subStoreName | STRING | 门店名称 |
| -auditReason | STRING | 审核原因 |
| -auditTime | LONG | 审核时间 |
| -createTime | LONG | 创建时间 |
| -auditState | INTEGER | 审核状态：1-未提交门店资质 2-待平台初审 3-待平台复审 4-审核通过 5-审核驳回 6-复审驳回 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820",
"subStoreWorkFlowItems": [
{
"workFlowId": 32,
"merchantId": "E95281",
"subStoreId": "VJm9mg20nbg",
"extSubStoreId": "1111",
"subStoreName": "测试1111",
"auditState": 2,
"auditReason": "",
"createTime": 1645173860000,
"auditTime": 1645173861000
}
]
}
}
# 7.1.6 查询门店详情
- 接口名
/merchant/subStore/getSubStoreDetail
使用场景 1；查询门店基础信息
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 必填 | 门店标识 |
- 请求示例
{
"subStoreId": "QGWDpPBoan9"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 流水编码 |
| -subStoreDetail | OBJECT | 门店详情 |
| -merchantId | STRING | 商家编码 |
| -merchantName | STRING | 商家名称 |
| -subStoreId | STRING | 门店编码 |
| -subStoreName | STRING | 门店名称 |
| -photos | ARRARY | 门店照片 |
| -extSubStoreId | STRING | 外部门店编码 |
| -mobilePhone | STRING | 手机号码 |
| -telePhone | STRING | 电话号码 |
| -provCode | INTEGER | 省编码 |
| -provName | STRING | 省名称 |
| -cityCode | INTEGER | 城市编码 |
| -cityName | STRING | 城市名称 |
| -countyCode | INTEGER | 区县编码 |
| -countyName | STRING | 区县名称 |
| -address | STRING | 门店地址 |
| -longitude | DOUBLE | 经度 |
| -latitude | DOUBLE | 纬度 |
| -openState | INTEGER | 门店状态：1-营业 2-关门 3-打烊 |
| -activeState | INTEGER | 门店启用状态：1-启用 2-禁用 |
| -auditState | INTEGER | 1-未提交门店资质 2-待平台初审 3-待平台复审 4-审核通过 5-审核驳回 6-复审驳回 |
| -bulletin | STRING | 公告 |
| -remark | STRING | 备注 |
| -openTimes | ARRAY | 营业时间 |
| -openBeginTime | LONG | 营业开始时间 |
| -openEndTime | LONG | 营业结束时间 |
| -deliveryAreas | ARRAY | 配送范围 |
| -rangeType | INTEGER | 配送范围类型：1： 半径类型 2：电子围栏 |
| -mapType | INTEGER | 地图类型同创建门店 |
| -rangeRadius | INTEGER | 单位米 |
| -coordinatePoints | STRING | 电子围栏坐标 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820",
"subStoreDetail": {
"merchantId": "E95281",
"merchantName": "内测商家",
"subStoreId": "xnaNzWDzp4w",
"subStoreName": "欣测试门店创建",
"photos": [
"http://11111"
],
"extSubStoreId": "1111",
"mobilePhone": "18122329825",
"telePhone": "18122329825",
"provCode": 110000,
"provName": "北京市",
"cityCode": 110100,
"cityName": "北京市",
"countyCode": 110101,
"countyName": "东城区",
"address": "深圳科兴",
"longitude": 10.0,
"latitude": 10.0,
"openState": 2,
"activeState": 2,
"auditState": 2,
"bulletin": "测试",
"remark": "测试",
"openTimes": [
{
"openBeginTime": 40689000,
"openEndTime": 40789000
},
{
"openBeginTime": 40889000,
"openEndTime": 40989000
}
],
"deliveryAreas": [
{
"rangeType": 1,
"mapType": 1,
"rangeRadius": 100,
"coordinatePoints": null
}
]
}
}
}
# 7.1.7 分页查询门店列表
- 接口名
/merchant/subStore/getSubStorePage
使用场景
分页查询门店列表
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 非必填 | 门店标识 |
| subStoreName | STRING | 非必填 | 店铺名称模糊查询 |
| licenseAuditState | INTEGER | 非必填 | 资质审核状态 |
| openState | INTEGER | 非必填 | 营业状态 |
| activeState | INTEGER | 非必填 | 门店启用状态 |
| pageNo | INTEGER | 非必填 | 页数 |
| pageSize | INTEGER | 非必填 | 页码 |
- 请求示例
{
"merchantId": "E95281"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 流水编码 |
| -subStoreItems | ARRAY | 门店列表 |
| -subStoreId | STRING | 门店标识 |
| -merchantId | STRING | 商家标识 |
| -extSubStoreId | STRING | 外门门店标识 |
| -subStoreName | STRING | 门店名称 |
| -openState | INTEGER | 门店状态：1-营业 2-关门 3-打烊 |
| -activeState | INTEGER | 门店启用状态：1-启用 2-禁用 |
| -auditState | INTEGER | 1-未提交门店资质 2-待平台初审 3-待平台复审 4-审核通过 5-审核驳回 6-复审驳回 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820",
"pageNo": 1,
"pageSize": 10,
"subStoreItems": [
{
"subStoreId": "Kz3DZ84pYN2",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "测试门店我的",
"openState": 1,
"activeState": 2,
"auditState": null
},
{
"subStoreId": "p2Mvd5QvWJB",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "修改修改",
"openState": 1,
"activeState": 2,
"auditState": null
},
{
"subStoreId": "zpdv3En421O",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "测试门店我的我的我的我的",
"openState": 1,
"activeState": 2,
"auditState": null
}
]
}
}
# 7.1.8 批量查询门店列表
- 接口名
/merchant/subStore/batchGetSubStoreList
使用场景
分页查询门店列表
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreIds | Arrary | 必填 | 门店标识列表 |
- 请求示例
{
"subStoreIds": ["HJ001"]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 流水编码 |
| -subStoreItems | ARRAY | 门店列表 |
| -subStoreId | STRING | 门店标识 |
| -merchantId | STRING | 商家标识 |
| -extSubStoreId | STRING | 外门门店标识 |
| -subStoreName | STRING | 门店名称 |
| -openState | INTEGER | 门店状态：1-营业 2-关门 3-打烊 |
| -activeState | INTEGER | 门店启用状态：1-启用 2-禁用 |
| -auditState | INTEGER | 1-未提交门店资质 2-待平台初审 3-待平台复审 4-审核通过 5-审核驳回 6-复审驳回 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820",
"subStoreItems": [
{
"subStoreId": "Kz3DZ84pYN2",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "测试门店我的",
"openState": 1,
"activeState": 2,
"auditState": null
},
{
"subStoreId": "p2Mvd5QvWJB",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "修改修改",
"openState": 1,
"activeState": 2,
"auditState": null
},
{
"subStoreId": "zpdv3En421O",
"merchantId": "E95281",
"extSubStoreId": "ext-1232222",
"subStoreName": "测试门店我的我的我的我的",
"openState": 1,
"activeState": 2,
"auditState": null
}
]
}
}
# 7.1.9 查询商家资质类目
- 接口名
/merchant/subStore/getMerchantCategory
使用场景
查询商家资质类目
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| merchantId | STRING | 必填 | 商家标识 |
- 请求示例
{
"merchantId": "E95281"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -requestId | STRING | 流水编码 |
| -merchantCategoryItems | ARRAY | 门店列表 |
| - type | INTEGER | 资质类型 |
| - bigCategoryId | LONG | 资质大类标识 |
| - bigCategoryName | STRING | 资质大类名称 |
| - categoryId1 | LONG | 一级类目 |
| - categoryId1Name | STRING | 一级类目名称 |
| - categoryId2 | LONG | 二级类目 |
| - categoryId2Name | STRING | 二级类目名称 |
| - categoryId3 | LONG | 三级类目 |
| - categoryId3Name | STRING | 三级类目名称 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "282882910sdjjs0193901820",
"merchantCategoryItems": [
{
"type": 1,
"bigCategoryId": 1034,
"bigCategoryName": "图书文娱",
"categoryId1": 106,
"categoryId1Name": "图书",
"categoryId2": 106121,
"categoryId2Name": "中小学教辅",
"categoryId3": 106121294,
"categoryId3Name": "中小学作文辅导"
}
]
}
}
# 7.1.10 查询入驻门店所需经营许可证
- 接口名
/merchant/subStore/getMerchantCategoryQualify
使用场景
查询商家所需经营许可证
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| categoryId3s | ARRARY | 必填 | 三级类目标识 |
- 请求示例
{
"categoryId3s": [
"106121294"
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 流水编码 |
| - MerchantCategoryQualifyItems | ARRAY | 资质列表 |
| - qualificationId | LONG | 资质标识 |
| -qualificationName | STRING | 资质名称 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"MerchantCategoryQualifyItems": [
{
"qualificationId": 1,
"qualificationName": "第三方权威机构出具的商品检测报告"
},
{
"qualificationId": 2,
"qualificationName": "中华人民共和国进口货物报关单"
},
{
"qualificationId": 39,
"qualificationName": "入驻主体的《出版物经营许可证》"
},
{
"qualificationId": 65,
"qualificationName": "入驻主体的《图书出版许可证》"
}
],
"requestId": "louisxzhang"
}
}
# 7.1.11 查询门店资质
- 接口名
/merchant/subStore/getSubStoreQualifyDetail
使用场景
查询门店资质
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreId | STRING | 必填 | 门店标识 |
- 请求示例
{
"subStoreId": "QGWDpPBoan9"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 流水编码 |
| -categories | ARRAY | 必填 |
| - bigCategoryId | LONG | 品牌大类 |
| - categoryId1 | LONG | 一级类目 |
| - categoryId2 | LONG | 二级类目 |
| - categoryId3 | LONG | 三级类目 |
| -busiLicenses | ARRAY | 营业执照 |
| - busiLicenseId | LONG | 资质标识 |
| - licenseUrl | STRING | 营业执照上传路径地址 |
| - legalPerson | STRING | 企业法人名称 |
| - licenseNumber | STRING | 营业执照编码 |
| - licenseType | INTEGER | 营业执照类型枚举值待定 |
| - companyName | STRING | 公司名称 |
| - address | STRING | 公司地址 |
| - validityStart | LONG | 营业执照有效开始时间 |
| - validityEnd | LONG | 营业执照有效结束时间 |
| - registerCapitalNum | LONG | 注册资本 |
| - state | INTEGER | 状态 |
| -permitLicenses | ARRAY | 经营许可证 |
| - permitLicenseId | LONG | 经营许可证标识 |
| - qualificationId | LONG | 资质标识 |
| - licenseUrl | STRING | 许可证上传路径地址 |
| - licenseNumber | STRING | 许可证编码 |
| - qualificationId | INTEGER | 许可证类型不可为空 |
| - validityStart | LONG | 营业执照有效开始时间 |
| - validityEnd | LONG | 营业执照有效结束时间 |
| - state | INTEGER | 状态 |
| -legalPersons | ARRAY | 企业法人 |
| - legalPersonId | LONG | 企业法人标识 |
| - idNumber | STRING | 身份证编码 |
| - name | STRING | 法人名称 |
| - frontUrl | STRING | 身份证头像面图片 |
| - backUrl | STRING | 身份证背面图片 |
| - validityStart | LONG | 营业执照有效开始时间 |
| - validityEnd | LONG | 营业执照有效结束时间 |
| - state | INTEGER | 状态 |
| -managers | ARRAY | 门店负责人 |
| - managerId | LONG | 门店负责人标识 |
| - idNumber | STRING | 身份证编码 |
| - managerName | STRING | 门店负责人名称 |
| - frontUrl | STRING | 身份证头像面图片 |
| - backUrl | STRING | 身份证背面图片 |
| - validityStart | LONG | 营业执照有效开始时间 |
| - validityEnd | LONG | 营业执照有效结束时间 |
| - state | INTEGER | 状态 |
| -authLetters | ARRAY | 门店经营授权书 |
| - authLetterId | LONG | 门店授权书标识 |
| - authLetterUrls | ARRAY | 数组线程传链接 |
| - validityStart | LONG | 营业执照有效开始时间 |
| - validityEnd | LONG | 营业执照有效结束时间 |
| - state | INTEGER | 状态 |
- 返回示例
# 7.1.12 上传图片
- 接口名
/goods/image/watermark
使用场景 1：上传门店图片，支持按照链接和Base64两种方式上传， 上传图片方式：需要上传图片到平台图片服务器，获取平台图片url之后，再输入到接口
调用方式: 回调
商家限流频次: 30次/秒
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| merchantId | STRING | 必填 | 商家标识 |
| requestId | string | 必填 | 请求流水标识 |
| fileBase64 | string | 非必填 | fileBase64 filename 为直接上传文件时传 |
| filename | string | 非必填 | 文件名称 |
| url | STRING | 非必填 | 图片地址 |
- 请求示例
{
"url": "",
"merchantId": "",
"requestId": "",
"fileBase64": "",
"filename": ""
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| ----- | ----- | ----- |
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
- 返回示例
# 7.2 商品API
# 7.2.1 门店商品列表查询
- 接口名
/goods/arrive/spu/list
- 使用场景：查询商家在智慧零售侧的门店商品信息
- 调用方式: 回调
- 商家限流qps: 120
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuIds | STRING | 非必填 | 平台 SPU ID，支持多个，用逗号隔开，最多20个 |
| outSpuIds | STRING | 非必填 | 商家 SPU 编码，支持多个，用逗号隔开，最多20个 |
| subStoreIds | STRING | 非必填 | 门店ID，支持多个，用逗号隔开，最多20个 |
| state | INTEGER | 非必填 | 状态(1 待上架, 2 在售中，3 已售罄，4 已下架， 5 审核中， 6 审核失败) |
| updateBegin | LONG | 非必填 | 更新时间-起始。大于等于。毫秒时间戳。 |
| updateEnd | LONG | 非必填 | 更新时间-止于。小于等于。毫秒时间戳。 |
| pageNum | INTEGER | 非必填 | 页码，默认1 |
| pageSize | INTEGER | 非必填 | 每页大小，默认15，最大100 |
- 请求示例
{
"spuIds": "xxx1,xxx2",
"outSpuIds": "xx1",
"state": 1,
"updateBegin": 1603714767000,
"updateEnd": 1603714867000,
"pageNum": 2,
"pageSize": 20
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - total | INTEGER | 总数 |
| - spuList | ARRAY | SPU 列表 |
| -- spuId | STRING | 平台 SPU ID |
| -- outSpuId | STRING | 商家 SPU 编码 |
| -- merchantId | STRING | 商家 ID |
| -- subStoreId | STRING | 门店 ID |
| -- name | STRING | 商品名称 |
| -- brandId | NUMBER | 品牌 ID |
| -- brandName | STRING | 品牌名称 |
| -- spuImg | STRING | 商品主图 |
| -- carousel | STRING | 商品轮播图 |
| -- content | STRING | 商品详情图 |
| -- marketPrice | INTEGER | 商品吊牌价（分为单位） |
| -- referencePrice | INTEGER | 商品市场参考价（分为单位） |
| -- categoryId1 | NUMBER | 一级类目 ID |
| -- categoryName1 | STRING | 一级类目名称 |
| -- categoryId2 | NUMBER | 二级类目 ID |
| -- categoryName2 | STRING | 二级类目名称 |
| -- categoryId3 | NUMBER | 三级类目 ID |
| -- categoryName3 | STRING | 三级类目名称 |
| -- reduceType | INTEGER | 库存计件（1 用户下单减库存，2 用户付款减库存 ） |
| -- weight | INTEGER | 物流重量（含包装），单位克 |
| -- state | NUMBER | 状态(1 待上架, 2 在售中，3 已售罄，4 已下架， 5 审核中， 6 审核失败) |
| -- updateTime | LONG | 更新时间（毫秒时间戳） |
| -- createTime | LONG | 创建时间（毫秒时间戳） |
| -- limitCount | INTEGER | 商品限购数量（1-10000）0或null不限购 |
| -- skuList | ARRAY | SKU 列表 |
| --- skuId | STRING | 平台 SKU ID |
| --- outSkuId | STRING | 商家 SKU 编码 |
| --- barCode | STRING | 条形码 |
| --- skuImg | STRING | SKU 图片 |
| --- styles1 | STRING | 规格1 |
| --- styles1name | STRING | 规格1名称 |
| --- styles2 | STRING | 规格2 |
| --- styles2name | STRING | 规格2名称 |
| --- settlementPrice | NUMBER | 结算价（分为单位） |
| --- state | STRING | 状态（1上架，2下架） |
| --- marketPrice | NUMBER | 划线价/吊牌价（分为单位） |
| --- marketPriceCertificate | STRING | 划线价/吊牌价凭证 |
| --- referencePrice | NUMBER | 参考价 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "回传的RequestId",
"total": 50,
"spuList": [
{
"spuId": "平台 SPU ID",
"outSpuId": "商家 SPU 编码",
"merchantId": "商家 ID",
"subStoreId": "门店 ID",
"name": "商品名称",
"brandId": 1,
"brandName": "品牌名称",
"spuImg": "https://img.zhls.qq.com/0/商品主图.jpg",
"carousel": ["https://img.zhls.qq.com/1/商品轮播图.jpg"],
"content": ["https://img.zhls.qq.com/1/商品详情图1.jpg"],
"marketPrice": 700,
"referencePrice": 700,
"categoryId1": 122,
"categoryName1": "服饰内衣",
"categoryId2": 122205,
"categoryName2": "女装",
"categoryId3": 122205989,
"categoryName3": "仿皮皮衣",
"reduceType": 1,
"weight": 21000,
"state": 4,
"updateTime": 1603714867000,
"createTime": 1603710891000,
"skuList": [
{
"skuId": "平台 SKU ID",
"outSkuId": "商家 SKU 编码",
"barCode": "SKU 条形码",
"skuImg": "https://img.zhls.qq.com/0/SKU图片.jpg",
"styles1": "尺寸",
"styles1name": "203*230CM",
"styles2": "颜色",
"styles2name": "粉",
"settlementPrice": 100,
"marketPrice": 100,
"marketPriceCertificate": "https://img.zhls.qq.com/0/SKU图片.jpg",
"referencePrice": 200,
"state": 1
}
]
}
]
}
}
# 7.2.2 门店SPU(包括SKU)新增
- 接口名
/goods/arrive/spu/add
使用场景
- 新增 spu
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| version | STRING | 非必填 | 默认v1.6.0, 参考版本编号 |
| outSpuId | STRING | 必填 | 商家商品编码。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| name | STRING | 必填 | 商品名称。最多输入60个字。 |
| brandId | Long | 必填 | 品牌 ID。通过【品牌查询接口】获取到商家可设置的品牌ID |
| categoryId | LONG | 必填 | 叶子类目 ID（三级类目 ID）。通过【类目查询接口】获取到商家可设置的类目，并取三级类目 ID |
| reduceType | INTEGER | 必填 | 库存计件（1 用户下单减库存，2 用户付款减库存 ）。现阶段暂只支持 1 |
| weight | INTEGER | 必填 | 物流重量（含包装），单位克。大于等于0.01千克，小于等于999千克。 |
| carousel | STRING | 必填 | 商品轮播图。最多5张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG，第一张商品图片默认为商品主图；图片尺寸长宽比1：1且单张图片大小不超过2M，建议尺寸为800px*800px；图片url不要带参数；需要将 OBJECT[] 类型转为 STRING 类型的 JSON 字符串 |
| content | STRING | 必填 | 商品详情图。最多30张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M，图片宽度建议750px；图片url不要带参数；需要将 OBJECT[] 类型转为 STRING 类型的 JSON 字符串 |
| skuList | STRING | 必填 | sku 对象列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - style1TemplateId | NUMBER | 必填 | 规格1模版id。可输入值：通过【规格查询接口】查询 |
| - style1name | STRING | 必填 | 规格1名称。规格名称不超过40个字； |
| - style2TemplateId | NUMBER | 非必填 | 规格2模版id。规格1已经选择的规格值，规格2不能再次选择； |
| - style2name | STRING | 非必填 | 规格2名称。上述规格2有值，则规格2名称为必填；规格名称不超过40个字；说明：在规格1、规格2都有值的情况下，需要按所需的【规格1，规格2】组合传入SKU，系统不会通过笛卡尔乘积自动组合；比如：规格1为：黑色、白色；规格2为：L、M；可只传入组合为：【黑色，L】、【白色，M】； |
| - outSkuId | STRING | 必填 | 商家 SKU 编码。商家自身判断商品sku的唯一标识，sku维度。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - barCode | STRING | 非必填 | 条形码。不能为0。仅能包含：字母、数字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - skuImg | STRING | 非必填 | SKU 图片。通过【图片上传接口】上传。图片长宽比1:1，大小不超过2M；建议尺寸为：350px*350px；图片url不要带参数； |
| - settlementPrice | NUMBER | 必填 | 结算价（分为单位）。大于0。小于等于SPU吊牌价。指智慧零售与商家协商，商品销售后，需要结算给商家的价格； |
| - marketPrice | NUMBER | 必填 | 划线价/吊牌价（分为单位）。大于0。大于等于SKU结算。 |
| - marketPriceCertificate | STRING | 必填 | 划线价/吊牌价凭证，吊牌价大于等于2倍的SKU结算价时，必须填写 |
| - referencePrice | NUMBER | 非必填 | 参考价, 选填 |
| - state | INTEGER | 必填 | 状态（1上架，2下架） |
| shipPledgeHours | INTEGER | 非必填 | 商品发货时间承诺（小时为单位）。默认值72，可选值72,120,168,240,360,720,1440 |
| whiteImage | STRING | 必填 | 商品白底图。图片必须为纯白底，图片长宽比要求为1:1，单张图片大小不能大于2M，建议图片尺寸为800*800像素，无logo、无水印，建议将素材抠图、边缘处理干净 |
| limitCount | INTEGER | 非必填 | 商品限购数量。大于0，小于等于10000 |
| attrList | STRING | 必填 | v1.7.5以上版本支持，属性列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - attributeId | NUMBER | 必填 | 属性项ID；可输入值：通过【属性项列表查询接口】查询 |
| - attrItems | ARRAY | 非必填 | 单/多选时，选中的属性值ID(itemId)的列表 |
| - attrValue | STRING | 非必填 | 输入框时。填写的属性值； |
- 业务请求参数示例
{
"version": "v1.7.5",
"outSpuId": "商家 SPU 编码",
"name": "商品名称",
"brandId": 1,
"categoryId": 122,
"marketPrice": 700,
"referencePrice": 700,
"reduceType": 1,
"weight": 21000,
"carousel": "[\"https://img.zhls.qq.com/1/商品轮播图.jpg\"]",
"content": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]",
"skuList": "[{\"outSkuId\":\"商家SKU编码\",\"barCode\":\"SKU条形码\",\"skuImg\":\"https://img.zhls.qq.com/0/SKU图片.jpg\",\"style1TemplateId\":1,\"style1name\":\"203*230CM\",\"style2TemplateId\":2,\"style2name\":\"粉\",\"settlementPrice\":100,\"state\":1,\"marketPrice\":100,\"marketPriceCertificate\":\"https://img.zhls.qq.com/1/吊牌价凭证.jpg\"}]",
"whiteImage": "https://img.zhls.qq.com/1/商品白底图.jpg",
"attrList": "[{\"templateId\":509101101001,\"attrItems\":[5091011010011],\"attrValue\":null},{\"templateId\":509101101004,\"attrItems\":null,\"attrValue\":\"十万个为什么\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - spuId | STRING | 平台 SPU ID |
| - skuList | ARRAY | SKU列表 |
| -- skuId | STRING | 平台 SKU ID |
| -- outSkuId | STRING | 商家 SKU 编码 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"skuList": [
{
"skuId": "k1089441529089",
"outSkuId": "arrive-hj-sku2"
}
],
"requestId": "7dfede0c-7bf2-9133-ec4b-09942",
"spuId": "p1089441529088"
}
}
# 7.2.3 门店SPU(包括SKU)修改
- 接口名
/goods/arrive/spu/update
使用场景
- 在商品提交审核后，商品状态为：审核不通过、已下架状态下，允许编辑修改商品中的相关字段；
- 目前只允许部分字段修改；
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| version | STRING | 非必填 | 默认v1.6.0, 文档版本编号 |
| spuId | STRING | 必填 | 平台 SPU ID |
| outSpuId | STRING | 必填 | 商家商品编码。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| name | STRING | 必填 | 商品名称。最多输入60个字。 |
| marketPrice | INTEGER | 必填 | 商品吊牌价（分为单位）。大于0。大于等于SKU结算价。指的是商品的原价，一般与商品吊牌上的价格一致；也叫在其他电商平台上划线价，或者市场价； |
| referencePrice | INTEGER | 非必填 | 商品市场参考价（分为单位）。大于0。指商家在其他渠道上的销售价格 |
| reduceType | INTEGER | 必填 | 库存计件（1 用户下单减库存，2 用户付款减库存 ）。现阶段暂只支持 1 |
| weight | INTEGER | 必填 | 物流重量（含包装），单位克。大于等于0.01千克，小于等于999千克。 |
| carousel | STRING | 必填 | 商品轮播图。最多5张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG，第一张商品图片默认为商品主图；图片尺寸长宽比1：1且单张图片大小不超过2M，建议尺寸为800px*800px；图片url不要带参数； |
| content | STRING | 必填 | 商品详情图。最多30张。通过【图片上传接口】，按次序上传，图片格式支持JPEG/JPG/PNG；单张图片大小不能大于2M，图片宽度建议750px；图片url不要带参数； |
| skuList | STRING | 必填 | sku 对象列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - skuId | STRING | 非必填 | 平台 SKU ID。传则认为是修改，不传则认为是新增 |
| - style1name | STRING | 非必填 | 规格1名称。如该spu规格1有值，则必填。规格名称不超过40个字； |
| - style2name | STRING | 非必填 | 规格2名称。如该spu规格2有值，则必填。规格名称不超过40个字；说明：在规格1、规格2都有值的情况下，需要按所需的【规格1，规格2】组合传入SKU，系统不会通过笛卡尔乘积自动组合；比如：规格1为：黑色、白色；规格2为：L、M；可只传入组合为：【黑色，L】、【白色，M】； |
| - outSkuId | STRING | 必填 | 商家 SKU 编码。商家自身判断商品sku的唯一标识，sku维度。不能为0。仅能包含：字母、数字、汉字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - barCode | STRING | 非必填 | 条形码。不能为0。仅能包含：字母、数字、下划线（_）、短横线（-）、+号、#号、*号、中英文括号、空格、正反斜杠、小数点； |
| - skuImg | STRING | 非必填 | SKU 图片。通过【图片上传接口】上传。图片长宽比1:1，大小不超过2M；建议尺寸为：350px*350px；图片url不要带参数； |
| - settlementPrice | NUMBER | 必填 | 结算价（分为单位）。大于0。小于等于SPU吊牌价。参加活动期间不能修改。指智慧零售与商家协商，商品销售后，需要结算给商家的价格； |
| - marketPrice | NUMBER | 必填 | 划线价/吊牌价（分为单位）。大于0。大于等于SKU结算。 |
| - marketPriceCertificate | STRING | 必填 | 划线价/吊牌价凭证，吊牌价大于等于2倍的SKU结算价时，必须填写 |
| - referencePrice | NUMBER | 非必填 | 参考价, 选填 |
| shipPledgeHours | INTEGER | 非必填 | 商品发货时间承诺（小时为单位）。默认值72，可选值72,120,168,240,360,720,1440 |
| whiteImage | STRING | 必填 | 商品白底图。图片必须为纯白底，图片长宽比要求为1:1，单张图片大小不能大于2M，建议图片尺寸为800*800像素，无logo、无水印，建议将素材抠图、边缘处理干净 |
| limitCount | INTEGER | 非必填 | 商品限购数量。大于0，小于等于10000 |
| attrList | STRING | 必填 | v1.7.5以上版本支持， 属性列表，需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - attributeId | NUMBER | 必填 | 属性项ID；可输入值：通过【属性项列表查询接口】查询 |
| - attrItems | ARRAY | 非必填 | 单/多选时，选中的属性值ID(itemId)的列表 |
| - attrValue | STRING | 非必填 | 输入框时。填写的属性值； |
- 业务请求参数示例
{
"version": "v1.7.5",
"spuId": "平台 SPU ID",
"outSpuId": "商家 SPU 编码",
"name": "商品名称",
"marketPrice": 700,
"referencePrice": 700,
"reduceType": 1,
"weight": 21000,
"onTime": 1603710993000,
"offTime": 0,
"carousel": "[\"https://img.zhls.qq.com/1/商品轮播图.jpg\"]",
"content": "[\"https://img.zhls.qq.com/1/商品详情图.jpg\"]",
"skuList": "[{\"skuId\":\"平台SKUID\",\"outSkuId\":\"商家SKU编码\",\"barCode\":\"SKU条形码\",\"skuImg\":\"https://img.zhls.qq.com/0/SKU图片.jpg\",\"style1name\":\"203*230CM\",\"style2name\":\"粉\",\"settlementPrice\":100,\"state\":1,\"marketPrice\":100,\"marketPriceCertificate\":\"https://img.zhls.qq.com/1/吊牌价凭证.jpg\"}]",
"whiteImage": "https://img.zhls.qq.com/1/商品白底图.jpg",
"attrList": "[{\"templateId\":509101101001,\"attrItems\":[5091011010011],\"attrValue\":null},{\"templateId\":509101101004,\"attrItems\":null,\"attrValue\":\"十万个为什么\"}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
| - spuId | STRING | 平台 SPU ID |
| - skuList | ARRAY | SKU列表 |
| -- skuId | STRING | 平台 SKU ID |
| -- outSkuId | STRING | 商家 SKU 编码 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"skuList": [
{
"skuId": "k1089441529089",
"outSkuId": "arrive-hj-sku2"
}
],
"requestId": "7dfede0c-7bf2-9133-ec4b-09942",
"spuId": "p1089441529088"
}
}
# 7.2.4 商品关联门店
- 接口名
/goods/arrive/spu/bindStore
使用场景：商家将商品关联至所有符合资质的门店
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuIds | ARRAY | 必填 | 平台spuId数组，最多50个 |
- 业务请求参数示例
{
"spuIds":[
"p1089434843918",
"p1089441529088",
"p1089434843922",
"p1089434843920",
"p1089434843914"
]
}
# 7.2.5 门店SPU状态修改
- 接口名
/goods/arrive/spu/update/state
使用场景：修改门店SPU上下架状态
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| updateObjList | ARRAY | 必填 | 更新数组，最大长度为100 |
| - subStoreId | STRING | 必填 | 平台门店id |
| - spuId | ARRAY | 必填 | 平台spuId |
| - state | INTEGER | 必填 | 状态（1上架，2下架）；上架前置条件：商品状态为：已下架；下架前置条件：商品状态为：待上架、在售中、已售罄 |
- 业务请求参数示例
{
"updateObjList":[
{
"subStoreId":"1ezGZw1La5v",
"spuId":"p1089434843918",
"state":2
},
{
"subStoreId":"G23b7rZk7bY",
"spuId":"p1089434843914",
"state":2
},
{
"subStoreId":"Kz3d0L16pQA",
"spuId":"p1089434843914",
"state":2
}
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "7dfede0c-7bf2-9133-ec4b-09933"
}
}
# 7.2.6 门店SKU状态修改
- 接口名
/goods/arrive/sku/update/state
使用场景：修改门店SKU上下架状态
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| updateObjList | ARRAY | 必填 | 更新数组，最大长度为100 |
| - subStoreId | STRING | 必填 | 平台门店id |
| - spuId | ARRAY | 必填 | 平台skuId |
| - state | INTEGER | 必填 | 状态（1上架，2下架）；上架前置条件：商品状态为：已下架；下架前置条件：商品状态为：待上架、在售中、已售罄 |
- 业务请求参数示例
{
"updateObjList":[
{
"subStoreId":"ejLa79doQrz",
"skuId":"k1089434843915",
"state":2
},
{
"subStoreId":"Kz3d0oz4z7m",
"skuId":"k1089434843915",
"state":1
},
{
"subStoreId":"ejLa79doQrz",
"skuId":"k1089434843921",
"state":1
}
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "f0f7685d-3b8d-484b-89ca-493e5101d93b"
}
}
# 7.2.7 门店SKU结算价修改
- 接口名
/goods/arrive/sku/update/price
使用场景：修改门店SKU结算价
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| updateObjList | ARRAY | 必填 | 更新数组，最大长度为100 |
| - subStoreId | STRING | 必填 | 平台门店id |
| - skuId | ARRAY | 必填 | 平台skuId |
| - settlementPrice | INTEGER | 单件结算价，单位：分 |
- 业务请求参数示例
{
"updateObjList":[
{
"subStoreId":"ejLa79doQrz",
"skuId":"k1089434843915",
"state":2
},
{
"subStoreId":"Kz3d0oz4z7m",
"skuId":"k1089434843915",
"state":1
},
{
"subStoreId":"ejLa79doQrz",
"skuId":"k1089434843921",
"state":1
}
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "7dfede0c-7bf2-9133-ec4b-09956"
}
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - requestId | STRING | 回传本次请求的 requestId |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "7dfede0c-7bf2-9133-ec4b-09950",
"success": null,
"fail": null
}
}
# 7.2.8 门店商品列表查询
- 接口名
/goods/arrive/store/spu/list
使用场景：查询单个门店可售的商品列表 (新增商品会延迟15s才可查到)
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| subStoreIds | ARRAY | 非必填 | 平台门店编码数组，最大长度20 |
| spuIds | ARRAY | 非必填 | 平台spu编码数组，最大长度20 |
| outSpuIds | ARRAY | 非必填 | 商家spu编码数组，最大长度20 |
| state | ARRAY | 非必填 | 门店SPU状态(2 在售中，3 已售罄，4 已下架) |
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 业务请求参数示例
{
"spuIds":[],
"outSpuIds":[],
"subStoreIds":[],
"state":0,
"pageNum":1,
"pageSize":10
}
返回参数
参数名称 参数类型 参数描述 code NUMBER 0：正常，非0：异常 message STRING 附加信息 data OBJECT 返回数据 - requestId STRING 回传本次请求的 requestId - total INTEGER 总数 - list ARRAY 门店 SPU 列表 -- spuId STRING 平台 SPU ID -- outSpuId STRING 商家 SPU 编码 -- merchantId STRING 商家ID -- storeId STRING 平台门店ID -- outStoreId STRING 门店编码 -- storeName STRING 门店名称 -- name STRING 商品名称 -- weight INTEGER 物流重量（含包装），单位克 -- state NUMBER 状态(2 在售中，3 已售罄，4 已下架) -- onTime LONG 定时上架时间（毫秒时间戳） -- offTime LONG 定时下架时间（毫秒时间戳） -- updateTime LONG 更新时间（毫秒时间戳） -- createTime LONG 创建时间（毫秒时间戳） -- limitCount INTEGER 商品限购数量（1-10000）0或null不限购 -- miniAppId STRING 商家小程序appId -- miniJumpUrl STRING 商家小程序商详页跳转链接 -- skuList ARRAY SKU 列表 --- skuId STRING 平台 SKU ID --- outSkuId STRING 商家 SKU 编码 --- barCode STRING 条形码 --- styles1 STRING 规格1 --- styles1name STRING 规格1名称 --- styles2 STRING 规格2 --- styles2name STRING 规格2名称 --- stock NUMBER 库存 --- settlementPrice NUMBER 结算价（分为单位） --- state STRING 状态（1上架，2下架） 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "7dfede0c-7bf2-9133-ec4b-09968",
"total": 1,
"list": [
{
"spuId": "平台 SPU ID",
"outSpuId": "商家 SPU 编码",
"name": "商品名",
"weight": 1000,
"state": 4,
"onTime": 1648260032000,
"offTime": 1648260032000,
"updateTime": 1648434952000,
"createTime": 1648260032000,
"limitCount": null,
"merchantId": "商家 ID",
"storeId": "门店id",
"outStoreId" : "门店编码",
"storeName": "门店名称",
"skuList": [
{
"skuId": "平台 SKU ID",
"outSkuId": "商家 SKU 编码",
"barCode": "条形码",
"styles1": "规格1",
"styles1name": "规格1名称",
"styles2": "规格2",
"styles2name": "规格2名称",
"stock": 0,
"settlementPrice": 1200,
"state": 1
}
]
}
]
}
}
# 7.2.9 根据商品查询门店列表
- 接口名
/goods/arrive/store/list
使用场景：根据商家SPU编码或SKU编码查询当前的销售门店
调用方式: 回调
商家限流qps: 120
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| spuId | ARRAY | 必填 | 平台spuId和平台skuId，两者有一个不允许为空 |
| skuId | ARRAY | 必填 | 平台spuId和平台skuId，两者有一个不允许为空 |
| pageNum | INTEGER | 是 | 返回页码，默认从1开始。PS：当前采用分页返回，数量和页数会一起传，如果不传，则采用默认值 |
| pageSize | INTEGER | 是 | 每页查询数量，默认50，最大50 |
- 业务请求参数示例
{
"skuId":"k1089434843915",
"pageNo":1,
"pageSize":5
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| - total | NUMBER | 当前销售该SPU的门店总数量 |
| - storeList | ARRAY | 门店列表 |
| - outStoreId | STRING | 门店编码 |
| - storeName | STRING | 门店名称 |
| - spuState | INTEGER | 门店SPU状态 2 在售中，3 已售罄，4 已下架 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": {
"requestId": "7dfede0c-7bf2-9133-ec4b-09933",
"list": [
{
"subStoreId": "zpdkjBZ4DMK",
"name": "测试23门店",
"outStoreId": "SS23C3D169",
"spuState": 4
},
{
"subStoreId": "zpdkjm0W2DA",
"name": "测试29门店",
"outStoreId": "SS29C3D169",
"spuState": 3
},
{
"subStoreId": "zpdkjx1pVaA",
"name": "测试25门店",
"outStoreId": "SS25C3D169",
"spuState": 3
},
{
"subStoreId": "zpdmO7bZLYO",
"name": "测试门店4",
"outStoreId": "SS4C3D169",
"spuState": 2
}
],
"total": 4
}
}
# 7.3 商品库存API
# 7.3.1 门店商品库存查询
- 接口名
/goods/stock/store/list
- 调用方式: 回调
- 商家限流qps: 30
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| outerSkus | STRING | 是 | 商家skuId列表(最大50个) List结构格式化为JSON |
- 业务请求参数示例
{
"outerSkus": [
{\"outSkuId\": \"商家sku编码\",
\"subStoreId\": \"test001门店\" //智慧零售门店id
},
{\"outSkuId\": \"商家sku编码\",
\"subStoreId\": \"test002门店\"
}
]
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "请求ID回传",
"list": [
{
"subStoreId":"智慧零售门店id1",//智慧零售门店id
"outerSkuId": "商家sku编码",
"skuId": "智慧零售skuId",
"qty": 1, //当前库存
"lockedQty": 2 //订单锁定库存,为用户下单后，未支付订单锁定的库存；
}
]
}
}
# 7.3.2 门店商品库存修改
- 接口名
/goods/stock/store/update
- 使用场景
- 商家增量修改智慧零售侧sku库存
- 增量修改时不能让最终总库存为负数
- 库存同步为 “智慧零售侧sku库存”，商家在更新商品库存时,必须保证 商家侧当前可售库存 - 订单锁定库存 =智慧零售侧sku库存数量(用户可购买的数量)；
- 调用方式: 回调
- 商家限流qps: 30
- 请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| actionType | INTEGER | 是 | 库存修改类型 1:全量修改 2:调增 3:调减 |
| stockList | STRING | 是 | 商家修改sku库存对象列表(最大50个)，List结构格式化为JSON |
- 业务请求参数示例
{
"actionType": 2,
"stockList": [
{
\"outerSkuId\": \"商家sku编码\",
\"qty\": 100 //库存加100,
\"subStoreId\": \"智慧零售门店id\",
},
{
\"outerSkuId\": \"商家sku编码\",
\"qty\": 200 //库存加200,
\"subStoreId\": \"智慧零售门店id\",
}
]
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "请求ID回传",
"failedSkuIds": [
{"subStoreId":"智慧零售门店id",
"outSkuId":"商家sku编码1"
},
{"subStoreId":"智慧零售门店id",
"outSkuId":"商家sku编码2"
},
{"subStoreId":"智慧零售门店id",
"outSkuId":"商家sku编码3"
},
],
"failedMsg": "更新失败原因"
}
}
# 7.4 运费模板API
# 7.4.1 运费模板新增
- 接口名
/goods/arrive/shipping/add
使用场景
- 通过调用该接口新增运费模板
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| templateName | STRING | 必填 | 模板名称 |
| paySubStoreIds | ARRAY | 必填 | 生效门店ID，数组类型 |
| paySubStoreFees | ARRAY | 必填 | 费用规则，数组，必须包含type为1的元素 |
| - type | NUMBER | 必填 | 费用类型：1配送费 |
| - feeType | NUMBER | 必填 | 计费方式：0按件数计费，1按重量计费 |
| - baseCount | NUMBER | 必填 | 基础配送费-计量：根据计费方式，单位为克或件 |
| - basePrice | NUMBER | 必填 | 基础配送费-费用：单位分 |
| - incrCount | NUMBER | 必填 | 附加配送费-计量：根据计费方式，单位为克或件 |
| - incrPrice | NUMBER | 必填 | 附加配送费-费用：单位分 |
| - isConditionBaseFree | NUMBER | 必填 | 指定条件免基础费用，0否1是 |
| - conditionBaseCount | NUMBER | 非必填 | 免基础费用计量 |
| - conditionBaseUnit | NUMBER | 非必填 | 免基础费用单位，1价钱-分，2件 |
| - isConditionFree | NUMBER | 必填 | 指定条件免所有费用，0否1是 |
| - conditionCount | NUMBER | 非必填 | 免所有费用计量 |
| - conditionUnit | NUMBER | 非必填 | 免所有费用单位，1价钱-分，2件 |
- 业务请求参数示例
{
"templateName": "运费模板测试",
"paySubStoreIds": [
"门店id1",
"门店id2",
"门店id3"
],
"paySubStoreFees": [
{
"type": 1,
"feeType": 1,
"baseCount": 2,
"basePrice": 100,
"incrCount": 100,
"incrPrice": 200,
"isConditionBaseFree": 0,
"conditionBaseCount": 1,
"conditionBaseUnit": 1,
"isConditionFree": 1,
"conditionCount": 50,
"conditionUnit": 2
}
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | NUMBER | 运费模板ID |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": 1
}
# 7.4.2 运费模板更新
- 接口名
/goods/arrive/shipping/update
使用场景
- 通过调用该接口更新运费模板
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| templateId | NUMBER | 必填 | 模板ID |
| templateName | STRING | 必填 | 模板名称 |
| paySubStoreIds | ARRAY | 必填 | 生效门店ID，数组类型 |
| paySubStoreFees | ARRAY | 必填 | 费用规则，数组，必须包含type为1的元素 |
| - type | NUMBER | 必填 | 费用类型：1配送费 |
| - feeType | NUMBER | 必填 | 计费方式：0按件数计费，1按重量计费 |
| - baseCount | NUMBER | 必填 | 基础配送费-计量：根据计费方式，单位为克或件 |
| - basePrice | NUMBER | 必填 | 基础配送费-费用：单位分 |
| - incrCount | NUMBER | 必填 | 附加配送费-计量：根据计费方式，单位为克或件 |
| - incrPrice | NUMBER | 必填 | 附加配送费-费用：单位分 |
| - isConditionBaseFree | NUMBER | 必填 | 指定条件免基础费用，0否1是 |
| - conditionBaseCount | NUMBER | 非必填 | 免基础费用计量 |
| - conditionBaseUnit | NUMBER | 非必填 | 免基础费用单位，1价钱-分，2件 |
| - isConditionFree | NUMBER | 必填 | 指定条件免所有费用，0否1是 |
| - conditionCount | NUMBER | 非必填 | 免所有费用计量 |
| - conditionUnit | NUMBER | 非必填 | 免所有费用单位，1价钱-分，2件 |
- 业务请求参数示例
{
"templateId": 1,
"templateName": "运费模板测试",
"paySubStoreIds": [
"门店id1",
"门店id2",
"门店id3"
],
"paySubStoreFees": [
{
"type": 1,
"feeType": 1,
"baseCount": 2,
"basePrice": 100,
"incrCount": 100,
"incrPrice": 200,
"isConditionBaseFree": 0,
"conditionBaseCount": 1,
"conditionBaseUnit": 1,
"isConditionFree": 1,
"conditionCount": 50,
"conditionUnit": 2
}
]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | NUMBER | 运费模板ID |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": 1
}
# 7.4.3 运费模板删除
- 接口名
/goods/arrive/shipping/delete
使用场景
- 通过调用该接口删除运费模板
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| templateId | NUMBER | 必填 | 模板ID |
- 业务请求参数示例
{
"templateId": 1
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | NUMBER | 运费模板ID |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": 1
}
# 7.4.4 生效中运费模板查询
- 接口名
/goods/arrive/shipping/query
使用场景
- 通过调用该接口删除运费模板，入参为模板ID或门店ID（二选一），入参为模板ID查出对应的运费模板，入参为门店ID查出门店对应生效的运费模板
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| templateIds | NUMBER | 非必填 | 模板ID |
| subStoreIds | NUMBER | 非必填 | 门店ID |
- 业务请求参数示例
{
"templateIds": [1]
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | ARRAY | 数据 |
| - templateId | NUMBER | 模板ID |
| - subStoreId | STRING | 门店ID |
| - template | OBJECT | 模板 |
| -- id | NUMBER | 模板ID |
| -- name | STRING | 模板名称 |
| -- paySubStoreIds | ARRAY | 门店ID，数组 |
| -- paySubStoreFees | ARRAY | 费用规则，数组，包含type为1的元素 |
| --- type | NUMBER | 费用类型：1配送费 |
| --- feeType | NUMBER | 计费方式：0按件数计费，1按重量计费 |
| --- baseCount | NUMBER | 基础配送费-计量：根据计费方式，单位为克或件 |
| --- basePrice | NUMBER | 基础配送费-费用：单位分 |
| --- incrCount | NUMBER | 附加配送费-计量：根据计费方式，单位为克或件 |
| --- incrPrice | NUMBER | 附加配送费-费用：单位分 |
| --- isConditionBaseFree | NUMBER | 指定条件免基础费用，0否1是 |
| --- conditionBaseCount | NUMBER | 免基础费用计量 |
| --- conditionBaseUnit | NUMBER | 免基础费用单位，1价钱-分，2件 |
| --- isConditionFree | NUMBER | 指定条件免所有费用，0否1是 |
| --- conditionCount | NUMBER | 免所有费用计量 |
| --- conditionUnit | NUMBER | 免所有费用单位，1价钱-分，2件 |
- 返回示例
{
"code": 0,
"message": "SUCCESS",
"data": [
{
"templateId": 1,
"subStoreId": "",
"template": {
"id": 1,
"name": "运费模板",
"paySubStoreIds": [
"门店ID1",
"门店ID2"
],
"paySubStoreFees": [
{
"type": 1,
"feeType": 0,
"baseCount": 1,
"basePrice": 200,
"incrCount": 3,
"incrPrice": 400,
"isConditionBaseFree": 1,
"conditionBaseCount": 500,
"conditionBaseUnit": 1,
"isConditionFree": 1,
"conditionCount": 600,
"conditionUnit": 1
}
]
}
}
]
}
# 7.5 时效运力API
# 7.5.1 时效规则列表查询
- 接口名
/shixiao/rule/list
- 使用场景
- 通过调用该接口查询商家对应的时效规则列表
- 商家只能查看自身下的规则
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| merchantId | STRING | 是 | 商家ID，腾讯荟聚侧商家标识 |
| subStoreId | STRING | 否 | 门店ID，腾讯荟聚侧门店标识 |
| ruleName | STRING | 否 | 规则名称，支持模糊查询 |
| status | NUMBER | 否 | 规则状态（1=待生效 2=生效中 3=已失效） |
| startDate | STRING | 否 | 生效开始日期 (yyyy-MM-dd) |
| endDate | STRING | 否 | 生效截止日期 (yyyy-MM-dd) |
| updateBeginTime | STRING | 否 | 最近编辑开始时间 (yyyy-MM-dd HH:mm:ss) |
| updateEndTime | STRING | 否 | 最近编辑截止时间 (yyyy-MM-dd HH:mm:ss) |
- 业务请求参数示例
{
"merchantId":"E95281",
"ruleName": "规则"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -list | ARRAY | 规则列表 |
| --ruleId | NUMBER | 规则ID |
| --ruleName | STRING | 规则名称 |
| --status | NUMBER | 规则状态（1=待生效 2=生效中 3=已失效） |
| --startDate | STRING | 生效开始日期 (yyyy-MM-dd) |
| --endDate | STRING | 生效截止日期 (yyyy-MM-dd) |
| --storeAmount | NUMBER | 生效门店数量 |
| --sendDate | NUMBER | 送达日期，第1-7天(用,隔开)，分别表示:当天，第二天，第三天等 |
| --updateTime | STRING | 最近编辑时间(yyyy-MM-dd HH:mm:ss) |
| -pageNo | NUMBER | 页码 |
| -pageSize | NUMBER | 页大小 |
| -total | NUMBER | 总数 |
| -totalPage | NUMBER | 总页数 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"list": [
{
"ruleId": 22,
"ruleName": "0609我是不限制规则222",
"status": "2",
"startDate": "2022-02-11",
"endDate": "2023-02-10",
"storeAmount": 2,
"sendDate": "1",
"updateTime": "2022-06-09 14:45:09"
},
{
"ruleId": 56305453,
"ruleName": "0617测试规则",
"status": "1",
"startDate": "2022-06-17",
"endDate": "2023-02-10",
"storeAmount": 2,
"sendDate": "1,2,3,4,5,6,7",
"updateTime": "2022-06-17 12:04:40"
}
],
"pageNo": 1,
"total": 2,
"pageSize": 10,
"totalPage": 1
},
"success": true
}
# 7.5.2 查询时效规则详情
- 接口名
/shixiao/rule/get
- 使用场景
通过调用该接口查询商家对应的时效规则详情
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| ruleId | NUMBER | 是 | 规则ID |
- 业务请求参数示例
{
"ruleId": 86505288
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -ruleId | NUMBER | 规则ID |
| -ruleName | STRING | 规则名称 |
| -status | NUMBER | 规则状态（1=待生效 2=生效中 3=已失效） |
| -startDate | STRING | 生效开始日期 (yyyy-MM-dd) |
| -endDate | STRING | 生效截止日期 (yyyy-MM-dd) |
| -storeList | ARRAY | 门店列表 |
| -- subStoreId | STRING | 门店ID，腾讯荟聚侧门店标识 |
| -- storeName | STRING | 门店名称 |
| -storeAmount | NUMBER | 生效门店数量 |
| --sendDate | STRING | 送达日期，第1-7天(用,隔开)，分别表示:当天，第二天，第三天等 |
| -sendCostTime | INTEGER | 送达时长:以分钟为单位 |
| -sendIntervalTime | INTEGER | 送达时段间隔:以分钟为单位 |
| -sendStartTime | STRING | 送达开始时间,取时分 如 09:00 |
| -sendEndTime | STRING | 送达截止时间,取时分 如 22:00 |
| -capacityType | INTEGER | 运力类型: 1 不限制 2 各时段运力限制相同 3 自定义 |
| -intervalList | ARRAY | 时段运力列表（capacityType=3必填） |
| --intervalStartTime | STRING | 时段开始时间 HH:mm |
| --intervalEndTime | STRING | 时段结束时间 HH:mm |
| --capacityAmount | INTEGER | 时段运力限制数量 |
| -capacityAmount | INTEGER | 运力限制数量（capacityType=2不为0） |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"ruleId": 86505288,
"ruleName": "0614规则更新",
"status": 1,
"startDate": "2022-06-14",
"endDate": "2023-02-10",
"storeList": [
{
"subStoreId": "1008",
"storeName": "爱马仕科兴8店update"
},
{
"subStoreId": "1009",
"storeName": "爱马仕科兴9店update"
}
],
"storeAmount": 2,
"sendDate": "1,2,3",
"sendCostTime": 30,
"sendIntervalTime": 60,
"sendStartTime": "08:00",
"sendEndTime": "20:00",
"capacityType": 3,
"intervalList": [
{
"intervalStartTime": "09:00",
"intervalEndTime": "10:00",
"capacityAmount": 30
},
{
"intervalStartTime": "10:00",
"intervalEndTime": "11:00",
"capacityAmount": 40
}
],
"capacityAmount": 0
}
}
# 7.5.3 创建时效规则
- 接口名
/shixiao/rule/create
- 使用场景
- 通过调用该接口创建商家对应的时效规则
- 时段运力列表intervalList在运力类型为 自定义时，必传
- 时段运力限制数量在运力类型为 各时段运力限制相同时，必传
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| merchantId | STRING | 是 | 商家ID，腾讯荟聚侧商家标识 |
| ruleName | STRING | 是 | 规则名称 |
| startDate | STRING | 是 | 生效开始日期(yyyy-MM-dd) |
| endDate | STRING | 是 | 生效截止日期(yyyy-MM-dd) |
| storeList | STRING | 是 | 门店列表,需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - subStoreId | STRING | 是 | 门店ID，腾讯荟聚侧门店标识 |
| - storeName | STRING | 是 | 门店名称 |
| sendDate | STRING | 是 | 送达日期: 第1-7天(多个以,隔开),如:1,2,3 |
| sendCostTime | INTEGER | 是 | 送达时长:以分钟为单位 |
| sendIntervalTime | INTEGER | 是 | 送达时段间隔:以分钟为单位 |
| sendStartTime | STRING | 是 | 送达开始时间,取时分 如 09:00 |
| sendEndTime | STRING | 是 | 送达截止时间,取时分 如 22:00 |
| capacityType | INTEGER | 是 | 运力类型: 1 不限制 2 各时段运力限制相同 3 自定义 |
| intervalList | STRING | 否 | 时段运力列表(capacityType=3必填,capacityType=1,2 将根据送达时间与送达时段间隔划分),需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| -intervalStartTime | STRING | 否 | 时段开始时间 HH:mm |
| -intervalEndTime | STRING | 否 | 时段结束时间 HH:mm |
| -capacityAmount | INTEGER | 否 | 时段运力限制数量(不限制为-1) |
| operator | STRING | 是 | 操作人 |
| capacityAmount | INTEGER | 否 | 运力限制数量（capacityType=2必填） |
| remark | STRING | 否 | 备注说明 |
- 业务请求参数示例
{
"merchantId": "E95281",
"ruleName": "0614测试规则",
"startDate": "2022-06-14",
"endDate": "2023-02-10",
"storeList": "[{\"subStoreId\": \"1008\",\"storeName\": \"爱马仕科兴8店\"},{\"subStoreId\": \"1009\",\"storeName\": \"爱马仕科兴9店\"}]",
"sendDate": "1,2,3",
"sendCostTime": 30,
"sendIntervalTime": 60,
"sendStartTime": "08:00",
"sendEndTime": "20:00",
"capacityType": 3,
"intervalList":"[{\"intervalStartTime\": \"09:00\",\"intervalEndTime\": \"10:00\",\"capacityAmount\": 30},{ \"intervalStartTime\": \"10:00\",\"intervalEndTime\": \"11:00\", \"capacityAmount\": 40}]",
"operator": "sysamdin"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | NUMBER | 规则ID，固定长度为8位 |
- 返回示例
{
"code": 0,
"message": "success",
"data": 86505288
}
# 7.5.4 编辑时效规则
- 接口名
/shixiao/rule/update
- 使用场景
- 通过调用该接口更新商家对应的时效规则
- 规则的生效开始日期和生效截止日期不能更改
- 编辑后，正在生效的时效规则将失效，编辑后新的时效规则对应的已使用运力从0开始计算，已产生订单不占用新的时效规则对应的运力
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| ruleId | INTEGER | 是 | 规则ID |
| merchantId | STRING | 是 | 商家ID，腾讯荟聚侧商家标识 |
| ruleName | STRING | 是 | 规则名称 |
| startDate | STRING | 是 | 生效开始日期(yyyy-MM-dd) |
| endDate | STRING | 是 | 生效截止日期(yyyy-MM-dd) |
| storeList | STRING | 是 | 门店列表,需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - subStoreId | STRING | 是 | 门店ID，腾讯荟聚侧门店标识 |
| - storeName | STRING | 是 | 门店名称 |
| sendDate | STRING | 是 | 送达日期: 第1-7天(多个以,隔开),如:1,2,3 |
| sendCostTime | INTEGER | 是 | 送达时长:以分钟为单位 |
| sendIntervalTime | INTEGER | 是 | 送达时段间隔:以分钟为单位 |
| sendStartTime | STRING | 是 | 送达开始时间,取时分 如 09:00 |
| sendEndTime | STRING | 是 | 送达截止时间,取时分 如 22:00 |
| capacityType | INTEGER | 是 | 运力类型: 1 不限制 2 各时段运力限制相同 3 自定义 |
| intervalList | STRING | 否 | 时段运力列表(capacityType=3必填,capacityType=1,2 将根据送达时间与送达时段间隔划分),需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| -intervalStartTime | STRING | 否 | 时段开始时间 HH:mm |
| -intervalEndTime | STRING | 否 | 时段结束时间 HH:mm |
| -capacityAmount | INTEGER | 否 | 时段运力限制数量(不限制为-1) |
| operator | STRING | 是 | 操作人 |
| capacityAmount | INTEGER | 否 | 运力限制数量（capacityType=2必填） |
| remark | STRING | 否 | 备注说明 |
- 业务请求参数示例
{
"ruleId":86505288,
"merchantId": "E95281",
"ruleName": "0614规则更新",
"startDate": "2022-06-14",
"endDate": "2023-02-10",
"storeList": "[{\"subStoreId\": \"1008\",\"storeName\": \"爱马仕科兴8店\"},\"subStoreId\": \"1009\",\"storeName\": \"爱马仕科兴9店\"}]",
"sendDate": "1,2,3",
"sendCostTime": 30,
"sendIntervalTime": 60,
"sendStartTime": "08:00",
"sendEndTime": "20:00",
"capacityType": 3,
"intervalList":"[{\"intervalStartTime\": \"09:00\",\"intervalEndTime\": \"10:00\",\"capacityAmount\": 30},{ \"intervalStartTime\": \"10:00\",\"intervalEndTime\": \"11:00\", \"capacityAmount\": 40}]",
"operator": "sysamdin"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
- 返回示例
{
"code": 0,
"message": "success"
}
# 7.5.5 删除时效规则
- 接口名
/shixiao/rule/delete
- 使用场景
- 通过调用该接口删除商家对应的时效规则
- 删除后，正在生效的时效规则将失效，门店将无法查询该规则下的运力，无法占用该规则时效运力进行下单
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| ruleId | INTEGER | 是 | 规则ID |
| merchantId | STRING | 是 | 商家ID，腾讯荟聚侧商家标识 |
| operator | STRING | 是 | 操作人 |
- 业务请求参数示例
{
"ruleId":86505288,
"merchantId": "E95281",
"operator":"王萌新"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
- 返回示例
{
"code": 0,
"message": "success"
}
# 7.5.6 门店实时运力详情查询
- 接口名
/shixiao/capacity/getByStoreId
- 使用场景
- 通过调用该接口查询门店配置的时效规则，以及该规则的时效运力信息
- 如商家对门店配置了多个时效规则，返回最近编辑的一个时效规则信息
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| merchantId | STRING | 是 | 商家ID,腾讯荟聚侧商家标识 |
| subStoreId | STRING | 是 | 门店ID，腾讯荟聚侧门店标识 |
- 业务请求参数示例
{
"merchantId": "E95281",
"subStoreId": "1e9xQ8L3ENZ"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
| data | OBJECT | 返回数据 |
| -ruleId | NUMBER | 规则ID |
| -ruleName | STRING | 规则名称 |
| -sendCostTime | INTEGER | 送达时长:以分钟为单位 |
| -list | ARRAY | 时效运力列表,按送达日期升序 |
| --sendDate | STRING | 送达日期(yyyy-MM-dd) |
| --intervalList | ARRAY | 时段运力列表，按时段开始时间升序 |
| ---timeIntervalId | NUMBER | 时段ID |
| ---intervalStartTime | STRING | 时段开始时间 HH:mm |
| ---intervalEndTime | STRING | 时段结束时间 HH:mm |
| ---capacityAmount | STRING | 时段运力限制数量，不限制为-1 |
| ---availableCapacity | STRING | 时段运力可用数量，不限制为-1 |
- 返回示例
{
"code": 0,
"message": "success",
"data": {
"ruleId": 26111418,
"ruleName": "海岸城店极速达",
"sendCostTime": 30,
"list": [
{
"sendDate":"2022-06-17",
"intervalList":[
{
"timeIntervalId": 107,
"intervalStartTime": "09:00",
"intervalEndTime": "10:00",
"capacityAmount": "50",
"availableCapacity": "50"
},
{
"timeIntervalId": 108,
"intervalStartTime": "10:00",
"intervalEndTime": "11:00",
"capacityAmount": "50",
"availableCapacity": "50"
}
]
},
{
"sendDate":"2022-06-18",
"intervalList":[
{
"timeIntervalId": 107,
"intervalStartTime": "09:00",
"intervalEndTime": "10:00",
"capacityAmount": "50",
"availableCapacity": "50"
},
{
"timeIntervalId": 108,
"intervalStartTime": "10:00",
"intervalEndTime": "11:00",
"capacityAmount": "50",
"availableCapacity": "50"
}
]
}
]
}
}
# 7.5.7 门店运力批量更新
- 接口名
/shixiao/capacity/batch/update
- 使用场景
- 门店活动需要单独增加、扣减指定日期的时效运力，可通过调用该接口更新指定门店、指定配送日期下的时段运力总数量和可用运力数量
- 可批量更改同一配送日期内多个时段下的运力总数量和可用运力数量
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| type | NUMBER | 是 | 操作类型(1扣减 2 增加) |
| merchantId | STRING | 是 | 商家ID,腾讯荟聚侧商家标识 |
| ruleId | NUMBER | 是 | 规则ID |
| subStoreId | STRING | 是 | 门店ID，腾讯荟聚侧门店标识 |
| sendDate | STRING | 是 | 配送日期 (yyyy-MM-dd) |
| operator | STRING | 是 | 操作人 |
| remark | STRING | 否 | 备注 |
| capacities | STRING | 是 | 时效运力信息,需要将 OBJECT[] 类型的列表转为 STRING 类型的 JSON 字符串 |
| - timeIntervalId | Long | 必填 | 时段id |
| - capacityAmount | Long | 必填 | 时段运力总数量(限制数量) |
| - availableAmount | Long | 必填 | 时段可用运力数量 |
- 业务请求参数示例
{
"type": 2,
"merchantId": "E95281",
"ruleId": 58412176,
"subStoreId": "1e9xQ8L3ENZ",
"sendDate": "2022-06-13",
"operator": "王萌新",
"remark": "店庆活动增加",
"capacities":"[{\"timeIntervalId\":234,\"capacityAmount\":200,\"availableAmount\":200}]"
}
- 返回参数
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| code | NUMBER | 0：正常，非0：异常 |
| message | STRING | 附加信息 |
- 返回示例
{
"code": 0,
"message": "success"
}
# 7.6 订单履约API
# 7.6.1 订单拣货
- 接口名
/fulfill/o2o/savePickingStatus
- 使用场景
- 通过调用拣货接口记录订单的拣货过程，普通订单无需调用
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | STRING | 是 | 智慧零售侧订单号 |
| status | Integer | 是 | 履约状态：1-待拣货；2-拣货中；3-待配送（支持跳过1直接传后面的状态，建议从第一个开始确保有完整的履约轨迹） |
| remark | STRING | 否 | 对应履约状态的说明 |
| skuInfo | STRING | 否 | 拣货商品信息，json格式，为空表示所有商品 |
- 业务请求参数示例
{
"orderId": "智慧零售订单号",
"skuInfo": "[{\"skuId\":\"sku-1\",\"qty\":1},{\"skuId\":\"sku-2\",\"qty\":1}]",
"status":1,
"remark":"留言"
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx",
"fulfillId":"12345678"
}
}
# 7.6.2 拣货状态更新
- 接口名
/fulfill/o2o/updatePickingStatus
- 使用场景
- 商家通过该接口更新拣货状态
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| fulfillId | STRING | 是 | 履约单单号 |
| status | INTEGER | 是 | 履约状态：1-待拣货；2-拣货中；3-待配送（支持跳过1直接传后面的状态，建议从第一个开始确保有完整的履约轨迹） |
| remark | STRING | 否 | 状态说明 |
- 业务请求参数示例
{
"fulfillId": "智慧零售订单号",
"status": 2,
"remark":"拣货员 张三 正在为您拣货"
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx",
"fulfillId":"12345678",
"fulfillDeliverId":"1234567890"
}
}
# 7.6.3 订单发货
- 接口名
/fulfill/o2o/addDeliverInfo
- 使用场景
- 通过调用O2O订单发货接口操作订单发货，使订单状态流转到“待收货”
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| orderId | STRING | 是 | 智慧零售侧订单号 |
| fulfillId | STRING | 否 | 履约单单号 |
| skuInfo | STRING | 否 | 发货商品信息，json格式。若没有履约单则必填。 |
| fulfillType | INTEGER | 是 | 履约方式：2-即时配送 3-自由配送 |
| deliverCompany | STRING | 否 | 物流公司，即时配送必填 |
| deliverNumber | STRING | 否 | 物流单号，即时配送必填 |
- 业务请求参数示例
{
"orderId": "智慧零售订单号",
"skuInfo": "[{\"skuId\":\"sku-1\",\"qty\":1},{\"skuId\":\"sku-2\",\"qty\":1}]",
"fulfullType":2,
"deliverCompany":"SFTC",
"deliverNumber":"123456"
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx",
"fulfillId":"12345678",
"fulfillDeliverId":"1234567890"
}
}
# 7.6.4 配送轨迹更新
- 接口名
/express/o2o/trace/upload
- 使用场景
- 上传轨迹，小程序端可以展示给用户轨迹信息
调用方式: 回调
商家限流qps: 30
请求参数
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| fulfillDeliverId | STRING | 是 | 履约物流单号 |
| traceDetails | STRING | 是 | 轨迹列表 |
| -traceTimestamp | LONG | 是 | 快递踪迹发生时间，毫秒级别 |
| -traceStatus | STRING | 是 | 轨迹状态（详见附录：O2O配送状态列表） |
| -detail | STRING | 是 | 详情 |
| status | STRING | 是 | 轨迹状态（详见附录：O2O配送状态列表） |
| courierName | STRING | 是 | 配送员名称 |
| courierPhone | STRING | 是 | 配送员电话 |
| operation | STRING | 是 | 推送操作状态:append:扩展，override:覆盖 |
- 业务请求参数示例
{
"fulfillDeliverId": "424337537576441707",
"traceDetails": "[{\"traceTimestamp\":1636547754000,\"traceStatus\":302,\"detail\":\"302[深圳市]快件离开[新南山科技北]已发往[深圳中心]\"}]",
"courierName": "配送员",
"courierPhone": "18888888888",
"status": 302,
"operation": "append"
}
- 响应结果
{
"code":0,
"message":"success",
"data": {
"requestId": "xxx"
}
}
# 8. 附录
# 8.1 订单状态列表
| 状态码 | 描述 |
|---|---|
| WAIT_DELIVER | 待发货 |
| WAIT_RECEIVE | 待收货 |
| TRADE_FINISH | 交易成功 |
| TRADE_CLOSE | 交易关闭 |
# 8.2 售后单类型(afterSaleType)
| 类型 | 描述 |
|---|---|
| REFUND | 未发货-仅退款 |
| AFTER_SALE_REFUND | 已发货-仅退款 |
| AFTER_SALE_RETURN | 已发货-退货退款 |
# 8.3 退货退款单状态列表
| 状态码 | 描述 |
|---|---|
| WAIT_AUDIT | 待商家审核 |
| AUDIT_FAIL | 拒绝退款，待与买家协商 |
| WAIT_DELIVER | 待买家退货 |
| WAIT_REFUND_AUDIT | 待商家确认收货 |
| REFUND_AUDIT_FAIL | 拒绝收货，待与买家协商 |
| WAIT_REFUND | 确认收货，退款中 |
| REFUND_CLOSE | 退款单关闭 |
| REFUND_FINISH | 退款成功 |
| REFUND_FAIL | 退款失败 |
# 8.4 退款单状态列表
| 状态码 | 描述 |
|---|---|
| WAIT_AUDIT | 待商家审核 |
| AUDIT_FAIL | 拒绝退款，待与买家协商 |
| WAIT_REFUND | 同意退款，退款中 |
| REFUND_CLOSE | 退款单关闭 |
| REFUND_FINISH | 退款成功 |
| REFUND_FAIL | 退款失败 |
# 8.5 退款单（审核是否同意退款）拒绝原因码
| 状态码 | 描述 | 对应接口 | 售后单类型(afterSaleType) |
|---|---|---|---|
| 1000 | 其他 | /aftersale/audit | AFTER_SALE_REFUND |
| 1001 | 仅支持退货退款 | /aftersale/audit | AFTER_SALE_REFUND |
| 1002 | 超过退款期限 | /aftersale/audit | AFTER_SALE_REFUND |
# 8.6 退货退款单（审核是否同意退货）拒绝原因码
| 状态码 | 描述 | 对应接口 | 售后单类型(afterSaleType) |
|---|---|---|---|
| 2000 | 其他 | /aftersale/audit | AFTER_SALE_RETURN |
| 2001 | 超过售后期限 | /aftersale/audit | AFTER_SALE_RETURN |
| 2002 | 退款金额有误 | /aftersale/audit | AFTER_SALE_RETURN |
# 8.7 退货退款单（审核是否同意退款）拒绝原因码
| 状态码 | 描述 | 对应接口 | 售后单类型(afterSaleType) |
|---|---|---|---|
| 3000 | 其他 | /aftersale/refund/audit | AFTER_SALE_RETURN |
| 3001 | 商品影响二次销售 | /aftersale/refund/audit | AFTER_SALE_RETURN |
| 3002 | 退货商品有误 | /aftersale/refund/audit | AFTER_SALE_RETURN |
# 8.8 快递公司编码（deliverCompany）
快递公司编码列表参考表格：https://doc.weixin.qq.com/sheet/e3_AYUAgwaQAAsMNFzgokxQMmHA1LcY1?scode=AJEAIQdfAAojRHEZXeAYUAgwaQAAs，如有疑问，请联系相关对接人员
# 8.9 错误码说明
| 错误码 | 错误码描述 | 解决办法 |
|---|---|---|
| 0 | 成功 | - |
| 200100 | 服务内部错误 | 服务内部错误 |
| 200101 | 内部接口连接异常 | 调用方设置合理重试间隔和次数 |
| 200102 | 内部接口请求异常 | 调用方设置合理重试间隔和次数 |
| 200103 | 响应结果为空 | 调用方设置合理重试间隔和次数，设置监控告警 |
| 200104 | HTTP请求格式异常 | 检查HTTP请求格式，比如是否设置请求头Content-Type: application/json |
| 200105 | 请求参数校验错误 | 检查HTTP请求参数是否按接口文档说明要求 |
| 200106 | 请求参数类型匹配错误 | 检查HTTP请求参数类型是否按接口文档说明要求 |
| 200120 | 参数错误 | 对照文档接口检查传参是否正确 |
| 200121 | appId错误 | 检查appId是否正确 |
| 200122 | 时间戳异常 | 检查时间戳参数是否按文档要求 |
| 200123 | 签名校验错误 | 检查sign签名是否按文档说明的算法得出 |
| 200124 | 签名已过期 | 检查sign签名计算时间是否过期 |
| 200125 | 调用过于频繁，请调整频率 | 检查相应接口的调用频率是否符合限流规则 |
| 200130 | 内部接口响应格式异常 | 调用方设置监控告警 |
| 103100 | 售后单查询服务异常 | 服务异常，商家侧监控上报错误码并联系智零开发团队 |
| 103101 | 售后服务请求参数错误 | 检查请求参数是否正确 |
| 103103 | 售后服务订单不存在 | 检查请求参数是否正确 |
| 103106 | 售后服务拒绝当前操作 | 检查请求参数是否正确 |
| 103107 | 售后单不存在 | 检查请求参数是否正确 |
| 103109 | 售后单状态异常 | 当前售后单状态不允许本次操作，请确认业务流程 |
| 103111 | 仅退款售后单不允许拒绝用户退款申请 | 商家侧内部对齐业务流程 |
| 103112 | 拒绝原因不匹配 | 请求传参的拒绝状态码是否对齐 |
| 103700 | 订单查询服务异常 | 服务异常，商家侧监控上报错误码并联系智零开发团队 |
| 103701 | 订单服务请求参数错误 | 商家侧系统检查请求参数是否正确 |
| 103702 | 订单不存在 | 商家侧系统检查请求参数是否正确 |
| 103704 | 订单状态异常 | 商家侧系统检查请求参数是否正确 |
| 103708 | 快递公司未匹配 | 按智零提供的物流公司编码对齐 |
| 103709 | 订单服务拒绝当前操作 | 检查请求参数是否正确 |
| 103710 | 已存在流程中的退款单 | 检查当前订单关联的售后单数据状态 |
| 103712 | 订单物流数量超过限制 | 单个订单最多发50个包裹 |
| 103714 | 找不到对应的物流单 | 修改/删除物流单找不到原物流信息 |
| 103715 | 已存在该物流单 | 修改物流单时新物流单号已存在 |
| 102602 | 库存服务请求参数错误 | 请求参数错误，请检查参数是否合规 |
| 102603 | 商品库存不存在，请添加后更新 | 请确认在智慧零售侧是否添加过商品和库存 |
| 102699 | 库存服务异常 | 服务异常，请监控上报并联系服务提供方 |
| 105000 | 商品服务异常 | 服务异常，请监控上报并联系服务提供方 |
| 105002 | 操作失败 | 商家侧系统检查是否满足接口条件 |
| 105003 | 商品不存在 | 商家侧系统检查请求参数是否正确 |
| 105004 | 图片不符合要求 | 检查图片参数是否符合接口要求 |
| 213010 | 优惠券服务请求参数错误 | 请求参数错误，请检查参数是否合规 |
| 213011 | 优惠券服务异常 | 服务异常，请监控上报并联系服务提供方 |
| 213012 | 优惠券列表查询失败 | 请检查参数是否正确，或联系服务提供方 |
| 213013 | 优惠券列表查询失败 | 请检查参数是否正确，或联系服务提供方 |
| 213014 | 优惠券草稿保存失败 | 请检查参数是否正确，或联系服务提供方 |
| 213015 | 优惠券提交失败 | 请检查参数是否正确，或联系服务提供方 |
| 213016 | 优惠券取消发放失败 | 优惠券未开始才允许取消发放，或联系服务提供方 |
| 213017 | 优惠券停止发放失败 | 优惠券已生效才允许停止发放，或联系服务提供方 |
错误码返回0表示请求成功，大于0表示请求异常
# 8.10 敏感数据加解密
所有涉及敏感信息的开放API后端都会做加密，调用方拿到密文数据后按双方约定的算法解密。
- 敏感接口列表
| 接口名 | 说明 |
|---|---|
| /order/list | 订单列表 |
| /order/list/increment | 订单增量列表 |
- 敏感字段列表
| 字段名 | 说明 |
|---|---|
| userName | 收货人姓名 |
| telNumber | 收货人手机 |
| provinceName | 省 |
| cityName | 市 |
| countyName | 区 |
| detailInfo | 详细地址 |
| deliverNumber | 快递单号 |
| deliverCompany | 快递公司 |
- 加解密算法介绍
- 加密算法使用"AES/CBC/PKCS5Padding"
- 加密用的初始向量会直接编码到加密数据中, 因此相同数据内容多次加密的结果不同
- 不同商家使用不同的密钥，密钥在商家申请入驻智慧零售系统后由开放平台管理端统一分配
- 数据为空字段开放API后端不加密
- AES加解密示例工具仅供参考，调用方结合实际环境自行实现
/**
* AES加解密工具
*/
public final class AESUtils {
private AESUtils() {
}
/**
* AES加密
*
* @param plainText 明文
* @param key 密钥
* @return byte[] 密文字节数组
*/
public static byte[] encrypt(String plainText, String key) throws Exception {
byte[] data = plainText.getBytes();
//生成向量
int ivSize = 16;
byte[] iv = new byte[ivSize];
SecureRandom random = new SecureRandom();
random.nextBytes(iv);
IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
//密钥hash
MessageDigest digest = MessageDigest.getInstance("SHA-256");
digest.update(key.getBytes(StandardCharsets.UTF_8));
byte[] keyBytes = new byte[16];
System.arraycopy(digest.digest(), 0, keyBytes, 0, keyBytes.length);
SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "AES");
//数据加密
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivParameterSpec);
byte[] encrypted = cipher.doFinal(data);
//整合向量和密文
byte[] encryptedIVAndText = new byte[ivSize + encrypted.length];
System.arraycopy(iv, 0, encryptedIVAndText, 0, ivSize);
System.arraycopy(encrypted, 0, encryptedIVAndText, ivSize, encrypted.length);
return encryptedIVAndText;
}
/**
* AES解密
*
* @param encryptedIvTextBytes 明文字节数组
* @param key 密钥
* @return String 明文
*/
public static String decrypt(byte[] encryptedIvTextBytes, String key) throws Exception {
int ivSize = 16;
int keySize = 16;
//解析出向量内容
byte[] iv = new byte[ivSize];
System.arraycopy(encryptedIvTextBytes, 0, iv, 0, iv.length);
IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
//解析密文数据
int encryptedSize = encryptedIvTextBytes.length - ivSize;
byte[] encryptedBytes = new byte[encryptedSize];
System.arraycopy(encryptedIvTextBytes, ivSize, encryptedBytes, 0, encryptedSize);
//密钥hash
byte[] keyBytes = new byte[keySize];
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(key.getBytes(StandardCharsets.UTF_8));
System.arraycopy(md.digest(), 0, keyBytes, 0, keyBytes.length);
SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "AES");
//密文还原
Cipher cipherDecrypt = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipherDecrypt.init(Cipher.DECRYPT_MODE, secretKeySpec, ivParameterSpec);
byte[] decrypted = cipherDecrypt.doFinal(encryptedBytes);
return new String(decrypted);
}
}
- 加解密调用示例
public static void main(String[] args) throws Exception {
String key = "data-key";
String data = "深圳市南山区科技园";
byte[] encrypted = AESUtils.encrypt(data, key);
String visibleStr = Base64.getEncoder().encodeToString(encrypted);
System.out.println(visibleStr);
byte[] encryptedBytes = Base64.getDecoder().decode(visibleStr);
String decrypted = AESUtils.decrypt(encryptedBytes, key);
System.out.println(decrypted);
}
- PHP客户端请求样例
<?php
/**
* post请求
* @param $url
* @param string $data
* @param int $timeout
* @return bool|string
*/
function post($url, $data = '', $timeout = 5)
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
if (is_string($data)) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
} else {
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json;charset=utf-8', 'Accept:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
$ret = curl_exec($ch);
curl_close($ch);
return $ret;
}
/** 当前时间戳*/
function currentTimeMillis(): float
{
list($s1, $s2) = explode(' ', microtime());
return (float)sprintf('%.0f', (floatval($s1) + floatval($s2)) * 1000);
}
/** 请求签名计算 */
class SignatureUtils
{
/** 生成请求签名
* @param $params array
* @param $appSecret string
* @return string
*/
public static function genSignature(array $params, string $appSecret): string
{
//参数对按key自然升序
ksort($params);
//遍历参数对
$str = "";
$index = 0;
foreach ($params as $k => $v) {
$str .= $k . "=" . urlencode(strval($v));
if ($index < count($params) - 1) {
$str .= "&";
}
$index++;
}
$str .= "&appSecret=" . $appSecret;
return strtoupper(md5($str));
}
}
//测试样例
$url = "https://qytest.sr.qq.com/openapi/v1/logistics/delivery/save";
//一单多物流发货接口
$deliveryPackage = array(
"deliverNumber" => 'xxx999',
"deliverCompany" => 'yuantong',
);
$deliverItems = array();
$item1 = array(
"skuId" => 'xxx101',
"spuId" => 'xxx102',
"outerSkuId" => 'xxx103',
"qty" => 1
);
$item2 = array(
"skuId" => 'xxx201',
"spuId" => 'xxx202',
"outerSkuId" => 'xxx203',
"qty" => 1
);
array_push($deliverItems, $item1, $item2);
$deliveryPackage['deliverItems'] = $deliverItems;
$params = array(
"requestId" => uniqid(),
"appId" => "test-appid-xxx",
"timestamp" => currentTimeMillis(),
"nonceStr" => substr(uniqid(), 0, 6),
"orderId" => 'xxx',
);
$params['deliverPackages'] = json_encode($deliveryPackage);
$sign = SignatureUtils::genSignature($params, "test-secret-xxx");
echo $sign;
echo "\n";
$params["sign"] = $sign;
$ret = post($url, json_encode($params), 3);
echo $ret;
- PHP客户端解密示例
<?php
/**
*
* AES解密
* @param $encryptedStr
* @param $key
* @return string
*/
function decrypt($encryptedStr, $key): string
{
try {
$encoded = base64_decode($encryptedStr);
$iv = substr($encoded, 0, 16);
$data = substr($encoded, 16);
$sha256key = encrypt_sha256($key);
$actualKey = substr($sha256key, 0, 16);
$decoded = openssl_decrypt($data, 'AES-128-CBC', $actualKey, OPENSSL_RAW_DATA, $iv);
if ($decoded === false) {
return "error";
}
return $decoded;
} catch (Exception $e) {
return "error";
}
}
function encrypt_sha256($str = ''): string
{
$res = hash("sha256", $str);
return hex2bin($res);
}
$r = decrypt("ajo52aeKdwAi1tkGl/F1IpPTBaSJB9dj/ioG9f4/uPUcn1MeW2dTwHgpidKcGTSF", "data-key2");
echo $r;
# 8.11 O2O配送状态列表
| 状态值 | 状态 | 含义 |
|---|---|---|
| 101 | 等待分配骑手 | 配送公司接单阶段—初始状态 |
| 102 | 骑手已接单 | 配送公司接单阶段—正常状态 |
| 103 | 商家取消订单 | 配送公司接单阶段—异常状态，接单异常 |
| 201 | 骑手到店开始取货 | 骑手取货阶段 |
| 202 | 取货成功，开始配送 | 骑手取货阶段—正常状态 |
| 203 | 取货失败，商家取消订单 | 骑手取货阶段—异常状态，取货异常 |
| 204 | 取货失败，骑手因自身原因取消订单， 订单结束 | 骑手取货阶段—异常状态，取货异常 |
| 205 | 取货失败，骑手因商家原因取消订单， 订单结束 | 骑手取货阶段—异常状态，取货异常 |
| 301 | 配送中 | 骑手配送阶段—正常状态 |
| 302 | 配送已完成 | 骑手配送阶段—正常状态 |
| 303 | 商家取消订单，物品开始返还商家 | 骑手配送阶段—异常状态，配送异常 |
| 304 | 无法联系收货人，物品开始返还商家 | 骑手配送阶段—异常状态，配送异常 |
| 305 | 收货人拒收，物品开始返还商家 | 骑手配送阶段—异常状态，配送异常 |
| 401 | 货品返还商户成功 | 骑手配送阶段—异常状态，配送异常 |
| 501 | 因运力系统原因取消 | 骑手配送阶段—异常状态，配送异常 |
| 502 | 因不可抗拒因素（天气，道路管制等原因）取消 | 骑手配送阶段—异常状态，配送异常 |
| 601 | 配送异常 | 其它所有异常情况下通用异常状态 |