**
围绕逆向物流退换货问题的解决方案
**
快递鸟集成了多家物流快递公司渠道,发货用户在线一键下单,快递小哥APP接单,并门到门取件的全流程在线服务,价格透明,服务有保障,过程可追踪。给电商平台提供完整的退货寄件物流解决方案,退货用户只需在电商平台一键退货呼叫快递员门到门取件即可,解决平台的逆向物流管理问题,比如退货后的退款核定监控等。为集团企业和直接发货用户解决集中的对账结算以及内部的快递集中管理问题。快递鸟门到门取件已覆盖全国300多个主要城市,38400多个区县,快递鸟多级地址库,精准的订单路由和分发能力,确保发件人和快递小哥的接单匹配,支持取件时间预约,2小时门到门取件让服务
快递鸟-物流数据领导品牌,专注于企业级物流API技术研发,旨在快速低成本帮助电商平台、零售商、金融机构、制造商、TMT等建设更安全、更智能的物流管理体系,定制化专业的物流解决方案。快递鸟具有强大的渠道服务能力,目前集合了全球600家物流公司系统,统一标准接口,涵盖快递、物流、快运、同城配等绝大部分国内快递,包括通达,顺丰,京东,邮政等主流快递物流公司,支持EMS、Fedex、TNT、UPS等国际快递,提供轨迹数据,电子面单,在线下单等服务,快递鸟接口的及时准确稳定性获得了用户的一致好评,腾讯、12306、跟谁学、建设银行、美团、唯品会、拼多多、贝店、云集、快手电商等知名企业都在使用快递鸟提供的数据服务,快递鸟每天上千万次的数据服务能力及上百万等订单服务支持能力,为企业提供运营监控管理系统,保障日常运营,帮助企业打通物流环节,提升物流服务能力。
“2小时门到门准时取”击中退换货痛点
电商技术解密之售后退换货流程设计
逆向物流退换货服务解决方案之技术对接API教程
为了照顾刚入门的技术人员,我会分享源代码,把源码复制到你的项目上,就能快速完成上门退货接口对接.更适合刚入门的菜鸟,这里我们以申通快递的上门退货服务为例来讲解,调用快递鸟提供的上门取件API标准接口,成功调用后,申通快递员会上门服务,同时支持申通快递单号的轨迹查询。快递鸟api接口不区分开发语言,支持Java,C#,PHP,Python,ObjectC等开发语言的程序调用。下面具体讲解实现过程.
3.1.完成前期准备工作
去快递鸟官网免费注册一个账号
免费获得一个apiKey(接口权限验证需要),
完成实名认证流程
订购一个免费套餐
3.2.API接口
测试调用地址:http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json
正式调用地址:https://api.kdniao.com/api/OOrderService
请求方式:POST
编码格式(utf-8):application/x-www-form-urlencoded;charset=utf-8
返回类型:JSON
调试页面:http://kdniao.com/UserCenter/v2/SandBox/TrackQuery.aspx
3.3.系统请求参数(Headers)
参数名称 | 类型 | 说明 | 必须要求 |
---|---|---|---|
RequestData | String | 请求内容需进行URL(utf-8)编码。请求内容JSON格式,须和DataType一致。 | R |
EBusinessID | String | 商户ID,请在我的服务页面查看。 | R |
RequestType | String | 请求指令类型:1801(下单接口)1802(取消接口) | R |
DataSign | String | 数据内容签名:把(请求内容(未编码)+AppKey)进行MD5加密,然后Base64编码,最后 进行URL(utf-8)编码。详细过程请查看Demo。 | R |
DataType | String | 请求、返回数据类型:只支持JSON格式 | R |
备注:R-必填(Required),O-可选(Optional),C-报文中该参数在一定条件下可选
3.4.下单请求参数(Body)
参数名称 | 类型 | 说明 | 必须要求 |
---|---|---|---|
WarehouseID | String | 仓库标识 | O |
WarehouseAddress | String | 仓库地址 | O |
CallBack | String | 商户标识 | O |
MemberID | String | 会员标识 | O |
OrderCode | String | 订单编号 | R |
PayType | Int | 邮费支付方式:1-现付,2-到付,3-月结,4-第三方支付 | R |
MonthCode | String | 月结编码 | C |
ExpType | Int | 快递类型:1-标准快件 | R |
IsReturnSignBill | Int | 签收回单:1-需要,0-不需要,默认为0 | O |
Receiver | |||
Company | String | 收件人公司 | O |
Name | String | 收件人 | R |
Tel | String | 电话与手机,必填一个 | R |
Mobile | String | ||
PostCode | String | 收件人邮编 | O |
ProvinceName | String | 收件省(如广东省,不要缺少“省”) | R |
CityName | String | 收件市(如深圳市,不要缺少“市”) | R |
ExpAreaName | String | 收件区(如福田区,不要缺少“区”或“县”) | O |
Address | String | 收件人详细地址 | R |
Sender | |||
Company | String | 发件人公司 | O |
Name | String | 发件人 | R |
Tel | String | 电话与手机,必填一个 | R |
Mobile | String | ||
PostCode | String | 发件人邮编 | O |
ProvinceName | String | 发件省(如广东省,不要缺少“省”) | R |
CityName | String | 发件市(如深圳市,不要缺少“市”) | R |
ExpAreaName | String | 发件区(如福田区,不要缺少“区”或“县”) | O |
Address | String | 发件人详细地址(实际取件) | R |
SenderShowAddress | String | 发件人详细地址 | O |
StartDate | String | 上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化 | O |
EndDate | String | 上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化 | O |
Weight | Double | 物品总重量kg | O |
Quantity | Int | 件数/包裹数 | O |
Volume | Double | 物品总体积m3 | O |
Remark | String | 备注 | O |
AddService | |||
Name | String | 增值服务名称 | O |
Value | String | 增值服务值 | O |
CustomerID | String | 客户标识(选填) | O |
Commodity | |||
GoodsName | String | 商品名称 | R |
GoodsCode | String | 商品编码 | O |
Goodsquantity | Int | 商品数量 | O |
GoodsPrice | Decimal | 商品价格 | O |
GoodsWeight | Decimal | 商品重量 | O |
GoodsDesc | String | 商品描述 | O |
GoodsVol | Double | 商品体积m3 | O |
PackingType | Int | 包装类型:包装类型(快运字段)默认为 0; 0- 纸 1- 纤 2- 木 3- 托膜 4- 木托 99-其他 | O |
DeliveryMethod | Int | 送货方式:0-自提,1-送货上门(不含上楼)2-送货上楼。(适用于快运类型订单,物流公司可能会收取费用),默认为0 | O |
3.5.下单返回参数(Return)
参数名称 | 类型 | 说明 | 必须要求 |
---|---|---|---|
EBusinessID | String | 用户ID | R |
Order | |||
OrderCode | String | 订单编号 | R |
KDNOrderCode | String | 快递鸟订单编号 | R |
ShipperCode | String | 快递公司编码 | R |
LogisticCode | String | 快递单号 | O |
Success | Bool | 成功与否 | R |
ResultCode | String | 结果编码 | R |
Reason | String | 失败原因 | O |
UniquerRequestNumber | String | 唯一标识 | R |
3.6.下单请求参数(Json示例)
{
"OrderCode":"012657018199",
"ShipperCode":"STO",
"PayType":1,
"MonthCode":"1234567890",
"ExpType":1,
"Sender":{
"Company":"LV",
"Name":"Taylor",
"Mobile":"15018442396",
"ProvinceName":"上海",
"CityName":"上海市",
"ExpAreaName":"青浦区",
"Address":"明珠路"
},
"Receiver":{
"Company":"GCCUI",
"Name":"Yann",
"Mobile":"15018442396",
"ProvinceName":"北京",
"CityName":"北京市",
"ExpAreaName":"朝阳区",
"Address":"三里屯街道"
},
"Commodity":[
{
"GoodsName":"鞋子",
"Goodsquantity":1,
"GoodsWeight":1
}
],
"Weight":1,
"Quantity":1,
"Volume":0,
"Remark":"小心轻放"
}
3.7.下单请求完整报文(URL编码)
RequestData=%7b%0d%0a++++%22OrderCode%22%3a%22012657018199%22%2c%0d%0a++++%22ShipperCode%22%3a%22STO%22%2c%0d%0a++++%22PayType%22%3a1%2c%0d%0a++++%22MonthCode%22%3a%221234567890%22%2c%0d%0a++++%22ExpType%22%3a1%2c%0d%0a++++%22Sender%22%3a%7b%0d%0a++++++++%22Company%22%3a%22LV%22%2c%0d%0a++++++++%22Name%22%3a%22Taylor%22%2c%0d%0a++++++++%22Mobile%22%3a%2215018442396%22%2c%0d%0a++++++++%22ProvinceName%22%3a%22%e4%b8%8a%e6%b5%b7%22%2c%0d%0a++++++++%22CityName%22%3a%22%e4%b8%8a%e6%b5%b7%e5%b8%82%22%2c%0d%0a++++++++%22ExpAreaName%22%3a%22%e9%9d%92%e6%b5%a6%e5%8c%ba%22%2c%0d%0a++++++++%22Address%22%3a%22%e6%98%8e%e7%8f%a0%e8%b7%af%22%0d%0a++++%7d%2c%0d%0a++++%22Receiver%22%3a%7b%0d%0a++++++++%22Company%22%3a%22GCCUI%22%2c%0d%0a++++++++%22Name%22%3a%22Yann%22%2c%0d%0a++++++++%22Mobile%22%3a%2215018442396%22%2c%0d%0a++++++++%22ProvinceName%22%3a%22%e5%8c%97%e4%ba%ac%22%2c%0d%0a++++++++%22CityName%22%3a%22%e5%8c%97%e4%ba%ac%e5%b8%82%22%2c%0d%0a++++++++%22ExpAreaName%22%3a%22%e6%9c%9d%e9%98%b3%e5%8c%ba%22%2c%0d%0a++++++++%22Address%22%3a%22%e4%b8%89%e9%87%8c%e5%b1%af%e8%a1%97%e9%81%93%22%0d%0a++++%7d%2c%0d%0a++++%22Commodity%22%3a%5b%0d%0a++++++++%7b%0d%0a++++++++++++%22GoodsName%22%3a%22%e9%9e%8b%e5%ad%90%22%2c%0d%0a++++++++++++%22Goodsquantity%22%3a1%2c%0d%0a++++++++++++%22GoodsWeight%22%3a1%0d%0a++++++++%7d%0d%0a++++%5d%2c%0d%0a++++%22Weight%22%3a1%2c%0d%0a++++%22Quantity%22%3a1%2c%0d%0a++++%22Volume%22%3a0%2c%0d%0a++++%22Remark%22%3a%22%e5%b0%8f%e5%bf%83%e8%bd%bb%e6%94%be%22%0d%0a%7d%0d%0a&EBusinessID=1365742&RequestType=1801&DataSign=ZTcxNTBkNjNhNjkxYjkzMGViNDcxZTRjNzc3NzlkNjI%3d&DataType=2
3.8.下单成功返回报文(Json示例)
{
"EBusinessID":"1237100",
"Success":true,
"Order":{
"OrderCode":"012657018199",
"KDNOrderCode":"KDN012657018199",
"ShipperCode":" STO",
"LogisticCode":"615123456789"
},
"ResultCode":"100",
"Reason":""
}
实际业务会存在,取消操作功能,客户下的订单,由于多方原因需要取消下单,为此快递鸟也提供了取消上门取件的接口,我们来讲解一下如何调用。
3.9.取消请求参数(Body)
参数名称 | 类型 | 说明 | 必须要求 |
---|---|---|---|
ShipperCode | String(20) | R | 快递鸟接口支持快递公司编码 |
OrderCode | String(30) | R | 订单编号(自定义,不可重复) |
LogisticCode | String(30) | O | 快递单号 |
Reason | String(100) | O | 取消原因 |
3.10.取消返回参数(Return)
参数名称 | 类型 | 说明 | 必须要求 |
---|---|---|---|
EBusinessID | String(10) | R | 用户ID |
Success | Bool(10) | R | 成功与否(true/false) |
ResultCode | String(5) | R | 返回编号 |
Reason | String(50) | O | 失败原因 |
3.11取消请求参数(Json示例)
{
"OrderCode": "012657018199",
"ShipperCode": "SF",
}
3.12取消成功返回报文(Json示例)
{
"EBusinessID": "1237100",
"Success": true,
"ResultCode": "100",
}
3.13.分步讲解(C#版本)
-
请求数据包结构
-
C#调用代码示例
//电商ID
string eEBusinessID = "test1617571";
//电商加密私钥,快递鸟提供,注意保管,不要泄漏
string appKey= "554343b2-7252-439b-b4eb-1af42c8f2175";
//请求url
string reqURL = "http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json";
//请求指令
string reqType="1801";
//2-json
string dataType = "2";
//字符编码采用UTF-8
string charset = "UTF-8";
//JSON字符串
string string jsonStr = "{
\"OrderCode\":\"012657018199\",
\"ShipperCode\":\"STO\",
\"PayType\":1,
\"MonthCode\":\"1234567890\",
\"ExpType\":1,
\"Sender\":{
\"Company\":\"LV\",
\"Name\":\"Taylor\",
\"Mobile\":\"15018442396\",
\"ProvinceName\":\"上海\",
\"CityName\":\"上海市\",
\"ExpAreaName\":\"青浦区\",
\"Address\":\"明珠路\"
},
\"Receiver\":{
\"Company\":\"GCCUI\",
\"Name\":\"Yann\",
\"Mobile\":\"15018442396\",
\"ProvinceName\":\"北京\",
\"CityName\":\"北京市\",
\"ExpAreaName\":\"朝阳区\",
\"Address\":\"三里屯街道\"
},
\"Commodity\":[
{
\"GoodsName\":\"鞋子\",
\"Goodsquantity\":1,
\"GoodsWeight\":1
}
],
\"Weight\":1,
\"Quantity\":1,
\"Volume\":0,
\"Remark\":\"小心轻放\"
}" ;
//把(jsonStr+APIKey)进行MD5加密
string md5Str=MD5(jsonStr + apiKey, charset);
//把md5Str 进行Base64编码
string base64Str=base64(md5Str,charset);
//进行URL编码 (utf-8)
string datasign = HttpUtility.UrlEncode(base64Str, charset);
//请求报文参数
string postStr = "RequestType=reqType&EBusinessID= eEBusinessID&RequestData=jsonStr
&DataSign= datasign&DataType=dataType";
//通讯协议使用Http协议Post请求方式 返回轨迹数据
string post = SendPost(reqURL, postStr);
//获取到的post数据就是快递鸟返回的完整报文,接下来自己写一个解析json的方法就能获取到里面的字段信息。
- 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;
}
3.14.关于签名
快递鸟和第三方电子商务公司系统进行对接,有一定的安全机制。采用 IP 认证加签名的方式对接,具体方案如下:
防止数据被篡改 在 POST 请求中会传递 5 个必须®参数 RequestData数据内容(URL 编码:UTF-8)
EBusinessID用户 ID RequestType=请求指令类型 DataSign==
数据内容签名:把(请求内容(未编码)+ApiKey)进行 MD5 加密,然后 Base64 编码,最后进行 URL(utf-8)编码
DataType==2(返回数据类型为 json) 注: DataSign 生成后,对方接收到数据后,以同样的算法进行签名(推送接口
RequestType 为 101/102 不需要进行 URL
编码),生成摘要,对比两者的摘要是否相同,如果不同,说明传递过程中发生数据篡改。 调用接口的身份认证
注册成为快递鸟用户后,会生成对应的用户 ID 和 APIKey,用户 ID 相当于用户名, APIKey 相当于密码。
3.15.返回码定义
编码 | 说明 |
---|---|
100 | 成功 |
101 | 缺少必要参数 |
102 | 校验问题 |
103 | 格式问题 |