京东快递上门揽件-在线下单API接口-快递鸟

前言

近几年来，我国电子商务交易规模越来越大，线上订单越来越多，退换货的情况也越来越常见。退换货环节是线上购物过程中的重要一环，也是体现电商平台与商家服务水平的重要方面。同时，退换货也是电商平台、商家与消费者之间最容易产生纠纷的环节。为了保障这个环节的服务，电商平台推出了退换货上门取件业务。退换货上门取件是为买家在退货时，提供的一种省心，便捷的物流服务，当买家购买的商品在申请换货或者发起维权投诉时需要退货，不需要自己邮寄商品，由物流公司安排快递员上门取件的一项服务。

目录

1.接口功能说明

2.完成前期准备工作

3.API接口

4.请求参数（示例）

5.返回报文（示例）

6.完整请求的报文（URL编码）

7.解码后的报文

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

9.关于签名

接口功能说明

此接口用于通知快递公司快递员上门揽件。

2.完成前期准备工作

去快递鸟官网免费注册一个账号

免费获得一个apiKey(接口权限验证需要)

完成实名认证流程

订购一个免费套餐

3.API接口

测试调用地址：http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json

正式调用地址：http://api.kdniao.com/api/dist

请求方式：POST

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

返回类型：JSON

调试页面：http://kdniao.com/UserCenter/v2/SandBox/TrackQuery.aspx

调试工具：去调试（使用快递鸟账号登录）

4.请求参数（示例）

{"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":"朝阳区","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.返回报文（示例）

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

6.完整请求的报文（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.解码后的报文：

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":"西城区","Address":"北京市西城区西直门南小街国英1号1020"},"Receiver": {"Name":"刘小刀","Mobile":"18809999999","ProvinceName":"广东省","CityName":"深圳市","ExpAreaName":"福田区","Address":"广东省深圳市福田区华宝一号大厦"}}&EBusinessID=test1617571&RequestType=1007&DataSign=ZDhhOTU2OTcxMWI1NGFiNTBmMzQ5NjMwNzYxZmEyMzk=&DataType=2

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

请求数据包结构

9 .签名说明

关于签名

快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。采用IP认证加签名的方式对接，具体方案如下：

1.防止数据被篡改在POST请求中会传递5个必须(R)参数RequestData==数据内容(URL编码:UTF-8)EBusinessID==用户IDRequestType=请求指令类型DataSign== 数据内容签名：把(请求内容(未编码)+ApiKey)进行MD5加密，然后Base64编码，最后进行URL(utf-8)编码DataType==2(返回数据类型为json)注：DataSign生成后，对方接收到数据后，以同样的算法进行签名(推送接口RequestType为101/102不需要进行URL编码)，生成摘要，对比两者的摘要是否相同，如果不同，说明传递过程中发生数据篡改。2.调用接口的身份认证注册成为快递鸟用户后，会生成对应的用户ID和APIKey，用户ID相当于用户名，APIKey相当于密码。举例：1.假设RequestData (JSON)内容为：{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}经过URL(UTF-8)编码的内容为：%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d；EBusinessID=1237100【示例ID，不可用来实际使用】APIKey=56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17【示例Key，不可用来实际使用】2.那么DataSign签名的内容为{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17经过md5和base64后的内容就为：OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=，在经过URL(UTF-8)编码的内容为：OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d最终要发送的数据为：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.接收方收到数据后，获得EBusinessID 和RequestData和DataSign等这几个数据。4.接收方对EBusinessID 得到APIKey，RequestData+APIKey的数据进行md5和base64后的内容就为OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=5.接收方判断签名后的数据跟传递过来的DataSign是否一致，如果一致进行业务操作，如果不一致返回错误。

接口调用示例:

stringused ="1237100";//仅作为示例ID，不可用来实际使用//加密私钥，由快递鸟提供stringkeyValue ="56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//仅作为示例Key，不可用来实际使用//请求地址stringurl ="http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx";//2-jsonstringDataType ="2";//字符编码采用UTF-8stringcharset ="UTF-8";//JSON字符串stringstringjsonStr ="json请求报文";//把(jsonStr+APIKey)进行MD5加密，然后Base64编码，最后 进行URL(utf-8)编码datasign = HttpUtility.UrlEncode(base64(MD5(jsonStr + keyValue,"UTF-8"),"UTF-8"), Encoding.UTF8);//请求报文参数stringPostStr ="RequestType=1002&EBusinessID= used &RequestData=jsonStr &DataSign= datasign&DataType=DataType";//通讯协议使用Http协议Post请求方式stringpost =this.DoPost(url, PostStr);

C#调用方法:

///

///字符串MD5加密///

///要加密的字符串///编码方式///密文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;        }    }///

///base64编码///

///内容///编码方式///privatestringbase64(String str, String charset){returnConvert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str));}///

///Post方式提交数据，返回网页的源代码///

///发送请求的 URL///请求报文参数///远程资源的响应结果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;    }