物流一站式单号查询之快递鸟API接口（附Demo源码）

连载篇提前看

前情提要

前三篇中，我们已经从注册、申请接口、调用接口、联调开发、部署上线等一系列角度对比过几家不同的物流平台，今天我们再来瞧一瞧快递鸟这个物流平台，我们会今天从

全流程的快速梳理一遍，另外，我还会就在我对接API过程中，遇到的一些常见问题特别备注一下，希望给后面用到的朋友有个参考帮助～

阅读完本篇内容，你可以利用快递鸟平台做出如下项目(文末有源码地址),当然，如果你觉得看图不过瘾，那就劳驾看官自己体验一下：点我在线体验

注册认证账号

1.进入快递鸟官网 ,点击右上角免费注册按钮，点我直接去官网

2.注册账号

3.注册成功后，会自动跳转到后台，可以看到首页面板中个人信息部分，有未认证提示，可按需进行认证

申请服务

1.申请服务这块也是在首页控制面板中，产品服务区域查看，可点击立即开通，进入服务详情页，按需开通即可

2.开通后的服务，可在左侧菜单《我的产品服务》中查看到

3.点进具体的服务详情，可以看到服务订单使用量情况，30天使用趋势图，以及可以设置余量提醒等等

技术对接

官网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签名范例：

 public class KdApiSearchDemo
    {
        //电商ID
        private string EBusinessID = "1237100";
        //电商加密私钥，快递鸟提供，注意保管，不要泄漏
        private string AppKey = "518a73d8-1f7f-441a-b644-33e77b49d846";
        //请求url
        private string ReqURL = "https://api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx";

        /// <summary>
        /// Json方式 查询订单物流轨迹
        /// </summary>
        /// <returns></returns>
        public string getOrderTracesByJson()
        {
            string requestData = "{'OrderCode':'','ShipperCode':'SF','LogisticCode':'589707398027'}";

            Dictionary<string, string> param = new Dictionary<string, string>();
            param.Add("RequestData", HttpUtility.UrlEncode(requestData, Encoding.UTF8));
            param.Add("EBusinessID", EBusinessID);
            param.Add("RequestType", "1002");
            string dataSign = encrypt(requestData, AppKey, "UTF-8");
            param.Add("DataSign", HttpUtility.UrlEncode(dataSign, Encoding.UTF8));
            param.Add("DataType", "2");

            string result = sendPost(ReqURL, param);

            //根据公司业务处理返回的信息......

            return result;
        }

        /// <summary>
        /// Post方式提交数据，返回网页的源代码
        /// </summary>
        /// <param name="url">发送请求的 URL</param>
        /// <param name="param">请求的参数集合</param>
        /// <returns>远程资源的响应结果</returns>
        private string sendPost(string url, Dictionary<string, string> param)
        {
            string result = "";
            StringBuilder postData = new StringBuilder();
            if (param != null && param.Count > 0)
            {
                foreach (var p in param)
                {
                    if (postData.Length > 0)
                    {
                        postData.Append("&");
                    }
                    postData.Append(p.Key);
                    postData.Append("=");
                    postData.Append(p.Value);
                }
            }
            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.Message;
            }
            return result;
        }

        ///<summary>
        ///电商Sign签名
        ///</summary>
        ///<param name="content">内容</param>
        ///<param name="keyValue">Appkey</param>
        ///<param name="charset">URL编码 </param>
        ///<returns>DataSign签名</returns>
        private string encrypt(String content, String keyValue, String charset)
        {
            if (keyValue != null)
            {
                return base64(MD5(content + keyValue, charset), charset);
            }
            return base64(MD5(content, charset), charset);
        }

        ///<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));
        }
    }

View Code

代码实现

好了，有了以上的接口基础，我们可以开始直接撸码了，我们这里环境使用到的是.NET Core 3.1版本。我们先以自动识别快递单号接口为例，可实现如下效果。

当我们输入申通快递单号时，左侧快递公司下拉框会自动识别到当前快递公司为申通，中通亦是如此。

那如何实现呢，我们话不多说，开整(默认看到这里的小伙伴有编程基础，有建基础项目的能力，跳过基础步骤)。

根据接口描述：该接口仅对运单号做出识别，识别可能属于的一家或多家快递公司。

我们定义出如下Model，仅供参考

public class RecognitionModel
    {
        /// <summary>
        /// 用户Id
        /// </summary>
        public string EBusinessID { get; set; }

        /// <summary>
        /// 物流单号
        /// </summary>
        public string LogisticCode { get; set; }

        /// <summary>
        /// 成功与否
        /// </summary>
        public bool Success { get; set; }

        /// <summary>
        /// 失败原因
        /// </summary>
        public string Code { get; set; }

        /// <summary>
        /// 快递公司
        /// </summary>
        public List<_Shipper> Shippers { get; set; }
    }

    public class _Shipper
    {
        public string ShipperCode { get; set; }

        public string ShipperName { get; set; }
    }

我们需要一个服务，来实现我们根据运单号获取一个或多个快递公司的功能，推荐使用异步编程

public async Task<RecognitionModel> getExpressCompany(string expressNumber)
{
   string requestData = "{'LogisticCode':'"+expressNumber+"'}";
   var result= await BaseAction(requestData, ((int)QueryType.ExpressRecognition).ToString());
   return result == null ? new RecognitionModel() : JsonConvert.DeserializeObject<RecognitionModel>(result);
}

其中，BaseAction用于所有的基础请求，我们需要传入请求数据和请求接口类型即可

　　　　public async Task<string> BaseAction(string requestData,string type)
        {
            return await Task.Run(() =>
            {
                Dictionary<string, string> param = new Dictionary<string, string>
                {
                    {"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编码，该类如下：

 ///<summary>
        ///电商Sign签名
        ///</summary>
        ///<param name="content">内容</param>
        ///<param name="keyValue">Appkey</param>
        ///<param name="charset">URL编码 </param>
        ///<returns>DataSign签名</returns>
        private string encrypt(String content, String keyValue, String charset)
        {
            if (keyValue != null)
            {
                return base64(MD5(content + keyValue, charset), charset);
            }
            return base64(MD5(content, charset), charset);
        }

        ///<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));
        }

View Code

这样，我们的代码就写的差不多了，我们来调试看看究竟能否获取成功:

从图中可以看出，最终result 返回了正确的识别结果，这样，我们的自动识别api到这里算已经对接成功了，下面我们再来看一看即时查询API对接上有何不同。

同样的，我们需要定义一个服务来实现获取物流轨迹的功能，看接口文档描述，我们需要传入快递公司编码和快递单号，我们从支持的公司编码表中看到

常见的快递物流公司编码格式都在此。那我们的服务就可以很快定义出来了，如下：

public async Task<string> 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中返回的名字是不一致的

3.免费接口仅支持四家主流快递的查询（申通、圆通、百世、天天），不支持其他主流快递查询。

项目源码

git源码下载： https://github.com/XiaoYong666/KdAPI_Demo

在线演示：http://kdn.fuyue.xyz/

小结

今天通过快递单号自动识别接口和即时查询接口快速的熟悉了一遍快递鸟平台接口对接方式和一些注意点。通过快递鸟官网API接口和接口文档我们可以看到，此平台接口内容比较详细，给出的介入案例也丰富多样，有C#、Java、PHP等多语言版本。同时还有QQ技术支持群和VIP专属对接专员，感觉还是比较贴心省事的，咨询问题响应也是比较及时。整个流程下来还是比较轻松的。希望通过这篇文章给需要对接物流的小伙伴带来一些帮助，如果有问题，欢迎私信或加我QQ～

全文完！

posted @ 2020-10-30 16:32 潇十一郎阅读(3248) 评论(5) 编辑收藏举报

刷新页面返回顶部

潇十一郎

☆努力做一个很哇塞的人！☆

物流一站式单号查询之快递鸟API接口（附Demo源码）

连载篇提前看