奇門ISV測試方案說明文檔.docxVIP

奇門對接方案說明文檔前言奇門對接流程：接口開發(fā)閱讀白皮書和測試說明文檔，完成所需接口的開發(fā)，不僅是接口開發(fā)，還包括對應(yīng)的業(yè)務(wù)功能。擋板自測也稱二方聯(lián)調(diào)，首先配置自測的參數(shù)，然后完成和奇門擋板的自測。三方聯(lián)調(diào)自測通過之后開始三方聯(lián)調(diào)，首先配置聯(lián)調(diào)的參數(shù)，然后進(jìn)行ERP-奇門-WMS聯(lián)調(diào)。商家驗收聯(lián)調(diào)通過后，在奇門預(yù)發(fā)環(huán)境配置真實的參數(shù)，商家發(fā)布真實商品進(jìn)行驗收。系統(tǒng)上線經(jīng)奇門確認(rèn)商家驗收通過后，可切換到奇門的正式環(huán)境，上線完成。整個奇門ERP與WMS互相調(diào)用的時序圖如下所示，分正向和反向。所謂的正向，我們約定為ERP發(fā)起，調(diào)用WMS的接口，接口實現(xiàn)方是WMS（如：商品同步接口，出庫單創(chuàng)建和入庫單創(chuàng)建接口等）；同理，反向即WMS發(fā)起，調(diào)用ERP的接口，接口實現(xiàn)方是ERP（如：出庫、入庫確認(rèn)接口，缺貨通知接口等）。在擋板自測環(huán)節(jié)：（1）ERP測試正向：ERP發(fā)起接口調(diào)用，奇門擋板會模擬WMS向ERP返回響應(yīng)；（2）ERP測試反向，需要ERP模擬WMS向自己發(fā)起調(diào)用請求，測試自己的ERP系統(tǒng)是否能接收到請求并正確響應(yīng)。WMS擋板自測同理。如果代碼還沒有實現(xiàn)調(diào)用的方法，可以利用chrome瀏覽器或者火狐瀏覽器的插件Rest Client來測試。關(guān)于Rest Client安裝，可以在瀏覽器應(yīng)用中心里搜索rest client關(guān)鍵字，隨便安裝一個即可，chrome瀏覽器下載應(yīng)用有時候網(wǎng)絡(luò)不暢，換個時間段多試幾次，火狐相對好一些。下載界面如下：測試的方法如下：1. 關(guān)于配置參數(shù)首先解釋一下奇門的環(huán)境和ISV的環(huán)境。奇門總共有三個環(huán)境，分別是日常環(huán)境（即沙箱環(huán)境），預(yù)發(fā)環(huán)境和線上環(huán)境，其中日常環(huán)境配置的都是測試數(shù)據(jù)，預(yù)發(fā)和線上配置的都是真實數(shù)據(jù)。對接過程中，參數(shù)配置遵循的原則如下。其中，商家驗收通過之后，奇門確認(rèn)沒有問題，可以切換到線上環(huán)境：在奇門的參數(shù)配置中主要涉及到下面幾個重要參數(shù)：1) ERP_APPKEY2) ERP_URL3) WMS_APPKEY4) WMS_URL5) CUSTOMER_ID奇門的作用是針對不同的應(yīng)用（比如一個ERP）發(fā)起的請求，正確的路由給其對應(yīng)的另一方（比如對應(yīng)的WMS），如下圖。那么奇門路由的策略是怎樣的呢？下面是一段標(biāo)準(zhǔn)的調(diào)用URL的例子：/router/qimen/service?method=*×tamp=2015-04-26 20:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*其中，各個字段的含義，請見下表：字段名含義域名/router/qimen/service是奇門測試環(huán)境的域名地址，自測和聯(lián)調(diào)的時候都是使用這個域名，注意，千萬不要直接寫成對方ISV應(yīng)用的服務(wù)地址Method調(diào)用的方法timestamp使用當(dāng)前調(diào)用接口的時間，做encode編碼 format暫時只支持xmlappkey調(diào)用方自己的appkey，即來源appkeysignMD5加密，加密策略參看附錄1customerId是倉儲為這個用戶分配的唯一的用戶帳號，自測和聯(lián)調(diào)的時候由奇門統(tǒng)一分配，等到切到預(yù)發(fā)和正式環(huán)境的時候，使用倉儲自己分配真實的值，注意，對于一個WMS，這個customerId一定要保證唯一言歸正傳，奇門如何根據(jù)這一段URL來做路由的呢？奇門首先會根據(jù)調(diào)用url中的customerId來找這個用戶配置的ERP信息和對應(yīng)的WMS信息，因此customerId一定要唯一。需要配置參數(shù)的地方有三個，這里分別介紹一下：注：Q:什么是沙箱appkey，怎么獲?。緼:登陸開放平臺，進(jìn)入控制臺，找到對接奇門要使用的應(yīng)用，應(yīng)用設(shè)置里有沙箱環(huán)境的參數(shù)。2. 關(guān)于擋板自測2.1 ERP端：2.1.1 ERP自測正向調(diào)用ERP端做正向接口調(diào)用，奇門測試擋板會模仿WMS返回信息，擋板自測調(diào)用地址如下(只需修改紅色標(biāo)示的method方法字段)：/router/qimen/service?method=taobao.qimen.entryorder.cancel×tamp=2015-04-26 20:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是ERP的appkey；sign簽名:采用md5不可逆加密方法，具體操作見附錄2；v字段：我們是通過v來區(qū)分1.0版本（白皮書v1.5）和2.0版本（白皮書v2.0），不同的v，調(diào)用的奇門測試擋板是不一樣的，請注意！暫時只有1.0和2.0兩種。以后進(jìn)行三方聯(lián)調(diào)之后，v的值如何定義由雙方自行協(xié)商了。2.1.2 ERP自測反向調(diào)用ERP需模擬WMS發(fā)起請求，訪問url和WMS調(diào)用奇門的url一致，奇門測試環(huán)境調(diào)用地址如下，其中，需要修改紅色標(biāo)示的method方法字段：/router/qimen/service?method=taobao.qimen.entryorder.report×tamp=2015-04-26 00:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是wms的appkey；2.2. WMS端：2.2.1 WMS自測正向調(diào)用WMS需模擬ERP發(fā)起請求，訪問url和ERP調(diào)用奇門的url一致，奇門測試環(huán)境調(diào)用地址如下，其中，需要修改紅色標(biāo)示的method方法字段：/router/qimen/service?method= taobao.qimen.entryorder.query×tamp=2015-04-26 00:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是ERP的appkey。2.2.2 WMS自測反向流程奇門擋板會模仿ERP返回信息，奇門測試環(huán)境調(diào)用地址如下(只需修改紅色標(biāo)示的method方法字段)：/router/qimen/service?method=taobao.qimen.entryorder.report×tamp=2015-04-26%2000:00:07&format=xml&app_key=*&v=2.0&sign=abc&sign_method=md5&customerId=*注：app_key是WMS的appkey；附錄1 sign簽名算法：我們用ERP調(diào)用奇門URL演示加密算法：/router/qimen/service?method=taobao.qimen.entryorde.rquery×tamp=2015-04-26 00:00:07&format=xml&app_key=testerp_appkey&v=2.0&sign=abc&sign_method=md5&customerId=stub-cust-code1、輸入?yún)?shù)為method= taobao.qimen.entryorder.query timestamp=2015-04-26 00:00:07 format=xml app_key= testerp_appkey v=2.0 sign_method=md5 customerId =test2、按首字母升序排列app_key= testerp_appkeycustomerId = stub-cust-codeformat=xmlmethod= taobao.qimen.entryorder.querysign_method=md5 timestamp=2015-04-26 00:00:07 v=2.0 3、連接字符串連接參數(shù)名與參數(shù)值,并在首尾加上secret，此處假設(shè)secret=test，如下： testapp_keytesterp_appkeycustomerIdstub-cust-codeformatxmlmethodtaobao.qimen.entryorder.querysign_methodmd5timestamp2015-04-26 00:00:07v2.0bodytest其中：body用請求中的body內(nèi)容代替4、生成簽名 sign32位大寫MD5值- D06D88CB34B2EC0E5C9BAB396C9542B65、拼裝URL請求將所有參數(shù)值轉(zhuǎn)換為UTF-8編碼，然后拼裝，通過瀏覽器訪問該地址，即成功調(diào)用一次接口，如下:/router/qimen/service?method=taobao.qimen.entryorder.query×tamp=2015-04-26 00:00:07&format=xml&app_key=testerp_appkey&v=2.0&sign= D06D88CB34B2EC0E5C9BAB396C9542B6 &sign_method=md5&customerId=stub-cust-code奇門對于sign簽名的校驗邏輯：ERP通過自己的secret做了sign簽名，奇門在收到請求的時候，同時也用這個ERP的secret去做簽名校驗，校驗通過之后，再去拿即將路由到的WMS的secret進(jìn)行重新加密，然后將新的sign發(fā)給WMS，由于WMS只知道自己的secret簽名，所以奇門在sign上做了一次轉(zhuǎn)換，這樣WMS在收到的請求中就可以用自己的secret做一次簽名校驗。簽名算法示例：package md5;import java.io.UnsupportedEncodingException;import .URLDecoder;import java.security.MessageDigest;import java.security.NoSuchAlgorithmException;import java.util.Arrays;import java.util.HashMap;import java.util.Map;/* * Created by jiqian.zzp on 2015/7/6. */public class QimenSign public static void main(String args) String url = /top/router/qimen/service? + method=your_method& + timestamp=2015-04-26%2000:00:07& + format=xml& + app_key=your_appkey& + v=your_version& + sign=your_sign& + sign_method=md5& + customerId=your_customerId; String body = your_body; String secretKey = your_secretKey; QimenSign sign = new QimenSign(); String md5 = sign.sign(url, body, secretKey); System.out.println(md5);/6A4B6FCFAFE80280565406E110C27DC8 public String sign(String url, String body, String secretKey) Map params = getParamsFromUrl(url); / 1. 第一步，確保參數(shù)已經(jīng)排序 String keys = params.keySet().toArray(new String0); Arrays.sort(keys); / 2. 第二步，把所有參數(shù)名和參數(shù)值拼接在一起(包含body體) String joinedParams = joinRequestParams(params, body, secretKey, keys); /your_secretKeyapp_keyyour_appkeycustomerIdyour_customerIdformatxmlmethodyour_methodsign_methodmd5timestamp2015-04-26 00:00:07vyour_versionyour_bodyyour_secretKey System.out.println(joinedParams); / 3. 第三步，使用加密算法進(jìn)行加密（目前僅支持md5算法） String signMethod = params.get(sign_method); if (!md5.equalsIgnoreCase(signMethod) /TODO return null; byte abstractMesaage = digest(joinedParams); / 4. 把二進(jìn)制轉(zhuǎn)換成大寫的十六進(jìn)制 String sign = byte2Hex(abstractMesaage); return sign; private Map getParamsFromUrl(String url) Map requestParams = new HashMap(); try String fullUrl = URLDecoder.decode(url, UTF-8); String urls = fullUrl.split(?); if (urls.length = 2) String paramArray = urls1.split(&); for (String param : paramArray) String params = param.split(=); if (params.length = 2) requestParams.put(params0, params1); catch (UnsupportedEncodingException e) / TODO return requestParams; private String byte2Hex(byte bytes) char hexDigits = 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F ; int j = bytes.length; char str = new charj * 2; int k = 0; for (byte byte0 : bytes) strk+ = hexDigitsbyte0 4 & 0xf; strk+ = hexDigitsbyte0 & 0xf; return new String(str); private byte digest(String message) try MessageDigest md5Instance = MessageDigest.getInstance(MD5); md5Instance.update(message.getBytes(UTF-8); return md5Instance.digest(); catch (UnsupportedEncodingException e) /TODO return null; catch (NoSuchAlgorithmException e) /TODO return null; private String joinRequestParams(Map params, String body, String secretKey, String sortedKes) StringBuilder sb = new StringBuilder(secretKey); / 前面加上secretKey for (String key : sortedKes) if (sign.equals(key) continue; / 簽名時不計算sign本身 else String value = para