API文档

开发注意事项必读：https://helptb.kuaidizs.cn/helpMap/getDetail?detailId=1234

测试环境接口链接：https://apiopenp.kuaidizs.cn/api/gateway

正式环境接口链接：https://apiopen.kuaidizs.cn/api/gateway

测试环境登陆连接：https://openmallp.kuaidizs.cn/forward.jsp

正式环境登陆连接：https://openmall.kuaidizs.cn/forward.jsp

应用类型

1 单店铺类型：一个appKey下只能存在一店铺。

2 多店铺类型：一个appKey下可以存在多个店铺,登录时的APP_KEY格式为 appkey_shopName_token。

请求格式

公共参数+应用参数

1.公共参数

2.应用参数appParam

3.签名的摘要算法 目前支持md5

1、所有非空系统参数和应用参数根据参数名按acsii字符集排序规则排序(注意是非空！)，并且在首尾凭借appSecret 如 999999999appKey=AAA&appParam=ABC&method=open.test&timestamp=1567862623723999999999

2、待签名串做大写32位MD5加密得到5E4E06D831A2FCB85A8905E0C2B5F9EB

交易模块

1. 创建订单

method:trade.create

应用参数： MallTrade

MallOrder

MallInvoice(暂无用)

MallProp

返回参数：

示例代码：

public void testTradeCreate() throws IOException {
        MallTrade mallTrade = createTradeUtil();//创建订单对象的工具类
        //请求部分
        String appParams = JSON.toJSONString(mallTrade);
        Map<String, String> sysParams = buildSysParams("trade.create");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        //应用参数
        System.out.println(appParams);
        //公共参数
        System.out.println(JSONObject.toJSONString(sysParams));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        //返回值格式
        System.out.println(res);
    }

2.批量推送订单信息（一次最多可推送300条）（内测中）

method:trade.batchCreate

应用参数：

示例代码：

xxxxxxxxxx
public void testBatchCreateTrade() throws Exception {
        MallTradeListVo mallTradeListVo = new MallTradeListVo();
        List<MallTrade> mallTrades = new ArrayList();
        //模拟请求参数 --批量订单
        for (int i = 0; i < 3; i++) {
            MallTrade mallTrade = createTradeUtil();
            mallTrades.add(mallTrade);
            Thread.sleep(1000);
        }
        mallTradeListVo.setMallTradeList(mallTrades);
        //请求部分
        String appParams = JSON.toJSONString(mallTradeListVo);
        Map<String, String> sysParams = buildSysParams("trade.batchCreate");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
    //请求参数
        System.out.println("appParams" + appParams);
    //系统参数
        System.out.println("sysParams" + sysParams);
        System.out.println("sign:" + signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println("res:" + res);
    }

3.修改订单信息

method:trade.update

公共参数

应用参数：

返回参数：

示例代码：

​x
public void testTradeUpdate() throws IOException {
        //模拟订单修改数据
        MallTradeUpdate mallTrade = new MallTradeUpdate();
        mallTrade.setModified(new Date());
        mallTrade.setTid("trade202007231595496355218");
        mallTrade.setReceiverAddress("修改订单地址");
        mallTrade.setReceiverName("修改收件人姓名");
        //请求参数部分
        String appParams = JSON.toJSONString(mallTrade);
        Map<String, String> sysParams = buildSysParams("trade.update");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }
​

4.订单发货

method:trade.send

公共参数

应用参数：

返回参数：

示例代码：

xxxxxxxxxx
//此情况是开发商将已发货的订单信息同步至快递助手方订单发货信息
public void testTradeSend() throws IOException {
        //模拟需要发货的订单数据
        MallTradeSend mallTrade = new MallTradeSend();
        mallTrade.setCompanyCode("YTO");
        mallTrade.setTid("trade202007231595496355218");
        mallTrade.setSplit(true);
        ArrayList<String> oids = new ArrayList<>();
        oids.add("order202007231595496355220");
        mallTrade.setOids(oids);
        mallTrade.setWaybillNo("YTO787878787878");
    //请求部分
        String appParams = JSON.toJSONString(mallTrade);
        Map<String, String> sysParams = buildSysParams("trade.send");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }
​

5.订单退款

method:trade.refund

公共参数 应用参数：

返回参数：

示例代码：

xxxxxxxxxx
public void testTradeRefund() throws IOException {
        //模拟需要退款的订单数据
        MallTradeRefund mallTrade = new MallTradeRefund();
        mallTrade.setTid("trade202007231595497923437");
        //若传入子订单 则默认更改子订单状态而不改变订单状态 不传子订单 默认更改所有订单状态
        ArrayList<String> oids = new ArrayList<>();
        oids.add("order202007231595481842541");
        mallTrade.setOids(oids);
        mallTrade.setRefundStatus("REFUND_SUCCESSED");
    //请求部分
        String appParams = JSON.toJSONString(mallTrade);
        Map<String, String> sysParams = buildSysParams("trade.refund");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }

6.订单删除

method:trade.batchDelete

公共参数 应用参数：

返回参数：

示例代码：

xxxxxxxxxx
public void testBatchDelete() throws IOException {
        //模拟需要删除订单
        MallTradeTidList mallTradeTidList = new MallTradeTidList();
        ArrayList<String> tidList = new ArrayList<>();
        tidList.add("trade202007231595497923437");
        tidList.add("trade202007231595497798431");
        mallTradeTidList.setTidList(tidList);
    //请求部分
        String appParams = JSON.toJSONString(mallTradeTidList);
        Map<String, String> sysParams = buildSysParams("trade.batchDelete");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }
​

商品模块

7.同步商品列表

定时推送全部商品列表

method:product.list

公共参数

应用参数：

MallItem

MallSku

返回参数：

示例代码：

xxxxxxxxxx
 public void testItemList() throws IOException {
        MallItemList mallItemList = new MallItemList();
    //模拟生成商品对象
        List<MallItem> mallItems = new ArrayList<>();
        for (int i = 0; i < 3; i++) {
            MallItem mallItem = createMallItemUtil();
            mallItems.add(mallItem);
        }
        mallItemList.setItemList(mallItems);
    //请求部分
        String appParams = JSON.toJSONString(mallItemList);
        Map<String, String> sysParams = buildSysParams("product.saveItemList");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }

8.批量更新商品（一次同步不可超过500条）

有则更新，无则添加

method:product.saveItemList

公共参数

应用参数：

返回参数：

示例代码：

xxxxxxxxxx
public void testUpdateItem() throws IOException {
    //模拟需要修改的商品对象
        MallItem mallItem = JMockData.mock(MallItem.class);
        mallItem.setAppKey(openApp.getAppKey());
        mallItem.setId(null);
        mallItem.setItemId("102");
        mallItem.setTitle("修改商品title");
        mallItem.setCreated(new Date());
        mallItem.setModified(new Date());
        mallItem.setStatus("ONSALE");
        mallItem.setPicUrl("测试图片地址");
        List<MallSku> skus = new ArrayList<>();
        MallSku sku = new MallSku();
        sku.setItemId("102");
        sku.setSkuId("20216224-skuid");
        sku.setItemTitle("修改商品sku");
        sku.setSkuName("修改sku");
        sku.setStatus(1);
        sku.setModified(new Date());
        skus.add(sku);
        mallItem.setSkus(skus);
        MallItemList mallItemList = new MallItemList();
        mallItemList.setItemList(Arrays.asList(mallItem));
    //请求部分
        String appParams = JSON.toJSONString(mallItemList);
        Map<String, String> sysParams = buildSysParams("product.saveItemList");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }

9.商品删除

method:product.deleteItemList

公共参数 应用参数：

返回参数：

示例代码：

xxxxxxxxxx
 public void testDeleteItem() throws IOException {
        MallItemIdList mallItemIdList = new MallItemIdList();
        List<String> list = new ArrayList<>();
        list.add("102");
        mallItemIdList.setItemIdList(list);
        String appParams = JSON.toJSONString(mallItemIdList);
        Map<String, String> sysParams = buildSysParams("product.deleteItemList");
        sysParams.put("appParam", appParams);
        sysParams.put("sign", signRequestCommon(JSONObject.parseObject(JSONObject.toJSONString(sysParams)), openApp.getAppSecret()));
        String res = WebUtils.doPost(apiUrl, sysParams, timeout, timeout);
        System.out.println(res);
    }

10. 平台提供外网访问接口列表

• 10.1 同步发货API

method:trade.send POST application/x-www-form-urlencoded

根据配置回调发货接口

公共参数

应用参数：

返回参数：

示例代码：

xxxxxxxxxx
@RequestMapping("/trade.send")
    public String tradeSendCallBack(MallTradeSend mallTradeSend){
        boolean isSuccess = false;
        /**
         * 接收需要发货的订单实体类信息 自行处理之后 可修改isSuccess参数 也可自定义
         */
        WebResponse response = new WebResponse();
        if (isSuccess){
            response.setCode(200);
            response.setMessage("同步发货成功");
        }else{
            response.setCode(500);
            response.setMessage("同步发货失败");
        }
        String res = JSON.toJSONString(response);
        return res;
    }

• 10.2 店铺信息推送 API

  method:user.push POST application/x-www-form-urlencoded

店铺第一次登录时回调该接口,推送mallUserId字段

公共参数

应用参数：

返回参数：

示例代码：

xxxxxxxxxx
    /**
     * 此情况是多店铺模式 店铺第一次登录时快递助手需要回调该接口 推送mallUserId字段
     */
    @RequestMapping("/user.push")
    public String userPushCallBack(UserPush userPush){
        boolean isSuccess = false;
        /**
         * 接收店铺信息 自定义校验是否有效
         */
        WebResponse response = new WebResponse();
        if (isSuccess){
            response.setCode(200);
            response.setMessage("现在登录的是"+ userPush.getShopName()+"-"+userPush.getMallUserId());
        }else{
            response.setCode(500);
            response.setMessage("该店铺不存在");
        }
        String res = JSON.toJSONString(response);
        return res;
    }

• 10.3 店铺登录 API

  method:user.login GET application/x-www-form-urlencoded

  店铺每次登录都会回调该接口

公共参数

应用参数：

返回参数：

示例代码：

xxxxxxxxxx
 /**
     * 此情况是多店铺模式 店铺每次登录 快递助手需要校验店铺
     */
    @RequestMapping("/user.login")
    public String userLoginCallBack(UserLogin userLogin) {
        boolean isSuccess = false;
        /**
         * 接收店铺token 自定义校验是否有效
         */
        WebResponse response = new WebResponse();
        if (isSuccess){
            response.setCode(200);
            response.setMessage("该店铺有效");
        }else{
            response.setCode(500);
            response.setMessage("店铺无效或token失效");
        }
        String res = JSON.toJSONString(response);
        return res;
    }

• 10.4 消息补偿API(未实现)

  根据后台配置接口调用，如未配置则不调用。

  针对推送失败的消息，需要提供补偿API机制，让快递助手能够主动来查询失败消息列表，做一些补偿的逻辑。

  查询式获取失败的消息列表: 获取的消息不会自动确认消费成功的状态，需要调用方手动调用确认api来确认。需注意， 确认后，对接方需清理掉已确认消息

• 查询式获取失败的消息列表API:

应用参数：

响应参数：

• 失败消息批量确认Api:

应用参数：

响应参数：

11.参数列表：

快递公司列表：

订单状态：

订单退款状态：

错误码：