前言
近几年来，我国电子商务交易规模越来越大，线上订单越来越多，退换货的情况也越来越常见。退换货环节是线上购物过程中的重要一环，也是体现电商平台与商家服务水平的重要方面。同时，退换货也是电商平台、商家与消费者之间最容易产生纠纷的环节。为了保障这个环节的服务，电商平台推出了退换货上门取件业务。退换货上门取件是为买家在退货时，提供的一种省心，便捷的物流服务，当买家购买的商品在申请换货或者发起维权投诉时需要退货，不需要自己邮寄商品，由物流公司安排快递员上门取件的一项服务。
目录
1.接口功能说明
2.完成前期准备工作
3.API接口
4.请求参数（Headers）
5.请求参数（Body）
6.请求参数（示例）
7.返回参数（Return）
8.返回报文（示例）
9.完整请求的报文（URL编码）
10.解码后的报文
11.分步讲解（C#版本）
12.关于签名
1. 接口功能说明
- 此接口用于通知快递公司快递员上门揽件。
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
- 调试工具：去调试（使用快递鸟账号登录）
接口规则
- 请求报文中不允许出现以下特殊字符： ' " # & + < > %
- 预约时提供的收寄方信息必须真实准确。
- 用户提供的寄件地址若超出快递公司服务范围，则无快递员上门揽件。
- 因用户原因(如：恶意下单、批量下单长时间不发货等)导致快递公司投诉超过3次，快递鸟将停用此用户接口权限。
- 预约时间段：上门取件服务时间是9：00~19：00，分为不同的时间片段，9：00~11：00，11：00~13：00，13：00~15：00，15：00~17：00，17：00~19：00，在这期间根据当前时间选择可选时间段，9点-17点可预约当天上门，17点-次日9点前，预约次日上门
-
全国（除特殊区域）：
当前时间：9点前 可预约时间段：预约当天任意时间段上门
当前时间：11点前 可预约时间段：11点后预约当天任意时间段上门
当前时间：13点前 可预约时间段：13点后任意时间段上门
当前时间：15点前 可预约时间段：15点后任意时间段上门
当前时间：17点前 可预约时间段：17点-19点时间段
当前时间：17-次日9点前，预约次日任意时间段上门
特殊区域：（西北6省（甘肃、青海、宁夏、陕西、新疆、西藏），东北三省（辽宁省、吉林省、黑龙江省），海南省）
当前时间：11点前 可预约时间段：14：00~19：00之间时间段
当前时间：11-17点前 可预约时间段：次日9点后任意时间段上门
当前时间：17-次日9点前，可预约时间段：次日9点后任意时间段上门
4.请求参数（Headers）
| 参数名称 | 类型 | 说明 | 必须要求 |
| RequestData | String | 请求内容需进行URL(utf-8)编码,请求内容JSON格式，须和DataType一致 | 必填 |
| EBusinessID | String | 用户ID，查看用户ID和ApiKey | 必填 |
| RequestType | String | 请求指令类型：1801 | 必填 |
| DataSign | String | 签名数据，(Body+ApiKey)进行MD5加密，再进行Base64编码，最后进行URL(utf-8)编码 | 必填 |
| DataType | String | 求、返回数据类型：2-json ，默认Json | 选填 |
5.请求参数（Body）
|
名称 |
类型(字符长度) |
是否必须 |
描述 |
||
|
WarehouseID |
String(50) |
O |
仓库标识(备用字段) |
||
|
WarehouseAddress |
String(50) |
O |
仓库地址(备用字段) |
||
|
Callback |
String(50) |
O |
用户自定义回传字段 |
||
|
MemberID |
String(50) |
O |
ERP系统、电商平台等系统或平台类型用户的会员ID或店铺账号等唯一性标识，用于区分其用户 |
||
|
OrderCode |
String(30) |
R |
订单编号(自定义，不可重复) |
||
|
PayType |
Int(1) |
R |
运费支付方式： 1-现付，2-到付，3-月结，4-第三方付(仅SF支持) |
||
|
MonthCode |
String(20) |
C |
月结编号 |
||
|
ExpType |
Int(2) |
R |
快递类型： 1-标准路线（默认传1） |
||
|
IsReturnSignBill |
Int(1) |
O |
是否要求签回单 0-不要求，1-要求 |
||
|
Receiver |
Company |
String(30) |
O |
收件人公司 |
|
|
Name |
String(30) |
R |
收件人 |
||
|
Tel |
String(20) |
R |
电话与手机，必填一个 |
||
|
Mobile |
String(20) |
|
|||
|
PostCode |
String(10) |
O |
收件地邮编 |
||
|
ProvinceName |
String(20) |
R |
收件省 (如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等； 如是自治区，请直接传广西壮族自治区等)
|
||
|
CityName |
String(20) |
R |
收件市(如深圳市，不要缺少“市； 如是市辖区，请直接传北京市、上海市等”) |
||
|
ExpAreaName |
String(20) |
R |
收件区/县(如福田区，不要缺少“区”或“县”) |
||
|
Address |
String(100) |
R |
收件人详细地址 |
||
|
Sender |
Company |
String(30) |
O |
发件人公司 |
|
|
Name |
String(30) |
R |
发件人 |
||
|
Tel |
String(20) |
R |
电话与手机，必填一个 |
||
|
Mobile |
String(20) |
|
|||
|
PostCode |
String(10) |
O |
发件地邮编 |
||
|
ProvinceName |
String(20) |
R |
发件省 (如广东省，不要缺少“省”； 如是直辖市，请直接传北京、上海等； 如是自治区，请直接传广西壮族自治区等) |
||
|
CityName |
String(20) |
R |
发件市(如深圳市，不要缺少“市； 如是市辖区，请直接传北京市、上海市等”) |
||
|
ExpAreaName |
String(20) |
R |
发件区/县(如福田区，不要缺少“区”或“县”) |
||
|
Address |
String(100) |
R |
发件人详细地址（实际取件） |
||
|
SenderShowAddress |
String(100) |
R |
发件人详细地址<发件地址> |
||
|
StartDate |
Date |
R |
预约开始时间和结束时间，格式：YYYY-MM-DD HH24:MM:SS |
||
|
EndDate |
Date |
R |
预约开始时间和结束时间，格式：YYYY-MM-DD HH24:MM:SS |
||
|
Weight |
Double(10,3) |
O |
包裹总重量kg |
||
|
Quantity |
Int(2) |
R |
包裹数，一个包裹对应一个运单号，如果是大于1个包裹，返回则按照子母件的方式返回母运单号和子运单号 |
||
|
Volume |
Double(20,3) |
O |
包裹总体积m3 |
||
|
Remark |
String(60) |
O |
备注 |
||
|
AddService |
Name |
String(20) |
O |
||
|
Value |
String(30) |
O |
增值服务值 |
||
|
CustomerID |
String(30) |
O |
客户标识 |
||
|
Commodity |
GoodsName |
String(100) |
R |
商品名称 |
|
|
GoodsCode |
String(20) |
O |
商品编码 |
||
|
Goodsquantity |
Int(5) |
O |
商品件数 |
||
|
GoodsPrice |
Double(10) |
O |
商品价格 |
||
|
GoodsWeight |
Double(10,3) |
O |
商品重量kg |
||
|
GoodsDesc |
String(50) |
O |
商品描述 |
||
|
GoodsVol |
Double(15,3) |
O |
商品体积m3 |
||
|
PackingType |
Int(2) |
C |
包装类型(快运字段)默认为0； 0-纸，1-纤，2-木，3-托膜，4-木托，99-其他 |
||
|
DeliveryMethod |
Int(1) |
C |
送货方式(快运字段)默认为0； 0-自提，1-送货上门（不含上楼），2-送货上楼 |
||
6.请求参数（示例）
{ "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" }
7.返回参数（Return）
|
名称 |
类型(字符长度) |
是否必须 |
描述 |
|
EBusinessID |
String(10) |
R |
用户ID |
|
Order.OrderCode |
String(30) |
R |
订单编号 |
|
Order.KDNOrderCode |
String(30) |
R |
快递鸟订单编号 |
|
Order.ShipperCode |
String(10) |
R |
快递公司编码 |
|
Order.LogisticCode |
String(30) |
O |
快递单号 |
|
Success |
Bool(10) |
R |
成功与否(true/false) |
|
ResultCode |
String(5) |
R |
返回编号 |
|
Reason |
String(50) |
O |
失败原因 |
|
UniquerRequestNumber |
String(50) |
R |
唯一标识 |
8.返回报文（示例）
{ "EBusinessID": "test1617571", "Success": true, "Order": { "OrderCode": "012657018199", "KDNOrderCode": "KDN20200519103057", "ShipperCode": "STO" }, "ResultCode": "100", "Reason": "", "UniquerRequestNumber": "1ed104ea-ff57-404f-8e12-59e1f4636920" }
9.完整请求的报文（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%2
c++++%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+%2
22020-05-19+15%3a00%3a00%22%7d&EBusinessID=test1617571&RequestType=1801&DataSign=MjRkM2ZjYWNhYzMyOGQ4M2U5ZDhjZmQxNTZjNTMxY2M%3d&DataType=2
10.解码后的报文：
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
11.分步讲解（C#版本）
请求数据包结构
12 .签名说明
关于签名
快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。采用IP认证加签名的方式对接，具体方案如下：
1.防止数据被篡改 在POST请求中会传递5个必须(R)参数 RequestData==数据内容(URL编码:UTF-8) EBusinessID==用户ID RequestType=请求指令类型 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=2 3.接收方收到数据后，获得 EBusinessID 和RequestData和DataSign等这几个数据。
4.接收方对EBusinessID 得到APIKey，RequestData+APIKey的数据进行 md5和base64后的内容就为 OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE= 5.接收方判断签名后的数据跟传递过来的DataSign是否一致，如果一致进行业务操作，如果不一致返回错误。
接口调用示例:
string used = "1237100";//仅作为示例ID，不可用来实际使用 //加密私钥，由快递鸟提供 string keyValue = "56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//仅作为示例Key，不可用来实际使用 //请求地址 string url = "http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx"; //2-json string DataType = "2"; //字符编码采用UTF-8 string charset = "UTF-8"; //JSON字符串string string jsonStr = "json请求报文"; //把(jsonStr+APIKey)进行MD5加密，然后Base64编码，最后 进行URL(utf-8)编码 datasign = HttpUtility.UrlEncode(base64(MD5(jsonStr + keyValue, "UTF-8"), "UTF-8"), Encoding.UTF8); //请求报文参数 string PostStr = "RequestType=1002&EBusinessID= used &RequestData=jsonStr &DataSign= datasign&DataType=DataType"; //通讯协议使用Http协议Post请求方式 string post = this.DoPost(url, PostStr);
C#调用方法:
///<summary> /// 字符串MD5加密 ///</summary> ///<param name="str">要加密的字符串</param> ///<param name="charset">编码方式</param> ///<returns>密文</returns> private string MD5(string str, string charset) { byte[] buffer = System.Text.Encoding.GetEncoding(charset).GetBytes(str); try { System.Security.Cryptography.MD5CryptoServiceProvider check; check = new System.Security.Cryptography.MD5CryptoServiceProvider(); byte[] somme = check.ComputeHash(buffer); string ret = ""; foreach (byte a in somme) { if (a < 16) ret += "0" + a.ToString("X"); else ret += a.ToString("X"); } return ret.ToLower(); } catch { throw; } } /// <summary> /// base64编码 /// </summary> /// <param name="str">内容</param> /// <param name="charset">编码方式</param> /// <returns></returns> private string base64(String str, String charset) { return Convert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str)); } /// <summary> /// Post方式提交数据，返回网页的源代码 /// </summary> /// <param name="url">发送请求的 URL</param> /// <param name="postData">请求报文参数</param> /// <returns>远程资源的响应结果</returns> private string SendPost(string url, string postData) { string result = ""; 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 = new StreamReader(backStream, Encoding.GetEncoding("UTF-8")); result = sr.ReadToEnd(); sr.Close(); backStream.Close(); response.Close(); request.Abort(); } catch (Exception ex) { result = ex.ToString(); } return result; }