奇门中心
一、仓储白皮书
奇门仓储白皮书包括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×tamp=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）以前的沙箱环境不再维护了，控制台发起的新的联调请使用新的测试地址，而不是以前的沙箱地址。
