商城开发者必备：快递单号信息查询及上门取件订单物流类API开放接口
近年来，我国电商产业发展迅速，数据显示，2010-2019年，我国电子商务交易规模从4.55万亿元增长至了34.81万亿元，年均复合增速达25%。在电子商务蓬勃发展的态势下，我国电商物流行业也迎来了广阔的发展机遇。2019年，我国电商物流行业的营收规模突破7000亿元，同比增长15.92%。电商产业的迅猛发展也推动着物流行业需求的增加，其中电商商城根据快递单号查询物流状态的需求就是基本需求，用户下单后商家把货物有没有及时的按要求发出去，就需要通过物流轨迹的揽件状态来判断，作为衡量商家物流服务的评价依据，货物发出去到哪了，商城就需要给用户查看提醒物流轨迹，用户退换货就需要预约快递员按时上门取件，提高用户的购物体验，商家发货仓库也需要根据物流轨迹的签收状态来统计签收率（妥投率）来考核物流网点的服务等需求。
目前，直播带货、线上消费、在线教育等新消费业态呈爆发式增长，线上消费对线下起到了很好的承接作用，因高效率、低成本的优势，电商行业仍会持续增长。 据国家邮政局快递大数据平台监测显示，21年春节期间全国邮政快递业累计揽收和投递快递包裹达6.6亿件，同比增长了260%。原地过年催生各电商平台全力推动“春节不打烊”政策，反映了电商行业的竞争激烈度。
电商业务的增长加速了物流行业的服务与整合能力。新零售时代下销售模式变化，对物流提出新诉求，各环节数据的打通与整合变得越来越重要。
物流作为服务业，其服务质量、配送时效，决定着电商、零售企业的成败。
从配送效率和服务来看，京东物流仓配一体化的模式，极大的保障了配送时效。作为物流企业，京东自身强大的力量不断巩固其在电商领域的成果。
阿里整合物流体系打造菜鸟联盟，利用大数据、智能仓储、智能配送等，全面布局物流网络。
拼多多崛起之后逐步构建自己的物流阵地，补足自身物流短板。
腾讯、字节跳动、快手等视频内容平台基于流量优势开始电商化，背后同样需要物流能力支持。
可见，深度连接电商与物流成为现时的迫切需求，优化行业资源，提升电商与物流的粘合度，优化用户体验成为众多电商与物流企业的痛点。
在各环节数据打通的大背景下，快递鸟作为第三方物流管理数据平台，致力于建立全球最大的物流数据枢纽中心，用科技让发货更简单，用信息让包裹更透明。
快递鸟整合物流全流程的各节点数据，为零售电商企业提供物流标准接口和物流模块整体解决方案，帮助企业打通物流环节，建立自己的物流管理体系，进而提高购物用户的物流体验。
对于电商平台而言，物流管控能力极为重要，快递鸟整合多家物流快递接口使其标准化，快速高效低成本对接，提升平台的物流服务能力，监控商家发货时效。提高商家打单效率，给用户提供物流预测、物流轨迹可视化，物流节点智能提醒等功能，进而提高购物用户的物流体验。
对于物流企业而言，快递鸟打通并整合产业链数据，让物流公司的客户满意度更高，同时为众多物流企业提供业务揽收渠道，实现用户寄件需求的便捷途径。
不仅限于数据连接，还有服务连接，快递鸟打通了物流快递工单、订单、查单、预约取件等功能，直连物流投诉管理中心，使用快递鸟API，提升物流全流程的交易效率，极大降低企业的时间及人工成本。
快递鸟API经过近10年的物流标准接口及解决方案产品打磨，一直专注于企业级物流API技术研发，开发者可一次接入全球600+快递物流公司接口，各零售电商平台只需简单的对接，就具备了完整的物流服务能力。
- 使用快递鸟API 仅需3步 -
1、到快递鸟网站注册获取API key和ID
2、在网站下载技术文档和调用的demo
3、修改参数对接后即可使用
专业的售前服务和售后技术支持团队，让企业物流对接更简单高效。
技术对接
官网API
1.点击官网API接口菜单，进入快递鸟API详情介绍页
2.我们可以看到API大致分为三大类：下单类接口、查询类接口、增值类接口
3.以即时查询为例，点击即时查询API后，我们可以看到右侧有对此接口的描述、应用场景介绍、功能说明、使用流程、API参数、接入流程以及Demo下载 。(等不及了的小伙伴 可以直接去看Demo)
4.我们看到功能说明中，此接口可以免费500/日对外开放
5.在API参数那块要注意，每个不同的请求，都对应一个接口指令，这个指令不能错
另外，在快递鸟公司官网的接口文档菜单中，我们可以看到为我们提供了以下文档信息
其中，建议如果有小伙伴要接入快递鸟，可以优先着重查看下接口说明文档，里面对请求报文、数据传输格式，请求参数以及返回字段等都有详细的描述说明。
我们先来看看报文的规范如下：
报文及报文编码
报文格式： Json 格式
请求方法的编码格式(utf-8)： "application/x-www-form-urlencoded;charset=utf-8"
交互协议上统一用 UTF-8， 避免传递中文数据出现乱码。
接口数据包结构
Json示例
string used = "1237100";//仅作为示例ID， 不可用来实际使用
//加密私钥， 由快递鸟提供
string keyValue = "56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//仅作为示例Key， 不可用来实际使用
//请求地址
string url = "https://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx";
//2-json
string DataType = "2";
//字符编码采用UTF-8
string charset = "UTF-8";
//JSON字符串string
string jsonStr ="{\"OrderCode\":\"\",\"ShipperCode\":\"SF\",\"LogisticCode\":\"118461988807\"}"; //把(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";
//通讯协议使用Https协议Post请求方式
string post = this.DoPost(url, PostStr);系统及参数
签名说明
快递鸟和第三方电子商务公司系统进行对接， 有一定的安全机制。 采用 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相当于密码。
假设
RequestData (JSON)内容为：
{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}
经过 URL(UTF-8)编码的内容为：
%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%2
7LogisticCode%27%3a%27118954907573%27%7d；
EBusinessID=1237100【示例 ID， 不可用来实际使用】
APIKey=56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17【示例 Key， 不可用来实际使用】那么DataSign签名的内容为
{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}56da2cf8-c8a2-44b2-b6
fa-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接收方收到数据后，获得EBusinessID 和 RequestData 和 DataSign 等这几个数据。 接收方对 EBusinessID 得到 APIKey， RequestData+APIKey 的数据进行md5 和 base64 后的内容就为
OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=
接收方判断签名后的数据跟传递过来的 DataSign 是否一致， 如果一致进行业务操作， 如果不一致返回错误。
C#版电商Sign签名范例：
View Code 代码实现
好了，有了以上的接口基础，我们可以开始直接撸码了，我们这里环境使用到的是.NET Core 3.1版本。我们先以自动识别快递单号接口为例，可实现如下效果。
当我们输入申通快递单号时，左侧快递公司下拉框会自动识别到当前快递公司为申通，中通亦是如此。
那如何实现呢，我们话不多说，开整(默认看到这里的小伙伴 有编程基础，有建基础项目的能力，跳过基础步骤)。
根据接口描述：该接口仅对运单号做出识别，识别可能属于的一家或多家快递公司。
我们定义出如下Model，仅供参考
public class RecognitionModel
{
///
/// 用户Id
///
public string EBusinessID { get; set; }
///
/// 物流单号
///
public string LogisticCode { get; set; }
///
/// 成功与否
///
public bool Success { get; set; }
///
/// 失败原因
///
public string Code { get; set; }
///
/// 快递公司
///
public List<_Shipper> Shippers { get; set; }
}
public class _Shipper
{
public string ShipperCode { get; set; }
public string ShipperName { get; set; }
}我们需要一个服务，来实现我们根据运单号获取一个或多个快递公司的功能，推荐使用异步编程
public async Task getExpressCompany(string expressNumber)
{
string requestData = "{'LogisticCode':'"+expressNumber+"'}";
var result= await BaseAction(requestData, ((int)QueryType.ExpressRecognition).ToString());
return result == null ? new RecognitionModel() : JsonConvert.DeserializeObject(result);
} 其中，BaseAction用于所有的基础请求，我们需要传入请求数据和请求接口类型即可
public async Task BaseAction(string requestData,string type)
{
return await Task.Run(() =>
{
Dictionary param = new Dictionary
{
{"RequestData", HttpUtility.UrlEncode(requestData, Encoding.UTF8)},
{"EBusinessID", expressConfig.BusinessID},
{"RequestType", type}
};
string dataSign = Encryption.encrypt(requestData, expressConfig.AppKey, "UTF-8");
param.Add("DataSign", HttpUtility.UrlEncode(dataSign, Encoding.UTF8));
param.Add("DataType", "2");
string result = HttpHelper.sendPost(apiConfig.Logistics_Trajectory_API, param);
return result;
});
}
上述代码中Encryption类为自定义类，类中包含了Sign签名方法、字符串MD5加密方法以及对内容的Base64编码，该类如下：
View Code
这样，我们的代码就写的差不多了，我们来调试看看究竟能否获取成功:
从图中可以看出，最终result 返回了正确的识别结果，这样，我们的自动识别api到这里算已经对接成功了，下面我们再来看一看即时查询API对接上有何不同。
同样的，我们需要定义一个服务来实现获取物流轨迹的功能，看接口文档描述，我们需要传入快递公司编码和快递单号，我们从支持的公司编码表中看到
常见的快递物流公司编码格式都在此。那我们的服务 就可以很快定义出来了，如下：
public async Task getOrderTracesByJson(string expressNumber, string expressCode,string sfNumber, QueryType queryType = QueryType.MonitorQuery)
{
var type = typeof(QueryType).GetEnmList().FirstOrDefault(m => m.Name == queryType.GetEnmName())?.Value;
return await Task.Run(async () =>
{
string requestData = expressCode != "SF"
? "{'OrderCode':'','ShipperCode':'" + expressCode + "','LogisticCode':'" + expressNumber + "'}"
: "{'OrderCode':'','ShipperCode':'" + expressCode + "','LogisticCode':'" + expressNumber +
"','CustomerName':'" + sfNumber + "'}";
var result = await BaseAction(requestData,type);
return result;
});
} 注：上述对expressCode有个判断，是否为顺丰，若为顺丰，按照快递鸟接口文档所述，需要另外多传入一个CustomerName的参数，参数内容为收件人/寄件人手机号尾数后四位。
我们只需要写一个获取方法，复用我们的BaseAction即可，我们来调试看看获取情况：
最终，我们再返回的result中看到了返回的物流信息。这样，我们就得到了自己所需要的数据，
ps：除了国内常见的快递公司，快递鸟还支持国内外众多快递公司，具体详情可以查看快递公司编码表
联调测试
在开发过程中，需要不断对服务中的代码进行测试，尝尝要判断一些不同的情况，比如：快递单号错误、快递公司选择错误等等诸如此类的问题
。
常见问题
这里列举的常见问题，一部分是我在对接过程中遇到的，如果大家在对接过程中，也有此类问题，可以参考参考。
1.关于顺丰查询输入手机尾号的问题，若某一单号此前没有查询过物流信息，输入错误手机尾号，将不会返回任何物流信息，若此前查询过，输入错误的手机尾号，返回的将是缓存数据，看图说话
注：上图中进行了三次查询，第一次输入顺丰单号，用0000手机尾号(错误的号码)查询，结果为暂无物流显示，第二次采用正确的7517手机尾号查询，结果返回正确的物流数据，第三次采用9999(错误的号码)查询，结果返回的是缓存第一次查询后的物流数据(不会更新)
2、快递编码表中的顺丰速运和中通快递，在快递单号识别API中 返回的名字是不一致的
