京東快遞上門攬件-在線下單API接口-快遞鳥

前言

近幾年來，我國電子商務(wù)交易規(guī)模越來越大庭砍，線上訂單越來越多，退換貨的情況也越來越常見混埠。退換貨環(huán)節(jié)是線上購物過程中的重要一環(huán)，也是體現(xiàn)電商平臺(tái)與商家服務(wù)水平的重要方面诗轻。同時(shí)钳宪，退換貨也是電商平臺(tái)、商家與消費(fèi)者之間最容易產(chǎn)生糾紛的環(huán)節(jié)扳炬。為了保障這個(gè)環(huán)節(jié)的服務(wù)吏颖，電商平臺(tái)推出了退換貨上門取件業(yè)務(wù)。退換貨上門取件是為買家在退貨時(shí)恨樟，提供的一種省心半醉，便捷的物流服務(wù)，當(dāng)買家購買的商品在申請(qǐng)換貨或者發(fā)起維權(quán)投訴時(shí)需要退貨劝术，不需要自己郵寄商品缩多，由物流公司安排快遞員上門取件的一項(xiàng)服務(wù)。

1.接口功能說明

2.完成前期準(zhǔn)備工作

3.API接口

4.請(qǐng)求參數(shù)（示例）

5.返回報(bào)文（示例）

6.完整請(qǐng)求的報(bào)文（URL編碼）

7.解碼后的報(bào)文

8.分步講解（C#版本）

9.關(guān)于簽名

接口功能說明

此接口用于通知快遞公司快遞員上門攬件养晋。

2.完成前期準(zhǔn)備工作

去快遞鳥官網(wǎng)免費(fèi)注冊(cè)一個(gè)賬號(hào)

免費(fèi)獲得一個(gè)apiKey(接口權(quán)限驗(yàn)證需要)

完成實(shí)名認(rèn)證流程

訂購一個(gè)免費(fèi)套餐

3.API接口

測(cè)試調(diào)用地址：http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json

正式調(diào)用地址：http://api.kdniao.com/api/dist

請(qǐng)求方式：POST

編碼格式(utf-8)：application/x-www-form-urlencoded;charset=utf-8

返回類型：JSON

調(diào)試頁面：http://kdniao.com/UserCenter/v2/SandBox/TrackQuery.aspx

調(diào)試工具：去調(diào)試（使用快遞鳥賬號(hào)登錄）

4.請(qǐng)求參數(shù)（示例）

{"OrderCode":"012657018199","PayType":"1","MonthCode":"1234567890","ExpType":"1","Sender": {"Name":"Taylor","Mobile":"15018442396","ProvinceName":"上海","CityName":"上海市","Address":"明珠路"},"Receiver": {"Company":"GCCUI","Name":"Yann","Mobile":"15018442396","ProvinceName":"北京","CityName":"北京市","ExpAreaName":"朝陽區(qū)","Address":"三里屯街道"},"Commodity": [ {"GoodsName":"鞋子","Goodsquantity":1,"GoodsWeight":1} ],"AddService": [ {"Name":"COD","Value":"1020","CustomerID":"1234567890"} ],"Weight":1,"Quantity":1,"Volume":0,"Remark":"小心輕放","StartDate":"2020-05-19 11:00:00","EndDate":"2020-05-19 15:00:00"}

5.返回報(bào)文（示例）

{"EBusinessID":"test1617571","Success":true,"Order": {"OrderCode":"112657018199","KDNOrderCode":"KDN10200519103057","ShipperCode":"JD"},"ResultCode":"100","Reason":"","UniquerRequestNumber":"1ed104ea-ff57-404f-8e12-59e1f4636920"}

6.完整請(qǐng)求的報(bào)文（URL編碼）

RequestData=%7b++++%22OrderCode%22%3a+%22012657018199%22%2c++++%22PayType%22%3a+%221%22%2c++++%22MonthCode%22%3a+%221234567890%22%2c++++%22ExpType%22%3a+%221%22%2c++++%22Sender%22%3a+%7b++++++++%22Name%22%3a+%22Taylor%22%2c++++++++%22Mobile%22%3a+%2215018442396%22%2c++++++++%22ProvinceName%22%3a+%22%e4%b8%8a%e6%b5%b7%22%2c++++++++%22CityName%22%3a+%22%e4%b8%8a%e6%b5%b7%e5%b8%82%22%2c++++++++%22Address%22%3a+%22%e6%98%8e%e7%8f%a0%e8%b7%af%22++++%7d%2c++++%22Receiver%22%3a+%7b++++++++%22Company%22%3a+%22GCCUI%22%2c++++++++%22Name%22%3a+%22Yann%22%2c++++++++%22Mobile%22%3a+%2215018442396%22%2c++++++++%22ProvinceName%22%3a+%22%e5%8c%97%e4%ba%ac%22%2c++++++++%22CityName%22%3a+%22%e5%8c%97%e4%ba%ac%e5%b8%82%22%2c++++++++%22ExpAreaName%22%3a+%22%e6%9c%9d%e9%98%b3%e5%8c%ba%22%2c++++++++%22Address%22%3a+%22%e4%b8%89%e9%87%8c%e5%b1%af%e8%a1%97%e9%81%93%22++++%7d%2c++++%22Commodity%22%3a+%5b++++++++%7b++++++++++++%22GoodsName%22%3a+%22%e9%9e%8b%e5%ad%90%22%2c++++++++++++%22Goodsquantity%22%3a+1%2c++++++++++++%22GoodsWeight%22%3a+1++++++++%7d++++%5d%2c++++%22AddService%22%3a+%5b++++++++%7b++++++++++++%22Name%22%3a+%22COD%22%2c++++++++++++%22Value%22%3a+%221020%22%2c++++++++++++%22CustomerID%22%3a+%221234567890%22++++++++%7d++++%5d%2c++++%22Weight%22%3a+1%2c++++%22Quantity%22%3a+1%2c++++%22Volume%22%3a+0%2c++++%22Remark%22%3a+%22%e5%b0%8f%e5%bf%83%e8%bd%bb%e6%94%be%22%2c++++%22StartDate%22%3a+%222020-05-19+11%3a00%3a00%22%2c++++%22EndDate%22%3a+%222020-05-19+15%3a00%3a00%22%7d&EBusinessID=test1617571&RequestType=1801&DataSign=MjRkM2ZjYWNhYzMyOGQ4M2U5ZDhjZmQxNTZjNTMxY2M%3d&DataType=2

7.解碼后的報(bào)文：

RequestData={"PayType":1,"ExpType":1,"ShipperCode":"SF","OrderCode":"300008886539888","IsNotice":1,"IsReturnPrintTemplate":1,"Commodity": [{"GoodsName":"其他","Goodsquantity":1,"GoodsWeight":0}],"Sender": {"Name":"王寶劍","Mobile":"13988888888","ProvinceName":"北京市","CityName":"北京市","ExpAreaName":"西城區(qū)","Address":"北京市西城區(qū)西直門南小街國英1號(hào)1020"},"Receiver": {"Name":"劉小刀","Mobile":"18809999999","ProvinceName":"廣東省","CityName":"深圳市","ExpAreaName":"福田區(qū)","Address":"廣東省深圳市福田區(qū)華寶一號(hào)大廈"}}&EBusinessID=test1617571&RequestType=1007&DataSign=ZDhhOTU2OTcxMWI1NGFiNTBmMzQ5NjMwNzYxZmEyMzk=&DataType=2

8.分步講解（C#版本）

請(qǐng)求數(shù)據(jù)包結(jié)構(gòu)

9 .簽名說明

關(guān)于簽名

快遞鳥和第三方電子商務(wù)公司系統(tǒng)進(jìn)行對(duì)接衬吆，有一定的安全機(jī)制。采用IP認(rèn)證加簽名的方式對(duì)接绳泉，具體方案如下：

1.防止數(shù)據(jù)被篡改在POST請(qǐng)求中會(huì)傳遞5個(gè)必須(R)參數(shù)RequestData==數(shù)據(jù)內(nèi)容(URL編碼:UTF-8)EBusinessID==用戶IDRequestType=請(qǐng)求指令類型DataSign== 數(shù)據(jù)內(nèi)容簽名：把(請(qǐng)求內(nèi)容(未編碼)+ApiKey)進(jìn)行MD5加密逊抡，然后Base64編碼，最后進(jìn)行URL(utf-8)編碼DataType==2(返回?cái)?shù)據(jù)類型為json)注：DataSign生成后零酪，對(duì)方接收到數(shù)據(jù)后冒嫡，以同樣的算法進(jìn)行簽名(推送接口RequestType為101/102不需要進(jìn)行URL編碼)，生成摘要四苇，對(duì)比兩者的摘要是否相同孝凌，如果不同，說明傳遞過程中發(fā)生數(shù)據(jù)篡改蛔琅。2.調(diào)用接口的身份認(rèn)證注冊(cè)成為快遞鳥用戶后胎许，會(huì)生成對(duì)應(yīng)的用戶ID和APIKey峻呛，用戶ID相當(dāng)于用戶名，APIKey相當(dāng)于密碼辜窑。舉例：1.假設(shè)RequestData (JSON)內(nèi)容為：{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}經(jīng)過URL(UTF-8)編碼的內(nèi)容為：%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d钩述；EBusinessID=1237100【示例ID，不可用來實(shí)際使用】APIKey=56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17【示例Key穆碎，不可用來實(shí)際使用】2.那么DataSign簽名的內(nèi)容為{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17經(jīng)過md5和base64后的內(nèi)容就為：OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=牙勘，在經(jīng)過URL(UTF-8)編碼的內(nèi)容為：OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d最終要發(fā)送的數(shù)據(jù)為：RequestType=1002&EBusinessID=1237100&RequestData =%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d&DataSign=OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d&DataType=23.接收方收到數(shù)據(jù)后，獲得EBusinessID 和RequestData和DataSign等這幾個(gè)數(shù)據(jù)所禀。4.接收方對(duì)EBusinessID 得到APIKey方面，RequestData+APIKey的數(shù)據(jù)進(jìn)行md5和base64后的內(nèi)容就為OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=5.接收方判斷簽名后的數(shù)據(jù)跟傳遞過來的DataSign是否一致，如果一致進(jìn)行業(yè)務(wù)操作色徘，如果不一致返回錯(cuò)誤恭金。

接口調(diào)用示例:

stringused ="1237100";//僅作為示例ID，不可用來實(shí)際使用//加密私鑰褂策，由快遞鳥提供stringkeyValue ="56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//僅作為示例Key横腿，不可用來實(shí)際使用//請(qǐng)求地址stringurl ="http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx";//2-jsonstringDataType ="2";//字符編碼采用UTF-8stringcharset ="UTF-8";//JSON字符串stringstringjsonStr ="json請(qǐng)求報(bào)文";//把(jsonStr+APIKey)進(jìn)行MD5加密，然后Base64編碼斤寂，最后進(jìn)行URL(utf-8)編碼datasign = HttpUtility.UrlEncode(base64(MD5(jsonStr + keyValue,"UTF-8"),"UTF-8"), Encoding.UTF8);//請(qǐng)求報(bào)文參數(shù)stringPostStr ="RequestType=1002&EBusinessID= used &RequestData=jsonStr &DataSign= datasign&DataType=DataType";//通訊協(xié)議使用Http協(xié)議Post請(qǐng)求方式stringpost =this.DoPost(url, PostStr);

C#調(diào)用方法:

///<summary>///字符串MD5加密///</summary>///<param name="str">要加密的字符串</param>///<param name="charset">編碼方式</param>///<returns>密文</returns>privatestringMD5(stringstr,stringcharset){byte[] buffer = System.Text.Encoding.GetEncoding(charset).GetBytes(str);try{? ? ? ? ? ? System.Security.Cryptography.MD5CryptoServiceProvider check;? ? ? ? ? ? check =newSystem.Security.Cryptography.MD5CryptoServiceProvider();byte[] somme = check.ComputeHash(buffer);stringret ="";foreach(byteainsomme)? ? ? ? ? ? {if(a <16)? ? ? ? ? ? ? ? ? ? ret +="0"+ a.ToString("X");elseret += a.ToString("X");? ? ? ? ? ? }returnret.ToLower();? ? ? ? }catch{throw;? ? ? ? }? ? }///<summary>///base64編碼///</summary>///<param name="str">內(nèi)容</param>///<param name="charset">編碼方式</param>///<returns></returns>privatestringbase64(String str, String charset){returnConvert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str));}///<summary>///Post方式提交數(shù)據(jù)耿焊，返回網(wǎng)頁的源代碼///</summary>///<param name="url">發(fā)送請(qǐng)求的 URL</param>///<param name="postData">請(qǐng)求報(bào)文參數(shù)</param>///<returns>遠(yuǎn)程資源的響應(yīng)結(jié)果</returns>privatestringSendPost(stringurl,stringpostData){stringresult ="";byte[] byteData = Encoding.GetEncoding("UTF-8").GetBytes(postData.ToString());try{? ? ? ? ? ? HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);? ? ? ? ? ? request.ContentType ="application/x-www-form-urlencoded";? ? ? ? ? ? request.Referer = url;? ? ? ? ? ? request.Accept ="*/*";? ? ? ? ? ? request.Timeout =30*1000;? ? ? ? ? ? request.UserAgent ="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 2.0.50727; .NET CLR 3.0.04506.648; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729)";? ? ? ? ? ? request.Method ="POST";? ? ? ? ? ? request.ContentLength = byteData.Length;? ? ? ? ? ? Stream stream = request.GetRequestStream();? ? ? ? ? ? stream.Write(byteData,0, byteData.Length);? ? ? ? ? ? stream.Flush();? ? ? ? ? ? stream.Close();? ? ? ? ? ? HttpWebResponse response = (HttpWebResponse)request.GetResponse();? ? ? ? ? ? Stream backStream = response.GetResponseStream();? ? ? ? ? ? StreamReader sr =newStreamReader(backStream, Encoding.GetEncoding("UTF-8"));? ? ? ? ? ? result = sr.ReadToEnd();? ? ? ? ? ? sr.Close();? ? ? ? ? ? backStream.Close();? ? ? ? ? ? response.Close();? ? ? ? ? ? request.Abort();? ? ? ? }catch(Exception ex)? ? ? ? {? ? ? ? ? ? result = ex.ToString();? ? ? ? }returnresult;? ? }