文档中心 > 商家经营工具-开发指引

奇门仓储接入说明

更新时间：2024/11/20 访问次数：208993

一、仓储白皮书
二、前言
三、业务背景
四、奇门对接方案
五、API协议
六、ITC注意事项

一、仓储白皮书

奇门仓储白皮书包括API业务说明以及签名算法规范等完整说明，点此查看。

二、前言

1. 对接奇门前需在服务市场发布应用，具体如下：

2. WMS：走“仓储管理系统（WMS）”类目应用接入流程，取得应用appkey，若已发布过请忽略。发布流程点此查看；

3. ERP（第三方服务商）：走“企业ERP”类目应用接入流程，取得应用appkey，若以前发布过请忽略（当前ERP入驻审核较严）。发布流程点此查看；

4. ERP（商家自研系统）：申请地址点击查看；

5. 非淘ERP：非淘ERP要与WMS通过奇门对接，需要申请应用appkey，不处理淘系订单。申请地址点击查看；

6. 奇门仓储业务API接口说明文档：点击查看；

7. 接口报错怎么办？有任何问题请先自查，遇到的问题这里都会找到解决方案：点此查看奇门异常排查手册；其他日常问题咨询请到支持中心进行提问：点此进入开放平台支持中心。其他问题可以加钉钉群答疑群咨询：108485004500；

8. 奇门API接口请务必使用SDK包，下载SDK请移步开放平台-控制台-应用管理，申请“**奇门仓储业务**”API权限包。

三、业务背景

当前奇门项目支持ERP-WMS系统标准化对接，通过构建系统之间标准通信协议来实现不同系统之间的打通。

四、奇门对接方案

奇门对接流程如下：

1. 接口开发

阅读奇门仓储API说明文档，完成所需接口的开发，只需要开发自己需要使用的接口。

2. 服务验收

也称和挡板联调，目的是让第一次对接奇门的开发者了解奇门的对接逻辑，如果您是ERP，则平台会模拟WMS和您完成自测。您需要配置服务地址，执行验收即可。

（1）对于您实现的接口：系统会发起接口调用，需要经过系统的验收，验收内容有编码测试和验签测试等，具体参考三方互通使用手册自测一项。

（2）对于您调用的接口：在没跟服务商联调之前，需要您调用到挡板，测试链路是否正确。具体参考三方互通使用手册挡板一项。

奇门测试环境地址：http://qimen.api.taobao.com/top/router/qmtest

注意！如果您使用过ITC，那需要您把测试地址从沙箱地址改为上面的地址。

3. 三方联调

自测通过之后开始三方联调（ERP-奇门-WMS），联调需要重新配置联调参数，customerId由奇门临时分配，需要ERP发起联调申请，WMS来接收申请。参考三方互通使用手册联调一项。

奇门地址和自测时候一样：http://qimen.api.taobao.com/top/router/qmtest。

4. 商家验收&上线

联调通过后，上线需要配置正式参数，customerId是WMS为商家分配的唯一的真实账号，商家发布真实商品进行验收。

参考三方互通使用手册上线一项。

奇门正式环境地址：http://qimen.api.taobao.com/router/qimen/service。

5. 控制台操作文档

上述步骤的详细操作请参考文档《三方互通使用手册》。

五、API协议

1. 环境

正式环境

qimen.api.taobao.com/router/qimen/service

测试环境

qimen.api.taobao.com/router/qmtest

注：不再支持沙箱环境

2. 通讯协议

1）通讯协议：只支持http 和 https；
2）请求方法：只支持post，Content-Type支持类型为application/xml和text/xml；
3）编码：请求参数及返回结果都使用UTF-8字符集进行编码，即使您在xml中指定了别的编码也不会生效。
4）请求参数：

a. 系统参数，系统参数如下表格：

参数名	是否必须	说明
method	必须	方法名
timestamp	必须	时间戳，格式为yyyy-MM-dd HH:mm:ss
format	必须	仓储仅支持xml
app_key	必须	您的应用名
sign	必须	签名字符串
sign_method	必须	签名算法，支持md5和hmac-sha256
tb_eagleeyex_t	非必须	压测标
customerid	必须	货主id
v	必须	目前仅支持2.0

系统参数要求放在query中，举个例子：

http://qimen.api.taobao.com/top/router/qimen/service?app_key=123456&customerId=123456&format=xml&method=taobao.qimen.deliveryorder.create&sign=2668531FB44D9D6D5027DE76A6981CA5&sign_method=md5&timestamp=2019-04-26+11%3a38%3a36&v=2.0

b. 业务参数，业务报文请以原生报文形式放在body体中。

3. 签名算法

1）如果您使用的是SDK，则生成签名对您来说是透明的。

2）签名算法如下，另外可以使用控制台的运维工具-签名辅助工具来协助您完成签名算法。

/**
     * 
     * 
     * @param params
     *            所有字符型的TOP请求参数
     * @param body
     *            请求主体内容
     * @param secret
     *            签名密钥
     * @param signMethod
     *            签名方法，目前支持：空（老md5)、md5, hmac_md5三种
     * @return 签名
     */
    public static String signTopRequest(Map<String, String> params, String body, String secret, String signMethod)
            throws IOException {
        // 第一步：检查参数是否已经排序
        String[] keys = params.keySet().toArray(new String[0]);
        Arrays.sort(keys);
        // 第二步：把所有参数名和参数值串在一起
        StringBuilder query = new StringBuilder();
        if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
            query.append(secret);
        }
        for (String key : keys) {
            String value = params.get(key);
            if (StringUtils.areNotEmpty(key, value)) {
                query.append(key).append(value);
            }
        }
        // 第三步：把请求主体拼接在参数后面
        if (body != null) {
            query.append(body);
        }
        // 第四步：使用MD5/HMAC加密
        byte[] bytes;
        if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
            bytes = encryptHMAC(query.toString(), secret);
        } else if (Constants.SIGN_METHOD_HMAC_SHA256.equals(signMethod)) {
            bytes = encryptHMACSHA256(query.toString(), secret);
        }  else {
            query.append(secret);
            bytes = encryptMD5(query.toString());
        }
        // 第五步：把二进制转化为大写的十六进制
        return byte2hex(bytes);
    }

4. 验签

后端服务在接收请求的时候要求对请求做验签，确保请求是来自奇门的而不是其他的非法请求。

验签推荐使用sdk的SpiUtils工具类的checkSign方法来做验签，如果您自己封装的算法，则参考上文的签名算法。

六、ITC注意事项

如果您没使用过ITC产品，那么可以跳过下文，如果您以前是在itc上操作的，那么需要您阅读一下以下注意事项。

1）测试地址不同；

2）以前的沙箱环境不再维护了，控制台发起的新的联调请使用新的测试地址，而不是以前的沙箱地址。

FAQ

关于此文档暂时还没有FAQ

有用(6) 我要提问

淘宝开放平台

商家经营工具-开发指引