商品退货京东快递上门揽收-API接口开发

前言

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

目录
1.接口功能说明

2.完成前期准备工作

3.API接口

4.请求参数（Headers）

5.请求参数（Body）

6.请求参数（示例）

7.返回参数（Return）

8.返回报文（示例）

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

10.解码后的报文

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

12.关于签名

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

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）

5.请求参数（Body）

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）

8.返回报文（示例）

{"EBusinessID": "test1617571","Success": true,"Order": {"OrderCode": "112657018199","KDNOrderCode": "KDN10200519103057","ShipperCode": "JD"},"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%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

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=23.接收方收到数据后，获得
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");elseret += 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;}

商品退货京东快递上门揽收-API接口开发相关推荐

国际快递顺丰API接口接入教程代码示例
快递100企业物流API支持接入国际快递顺丰API接口,而且我们的快递单号查询API接口,供小程序.APP.需实时返回物流轨迹信息即查即走,快递查询将提供输入运单编号立即获取物流最新轨迹,无需快递编码 ...
国内主流快递物流查询API接口测评对比
• 快递物流查询API接口快递查询接口是指快递查询网对外开放的应用程序接口,开发人员能够通过调用该接口与快递查询网进行交互,并基于该接口开发自己的快递查询应用程序. • 应用场景 ① 买家物流查询: ...
python调用api应用接口_第三方免费快递物流查询接口平台（快递鸟）api接口调用...
随着网购的发展,快递业也随之壮大.快递查询接口对接的需求量也越来越大,下面是对免费快递接口做的整理,并附上调用流程,分享给大家. 项目开发中,有些需求难免会用到关于快递的一些Api接口:本篇主要介绍的 ...
快递鸟查询Api接口使用（PHP版）
前提项目开发中,有些需求难免会用到关于快递的一些Api接口:本篇主要介绍的是快递的查询Api及与其他各家的不同之处: 常用的提供快递Api接口的有: 快递鸟快递100 爱查快递等等如大家使用 ...
如何用PHP对接调用快递鸟物流信息api接口
博主最近需要做一个物流信息轨迹查询的api接口,就去网上搜索,看到了一个快递鸟的API接口,返回值是以JSON格式,只需要返回是转成数组就能轻松实现各种实例了.真的很方便. 对接流程快递鸟网站申请接 ...
php 接口 2.0,YII 2.0 API接口开发
YII2.0 API接口开发首先先安装 YII2.0 高级模板(安装请参考其他教程) 准备添加数据库配置 common/config/main-local.php image 把backend目录 ...
api接口加密_谈谈API接口开发中的安全性如何解决
如今各种API接口层出不穷,一个API的好与不好可以从很多方面来考量,其中"安全性"就是一个API接口最基本也是最重要的一个特点.本文就来跟大家聊聊关于API接口开发的安全性问题. ...
Web API接口开发和测试
4.ASP.NET Web API的开发上面我们定义了一般的Web API接口,以及实现相应的业务实现,如果我们需要创建Web API层,还需要构建一个Web API项目的. 创建好相应的项目后,可 ...
为什么需要API接口开发？
API网关是提供服务开放和共享的企业级PaaS平台,提供发布管理.统一认证鉴权.流控.协议转换.服务审计等功能,帮助用户实现内部多系统间,或者内部系统与外部系统之间实现跨系统.跨协议的服务能力互通. ...

商品退货京东快递上门揽收-API接口开发

商品退货京东快递上门揽收-API接口开发相关推荐

最新文章

热门文章