連載篇提前看
物流一站式查詢之TrackingMore篇
物流一站式查詢之順豐接口篇
物流一站式查詢之快遞100篇
快遞查詢接口
目前提供快遞查詢的接口平台有:
不同接口的區別:
(1)Trackingmore支持380家快遞公司,其中有55家為國內的快遞,其余325家為國際快遞。具體的價格為0.6分錢/單號左右,新注冊用戶可以免費測試12小時。
(2)快遞100屬於在國內做得比較早的平台,可以申請每天最多2000次的API調用,但需要給快遞100做一個友鏈。超過2000次收費,每次0.06~0.1元不等。
(3)快遞網可以申請每天最多500次的API調用,但同樣需要做一個友鏈。超過部分,每次0.05元。
快遞API的應用場景與用途
1. 最常見的應用場景如下:
(1)電商網站:例如B2C、團購、B2B、批發分銷站、C2C、本地生活交易等網站。
(2)管理系統:訂單處理平台、訂貨平台、發貨平台、分銷系統、渠道管理系統、客戶管理系統、ERP等。
2. 快遞API的用途如下:
(1)讓顧客登錄網站后,直接在“我的訂單”頁面內就能看到訂單的物流狀態。
(2)自動篩選出“已簽收”、“疑難件”等狀態的單號,減輕物流跟單人員的壓力。
(3)改變訂單的狀態和交易流程,例如單號變為“已簽收”,就能讓訂單變為可以確認退換貨等。
(4)評估選擇快遞公司,根據“已簽收”的運單數,可以算出銷售人員的業績,且便於應對貨到付款的結算。
(5)郵件、短信提醒用戶運單的最新狀態,可以安撫用戶,也可以利用郵件短信二次營銷。
對接示例
這里以Trackingmore為例,不同的接口的對接方式比較類似,都需要注冊,並生成自己的API key。以下以Trackingmore的實時查詢API為例。
接口支持的消息接收方式為HTTP POST
請求方法的編碼格式為 utf-8
請求body部分的參數的數據格式為json 格式
接口參數
接口請求地址
http://api.trackingmore.com/v2/trackings/realtime
請求頭部信息參數
參數名稱 | 類型 | 說明 | 是否必須 |
|
|
定義請求頭部的數據格式 | 是 |
|
string | Trackingmore 后台獲取的API | 是 |
請求body參數說明
參數說明 | 類型 | 說明 | 是否必須 |
|
string | 查詢快遞的快遞單號 | 是 |
|
string | trackingmore定義的快遞商簡碼,比如china ems 就是china-ema | 是 |
carrier_code 參數是trackingmore 自己定義的快遞商家的簡碼,具體的可以在這里查看。
還有需要注意的就是body部分這兩個參數需要時json數據格式。大概樣子就是這樣的
1 { 2 "tracking_number": "LK664578623CN", 3 "carrier_code": "china-ems" 4 }
返回參數定義
參數名稱 | 參數類型 | 參數說明 | 是否一定要返回該項值 |
code |
數字 | 返回碼 | 成功返回200,失敗有其他隊列的錯誤碼 |
type | string | 接口類型 | 成功返回Success |
message | string | 返回信息說明 | 成功返回Succes,失敗返回隊列的錯誤信息 |
data | json | 查詢到的物流信息 | 成功返回物流信息,失敗返回空 |
其他的狀態響應簡碼可以在這里看到。
這里把Trackingmore平台狀態響應簡碼簡單封裝了下,代碼如下:

/// <summary> /// 典型的服務器響應 狀態枚舉 /// </summary> public enum TrackMoreServerResponse { [Display(Name = "請求已成功 (一些 API 調用可能會相反返回 201)")] OK = 200, [Display(Name = "請求成功,已創建了資源")] Created = 201, [Display(Name = "請求已成功,但超過了數量限制")] CreatedFail = 202, [Display(Name = "身份驗證失敗或用戶沒有所請求的操作的權限")] Unauthorized = 401, [Display(Name = "無效的 API 密鑰。請確保自己的申請API key的賬戶與調用API的服務器同時在國內或國外。即如果你的服務器在國外,你需要翻牆登錄trackingmore網站進而獲取API key")] UnauthorizedAPIInvalid = 4001, [Display(Name = "API 密鑰已被刪除")] UnauthorizedAPIDelete = 4002, [Display(Name = "請求不能理解或缺少必需的參數")] BadRequest = 4012, [Display(Name = "Tracking_number 是必需的")] BadRequest1 = 4013, [Display(Name = "Tracking_number 的值是無效的")] BadRequestInvalid = 4014, [Display(Name = "Carrier_code的值是無效的")] BadRequest3 = 4015, [Display(Name = "跟蹤已存在")] BadRequest4 = 4016, [Display(Name = "跟蹤並不存在")] BadRequest5 = 4017, [Display(Name = "由於過載風險此功能需要自定義激活。與 service@trackingmore.org 聯系更多的信息。")] BadRequest6 = 4018, [Display(Name = "數量限制一次 200")] BadRequest7 = 4020, [Display(Name = "你的余額不夠,所以你不能調用API請求數據")] BadRequest8 = 4021, [Display(Name = "請求已成功,但響應為空")] BadRequest9 = 4031, [Display(Name = "無法檢測到快遞")] NoContent = 4032, [Display(Name = "付款要求")] PaymentRequired = 402, [Display(Name = "訪問被拒絕")] Forbidden = 403, [Display(Name = "找不到資源")] NotFound = 404, [Display(Name = "指定的資源不支持請求的方法")] MethodNotAllowed = 405, [Display(Name = "由於沖突,無法完成請求")] Conflict = 409, [Display(Name = "超過 API 限制。請求暫停,等待兩分鍾,然后再試")] TooManyRequests = 429, [Display(Name = "內部異常")] ServerError = 500, [Display(Name = "服務是臨時不可用 (例如預定的平台維護)稍后再試")] ServiceUnavailable = 503, }
然后我們可以獲取枚舉描述值來快速知道返回了什么狀態,而不用去官網查狀態碼的意思。這里也把獲取枚舉描述值的代碼貼出來如下:

/// <summary> /// 枚舉輔助類 /// </summary> public static class EnmHelper { /// <summary> /// 獲取枚舉值的描述 /// </summary> /// <param name="sourceValue"></param> /// <returns></returns> public static string GetEnmName(this Enum sourceValue) { DisplayAttribute[] attributes = null; if (sourceValue != null) { FieldInfo field = sourceValue.GetType().GetField(sourceValue.ToString()); if (field != null) { attributes =field .GetCustomAttributes(typeof(DisplayAttribute), false) as DisplayAttribute[]; } } if (attributes==null|| attributes.Length < 1) return sourceValue.ToString(); return attributes[0].Name; } /// <summary> /// 獲取枚舉集合列表 /// </summary> /// <param name="enmType"></param> /// <returns></returns> public static List<ModItem> GetEnmList(this Type enmType) { List<EnmItem> result = new List<EnmItem>(); Array array= Enum.GetValues(enmType); foreach (var item in array) { DisplayAttribute[] attributes = (DisplayAttribute[])item.GetType().GetField(item.ToString()).GetCustomAttributes(typeof(DisplayAttribute), false); EnmItem enmItem = new EnmItem(); if (attributes.Length > 0) { enmItem.Name = attributes[0].Name; enmItem.Value = Convert.ToInt32(item).ToString(); enmItem.OrderIndex = attributes[0].GetOrder().GetValueOrDefault(0); result.Add(enmItem); } } return result.OrderBy(x=>x.OrderIndex).Select(x=>x as ModItem).ToList(); } /// <summary> /// 把字符串轉換為枚舉 /// </summary> /// <typeparam name="T"></typeparam> /// <param name="source"></param> /// <returns></returns> public static T ConvertToEnm<T>(this string source) { return (T) ConvertToEnm(source,typeof(T)); } /// <summary> /// 把字符串轉換為枚舉 /// </summary> /// <typeparam name="T"></typeparam> /// <param name="source"></param> /// <returns></returns> public static object ConvertToEnm(this string source,Type enmType) { ModItem mod = enmType.GetEnmList().FirstOrDefault(x => x.Name == source); if (mod != null) { source = mod.Value; } return Enum.Parse(enmType, source); } } class EnmItem:ModItem { public int OrderIndex { set; get; } }
一個枚舉幫助類,其中ModItem類是自定義的一個類,里面就兩個屬性,Name、Value。
public class ModItem { public string Name { set; get; } public string Value { set; get; } }
像一般的調用接口獲取物流信息,官網也有提供調用示例,點我去看示例
完整的物流訂閱、查詢狀態有更新觸發回調url 示例
現在假設你已經在More平台注冊過,並生成創建了一個API Key。
訂閱篇
①創建一個接口的訪問類(此類官方已提供)

/// <summary> /// TrackingMore 每次發送必須帶有Key 否則請求無效 /// </summary> public class TrackingMoreAPI { private string ApiKey = ConfigHelper.GetKey("APIKey"); public string getOrderTracesByJson(string requestData, string urlStr, string method) { string result = null; if (method.Equals("post")) { string ReqURL = "http://api.trackingmore.com/v2/trackings/post"; string RelUrl = ReqURL + urlStr; result = sendPost(ReqURL, requestData, "POST"); } else if (method.Equals("get")) { string ReqURL = "http://api.trackingmore.com/v2/trackings/get"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "GET"); } else if (method.Equals("batch")) { string ReqURL = "http://api.trackingmore.com/v2/trackings/batch"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "POST"); } else if (method.Equals("codeNumberGet")) { string ReqURL = "http://api.trackingmore.com/v2/trackings"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "GET"); } else if (method.Equals("codeNumberPut")) { string ReqURL = "http://api.trackingmore.com/v2/trackings"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "PUT"); } else if (method.Equals("codeNumberDel")) { string ReqURL = "http://api.trackingmore.com/v2/trackings"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "DELETE"); } else if (method.Equals("realtime")) { string ReqURL = "http://api.trackingmore.com/v2/trackings/realtime"; string RelUrl = ReqURL + urlStr; //Console.WriteLine("RelUrl:" + RelUrl); result = sendPost(RelUrl, requestData, "POST"); } return result; } private string sendPost(string url, string requestData, string method) { string result = ""; byte[] byteData = null; if (requestData != null) { byteData = Encoding.GetEncoding("UTF-8").GetBytes(requestData.ToString()); } try { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); request.ContentType = "application/x-www-form-urlencoded"; request.Timeout = 30 * 1000; request.Method = method; request.Headers["Trackingmore-Api-Key"] = ApiKey; if (byteData != null) { 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; } }
②創建一個TrackMoreModel模型類用於傳輸快遞單號和快遞公司編碼

public class TrackMoreModel { /// <summary> /// 快遞單號 /// </summary> public string tracking_number { get; set; } /// <summary> /// 快遞公司編碼 /// </summary> public string carrier_code { get; set; } }
③創建一個TrackMore快遞信息跟蹤類,里面可以包含你需要的一些訪問接口的方法,如:創建快遞單項目,查詢單個物流信息、創建多個物流項目,查詢多個物流信息、實時查詢物流信息等。這里以創建單個快遞單項目為例

/// <summary> /// 快遞跟蹤信息 /// </summary> public class TrackMore { /// <summary> /// 創建快遞單號項目 /// </summary> /// <param name="input"></param> /// <returns></returns> public static OperationResult TrackExpressSubscibe(TrackMoreModel model) { #region 創建物流跟蹤信息 string urlstr = null; string requestdata = "{\"tracking_number\": \"" + model.tracking_number + "\",\"carrier_code\":\"" + model.carrier_code + "\"}"; string result = new TrackingMoreAPI().getOrderTracesByJson(requestdata, urlstr, "post"); var code = TarckMoreExpressCompany.GetValueFromJson(result, "code"); if ( code!="200") { string message = EnmHelper.GetEnmName((TrackMoreServerResponse)int.Parse(code)); if (!message.Equals("跟蹤已存在")) { return new OperationResult(message); } } #endregion return new OperationResult(); } }
其中GetValueFromJson 方法作用是從json字符串中獲取字段值 ,在這里方法也貼一下:

/// <summary> /// 從json字符串中獲取字段值 /// </summary> /// <param name="json">json字符串</param> /// <param name="field">要解析出值的字段</param> /// <returns></returns> public static string GetValueFromJson(string json, string field) { int start = json.IndexOf(field + "\":"); start += field.Length + 2; int end = json.IndexOf(",", start); if (end < 0) { end = json.IndexOf("}", start); } return json.Substring(start, end - start).Trim('"'); }
OperationResult 類是自定義的業務操作結果類,可以根據項目需要自定義添加,這里我貼三個出來
/// <summary> /// 默認操作成功 /// </summary> public OperationResult() { IsSuccess = true; } /// <summary> /// 以操作失敗信息實例操作結果 /// </summary> /// <param name="failMessage">操作失敗信息</param> public OperationResult(string failMessage) { IsSuccess = false; FailMessage = failMessage; } /// <summary> /// 業務操作是否成功 /// </summary> public bool IsSuccess { set; get; }
④有了跟蹤物流信息類,那剩下的就是調用了 ,調用比較簡單,主要是根絕項目業務 去做一些操作,比如從數據庫查詢訂單,過濾一些條件,快遞沒有訂閱的,排除掉一些訂單類型,有些充值啊這些不需要快遞,查詢到的集合
可以循環去創建物流單項目,調用的代碼就一句,
OperationResult result = TrackMore.TrackExpressSubscibe(new TrackMoreModel() { tracking_number =快遞單號, carrier_code =快遞公司簡碼) });
然后可以根據返回的結果做一些其他操作
if (result.IsSuccess) { //TODO 比如 更新數據庫此條訂單物流訂閱狀態,訂閱時間等 } else { //TODO 比如 日志記錄失敗原因 }
回調更新物流信息
上面只是再More物流平台創建了此條物流信息記錄,但是我們並不知道當前這個快遞狀態是如何,也不能每次都去快遞平台查詢,所以,回調的作用就凸顯出來了,物流平台每次只要有物流更新的時候,會訪問到你再平台上設定的回調URL。
此時,你只用接收發過來的數據(包括meta請求頭狀態,data 數據
verifyInfo 簽名部分
),具體代碼如下:
⑴先再More平台設置回調地址
當然官方也提供了回調測試的 頁面 在填回調地址的下面 點擊 format of inbound webhooks 即可進入,界面如下圖所示:
⑵設置完了回調地址,那我們就可以進行編碼了,首先我們要對返回的數據 進行分析,上面也提到了 Body返回的主體部分是Json格式的,其實這里有一個坑,就是提交那邊是form,但是接收是的數據類型是Json的
關於這種請求數據類型區別和使用,可以看這篇博客:
ASP.NET MVC學習系列(二)-WebAPI請求
ok,既然是Json格式數據,那我們就把返回的Json格式數據轉成實體模型。這里有幾種方式推薦,①將官方示例中的json全部復制下來,然后隨便百度一個Json轉實體,不過我更推薦第二種,② 號稱宇宙最強IED 的VS也幫我們實現Json轉實體的快捷操作,具體操作方式如下:
有了模型容器,我們就可以來接收數據了 創建一個和回調URL一樣的方法名稱UpdateTrack
/// <summary> /// TrackingMore 回調 同步物流信息 /// </summary> /// <param name="form"></param> /// <returns></returns> public ActionResult UpdateTrack([FromBody]Root dataJson) { var code = dataJson.meta.code;//請求狀態 var expressNumber = dataJson.data.tracking_number;//快遞單號 var status = dataJson.data.status;//物流狀態 var trackinfo = dataJson.data.origin_info.trackinfo;//物流信息集合 var expressMessage = ""; //所有物流信息 foreach (var item in dataJson.data.origin_info.trackinfo) { expressMessage += item.Date + " " + item.StatusDescription + "<br/>"; } var track = dataJson.data.origin_info.trackinfo; var LastExpressMessage = track.Count > 0 ? track[0].Date + " " + track[0].StatusDescription : "";//最近一條物流信息 //TODO 比如:先根據傳過來的快遞單號查尋 項目的訂單表 確認是否有此訂單,再根據數據表中的訂單狀態 //看是否需要修改一些其他信息,主要就是拿到第一條物流信息和所有的物流信息,也可以再數據表中記錄此時這個快遞單 回調的時間 和返回的狀態 用於后期數據分析 }
注:此方法接受回調使用了FormBody ,快遞100平台接收回調是FormCollection即可。
外部調用
所謂外部調用,就是再自己項目中,根據不同單號 借助物流平台查詢快遞實時信息。物流平台對此操作也有講解,這里簡單提下。
官方給出的效果如下:
實現步驟
①將下面這句引用代碼放在標簽開始之前的位置
<script type="text/javascript" src="//cdn.trackingmore.com/plugins/v1/pluginsCss.js?time=20170913"></script><script type="text/javascript" src="//cdn.trackingmore.com/plugins/v1/plugins.min.js"></script>
②將下面代碼放在 頁面與標簽之間的位置
<div style="width:600px;margin-left:0px;text-align:left;"> <form id="trackingmoreId" role="form" action="//track.trackingmore.com" method="get" onsubmit="return false"> <div class="search-box"> <div class="input-box"> <input id="button_express_code" type="hidden" value="" name="button_express_code"><input style="border-color: #428bca;" type="text" autocomplete="off" maxlength="26" placeholder="請輸入快遞單號" id="button_tracking_number" class="inp-metro" name="button_tracking_number"> <button style="background-color: #428bca" class="button-query" type="submit" onclick="return doTrack()" id="query">查詢</button> </div> </div> <input type="hidden" name="lang" value="cn" /> </form> <div id="TRNum"></div> </div> <script type="text/javascript"> function doTrack() { var num=document.getElementById("button_tracking_number").value; var expCode=document.getElementById("button_express_code").value; var width = document.getElementById("query").parentNode.offsetWidth; TRACKINGMORE.trackMynumber({ TR_ElementId:"TRNum", //必須,指定懸浮位置的元素ID。 TR_Width:width, //可選,指定查詢結果寬度,最小寬度為600px,默認撐滿容器。 TR_Height:600, //可選,指定查詢結果高度,最大高度為800px,默認撐滿容器。 TR_ExpressCode:expCode, //可選,指定運輸商,默認為自動識別。 TR_Lang:"cn", //可選,指定UI語言,默認根據瀏覽器自動識別。 TR_Num:num //必須,指定要查詢的單號。 }); return false; } </script>
溫馨提示:不要短時間內頻繁調用 More平台會檢測當前IP,過短調用會提示I異常 需要輸入驗證碼 最終效果展示如下:
PS:這種每次點擊訂單請求快遞數據並不是最優的做法。因為上面我們也有提到過快遞訂閱這個功能,其實,最佳的做法是 訂閱之后,快遞平台推送到回調地址的最新物流信息,我們可以將這些物流信息保存再對應訂單的快遞物流字段里面。這樣前台取的時候可以先判斷
物流信息字段是否為空,如果不為空 就直接取物流信息字段,這樣既可以減少網絡流量消耗,也可以加快系統反應時間,帶來更好的用戶體驗。如果不喜歡用官方自帶的這個顯示框,也可以改成Bootstrap的樣式框顯示,具體做法如下:
//查看物流(訂單id,this,物流信息,快遞單號,快遞公司簡碼) function viewSenderMessage(id, obj, message, number, company) { debugger; if (!isNullEmptyUndefined(message)) { var d = dialog({ title: '物流最新跟蹤', content: "<div style='line-height:20px;'>" + message + "</div>", okValue: '確定', ok: true, }); d.show(obj); } else if (!isNullEmptyUndefined(number) && !isNullEmptyUndefined(company)) { // doTrack(number, company); ajaxGetContent("@Url.Action("ViewExpress")" + "?companyNumber=" + company + "&expressNumber=" + number, function (data) { var d = dialog({ title: '物流最新跟蹤', content: data, okValue: '確定', ok: true, }); d.show(obj); }); } else { var d = dialog({ title: '物流最新跟蹤', content: "無物流跟蹤信息", okValue: '確定', ok: true, }); d.show(obj); } }
按照邏輯,如果物流信息為空 此時我們就需要從Action ViewExpress中獲取單個快遞信息。ViewExpress代碼如下:
public ActionResult ViewExpress(string expressNumber, string companyNumber) { string urlstr = null; string requestdata = "carrier_code=" + companyNumber + "&tracking_number=" + expressNumber; //此處是獲取單個物流信息 采用get請求,method傳入codeNumberGet string result = new TrackingMoreAPI().getOrderTracesByJson(requestdata, urlstr, "codeNumberGet"); if (!result.Contains("code")) return Content("暫無物流信息,請稍后重試"); var code = TarckMoreExpressCompany.GetValueFromJson(result, "code"); if (code != "200") { message = EnmHelper.GetEnmName((TrackMoreServerResponse)int.Parse(code)); //這里多加一層判斷 4031表示請求成功,但是響應為空,意思就是 TrackMore平台上還沒有這個快遞單數據,所以要再次調之前創建物流項目這個接口 if (code == "4031") { OperationResult resMessage = TrackMore.TrackExpressSubscibe(new TrackMoreModel() { carrier_code = companyNumber, tracking_number = expressNumber }); if (resMessage.IsSuccess) { return ViewExpress(expressNumber, companyNumber); } else { message = resMessage.FailMessage; } } } else { Root root = JsonConvert.DeserializeObject<Root>(result); if (root.Data.origin_info.trackinfo.Count == 0) message = "暫無物流信息,請稍后重試";
//此處將返回的物流信息以 時間+空格+物流消息 格式循環輸出 foreach (var item in root.Data.origin_info.trackinfo) { message += item.Date + " " + item.StatusDescription + "\r\n <br/>"; } }
return Content(message); }
獲取單個物流信息采用的是get請求,所以再發送http請求的時候不能再用post 的流方式,需要多加一個get請求的,代碼如下:
public string HttpGet(string Url, string postDataStr, string method) { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(Url + (postDataStr == "" ? "" : "?") + postDataStr); request.Method = "GET"; request.ContentType = "application/x-www-form-urlencoded"; request.Timeout = 30 * 1000; request.Method = method; request.Headers["Trackingmore-Api-Key"] = ApiKey; HttpWebResponse response = (HttpWebResponse)request.GetResponse(); Stream myResponseStream = response.GetResponseStream(); StreamReader myStreamReader = new StreamReader(myResponseStream, Encoding.GetEncoding("utf-8")); string retString = myStreamReader.ReadToEnd(); myStreamReader.Close(); myResponseStream.Close(); return retString; }
最終效果展示
注:順豐即日取消了對外第三方接口,故不能通過第三方物流平台獲取到順豐的物流信息,需要和順豐開放平台(目前據順豐IT人員透露,此平台已無人維護,已物流服務已轉至順豐官方的企業服務平台)對接 才能查到最新順豐的物流信息
順豐的接口對接請轉場至下文《物流一站式查詢之順豐接口篇》