快遞單號查詢之物流軌跡推送,推送100多家常用快遞公司的運單信息,菜鳥也能快速實現對接。
上一篇文章我們講解了訂閱服務功能。我們已經完成了如何把物流訂單訂閱到快遞鳥,快遞鳥也能接收到我們的訂單信息,接下來就需要快遞鳥實時的將最新的物流軌跡推送到我們服務器,我們既然要接收快遞鳥的信息,就需要提供一個服務地址給快遞鳥,以C#為列,我們新建一個接收頁面,我的接收文件: KdniaoHandler.aspx,把他部署到服務器,
接收地址:http://www.你的域名.com/KdniaoHandler.ashx
登陸快遞鳥官網,通過快遞鳥提供的沙箱調試頁面進去測試接口
調試頁面地址:
http://kdniao.com/UserCenter/v2/SandBox/PushQueryParam.aspx
測試的截圖:
一、接口描述/說明
推送接口(商戶實現)
(1)客戶需要按快遞鳥要求開發接口,保證信息的正常接收。
(2)快遞鳥主動推送時,物流信息接收接口由客戶提供。
(3)接口支持的消息接收方式為HTTP POST,請求方法的編碼格式(utf-8):"application/x-www-form-urlencoded;charset=utf-8"。
(4)運單物流信息全量推送(每次推送的運單物流信息包括運單當前所有的的物流信息)。
請求系統級參數說明:
參數名稱 |
類型 |
說明 |
必須要求 |
RequestData |
String |
請求內容需進行URL(utf-8)編碼。請求內容只支持JSON格式。 |
R |
RequestType |
String |
101-軌跡查詢結果, 107-貨款狀態 |
R |
DataSign |
String |
數據內容簽名(把(請求內容(未編碼)+AppKey)進行MD5加密,然后Base64編碼) |
R |
備注:R-必填(Required),O-可選(Optional),C-報文中該參數在一定條件下可選(Conditional)
二、接口參數
推送接口
應用級輸入參數
參數名稱 |
類型 |
說明 |
必須要求 |
EBusinessID |
String |
用戶電商ID |
R |
PushTime |
String |
推送時間 |
R |
Count |
String |
推送物流單號軌跡個數 |
R |
Data |
String |
推送物流單號軌跡集合 |
R |
訂閱查詢結果(RequestType:101)
通過軌跡查詢(訂閱查詢)接口訂閱到快遞鳥的數據,快遞鳥推送時,會將推送的RequestType的值置為101,同時返回下列數據
請求內容字段定義:
參數 |
類型 |
說明 |
必須要求 |
||
Data |
EBusinessID |
String |
商戶ID |
O |
|
ShipperCode |
String |
快遞公司編碼 |
R |
||
LogisticCode |
String |
快遞單號 |
R |
||
Success |
Bool |
成功與否:true,false |
R |
||
Reason |
String |
失敗原因 |
O |
||
State |
String |
物流狀態: 0-無軌跡,1-已攬收,2-在途中,3-簽收,4-問題件 |
R |
||
CallBack |
String |
訂閱接口的Bk值 |
O |
||
Traces |
|||||
Traces |
AcceptTime |
String |
時間 |
R |
|
AcceptStation |
String |
描述 |
R |
||
Remark |
String |
備注 |
O |
||
EstimatedDeliveryTime |
String |
預計到達時間yyyy-mm-dd |
O |
貨款狀態(RequestType:107)
用戶通過電子面單使用快遞鳥貨到付款等金融服務時,快遞鳥會將該訂單的金融狀態通過接口推送給用戶。
請求內容字段定義:
參數名稱 |
類型 |
說明 |
必須要求 |
|
Data |
EBusinessID |
String |
用戶電商ID |
O |
OrderCode |
String |
訂單編號 |
O |
|
ShipperCode |
String |
快遞公司編碼 |
R |
|
LogisticCode |
String |
物流運單號 |
R |
|
Success |
Bool |
成功與否 |
R |
|
Reason |
String |
失敗原因 |
O |
|
State |
String |
物流狀態:0-無軌跡,1-已攬收, 2-在途中 201-到達派件城市,3-簽收,4-問題件 |
R |
|
CallBack |
String |
訂閱接口的Bk值 |
O |
|
OrderState |
String |
訂單貨款狀態:1-待出款;2-已出款;3-已收款 |
O |
|
AccountName |
String |
返款銀行卡開戶人(例:**偉、*佳) |
O |
|
AccountTel |
String |
返款銀行卡手機末四位 |
O |
|
AccountNum |
String |
返款銀行卡末四位 |
O |
返回參數定義
參數名稱 |
類型 |
說明 |
必須要求 |
EBusinessID |
String |
用戶ID |
R |
UpdateTime |
String |
時間 |
R |
Success |
Bool |
成功與否:true,false |
R |
Reason |
String |
失敗原因 |
O |
推送接口(商戶實現)
請求示例 JSON (訂閱查詢結果)
{
"EBusinessID": "1109259",
"Count": "2",
"PushTime": "2015-3-11 16:21:06",
"Data": [
{
"EBusinessID": "1109259",
"OrderCode": "",
"ShipperCode": "EMS",
"LogisticCode": "5042260908504",
"Success": true,
"Reason": "",
"State": "2",
"CallBack": "0",
"Traces": [
{
"AcceptTime": "2015-03-06 21:16:58",
"AcceptStation": "深圳市橫崗速遞營銷部已收件,(攬投員姓名:鍾定基;聯系電話:)",
"Remark": ""
},
{
"AcceptTime": "2015-03-07 14:25:00",
"AcceptStation": "離開深圳市 發往廣州市",
"Remark": ""
},
{
"AcceptTime": "2015-03-08 00:17:00",
"AcceptStation": "到達廣東速遞物流公司廣航中心處理中心(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-08 01:15:00",
"AcceptStation": "離開廣州市 發往北京市(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-09 09:01:00",
"AcceptStation": "到達北京黃村轉運站處理中心(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-09 18:39:00",
"AcceptStation": "離開北京市 發往呼和浩特市(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-10 18:06:00",
"AcceptStation": "到達 呼和浩特市 處理中心",
"Remark": ""
},
{
"AcceptTime": "2015-03-11 09:53:48",
"AcceptStation": "呼和浩特市郵政速遞物流分公司金川攬投部安排投遞(投遞員姓名:安長虹;聯系電話:18047140142)",
"Remark": ""
}
]
},
{
"EBusinessID": "1109259",
"OrderCode": "",
"ShipperCode": "EMS",
"LogisticCode": "5042260943004",
"Success": true,
"Reason": "",
"State": "2",
"CallBack": "0",
"Traces": [
{
"AcceptTime": "2015-03-07 15:26:09",
"AcceptStation": "深圳市橫崗速遞營銷部已收件,(攬投員姓名:周宏彪;聯系電話:13689537568)",
"Remark": ""
},
{
"AcceptTime": "2015-03-08 16:32:00",
"AcceptStation": "離開深圳市 發往廣州市",
"Remark": ""
},
{
"AcceptTime": "2015-03-09 00:58:00",
"AcceptStation": "到達廣東速遞物流公司廣航中心處理中心(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-09 01:15:00",
"AcceptStation": "離開廣州市 發往北京市(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-10 05:20:00",
"AcceptStation": "到達北京黃村轉運站處理中心(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-10 11:59:00",
"AcceptStation": "離開北京市 發往廊坊市(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-10 14:23:00",
"AcceptStation": "到達廊坊市處理中心(經轉)",
"Remark": ""
},
{
"AcceptTime": "2015-03-11 08:55:00",
"AcceptStation": "離開廊坊市 發往保定市(經轉)",
"Remark": ""
}
]
}
]
}
請求示例 JSON格式 (貨款狀態)
{
"EBusinessID": "1109259",
"Count": "2",
"PushTime": "2015-3-11 16:21:06",
"Data": [
{
"EBusinessID": "1109259",
"OrderCode": "",
"ShipperCode": "EMS",
"LogisticCode": "5042260908504",
"Success": true,
"Reason": "",
"State": "2",
"CallBack": "0",
"OrderState":"1",
"AccountName":"張三",
"AccountTel":"13800000000",
"AccountNum":"0321"
},
{
"EBusinessID": "1109259",
"OrderCode": "",
"ShipperCode": "EMS",
"LogisticCode": "5042260908522",
"Success": true,
"Reason": "",
"State": "2",
"CallBack": "0",
"OrderState":"1",
"AccountName":"張三",
"AccountTel":"13800000011",
"AccountNum":"0321"
}
]
}
返回示例 JSON
{
"EBusinessID": "1151847",
"UpdateTime": "2016-08-09 16:42:38",
"Success": true,
"Reason": ""
}
KdniaoHandler.ashx
回調頁面:
<%@ WebHandler Language="C#" Class="KdniaoHandler" %>
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;
/// <summary>
/// 作者:yanghanwen
/// 聯系QQ:510997342
/// </summary>
public class KdniaoHandler : IHttpHandler {
/// <summary>
/// 訂閱接口的處理機制:用戶將快遞單號訂閱給快遞鳥,快遞鳥內部接收信息並按每家物流公司軌跡的生成規律實時動態調用物流公司給快遞鳥提供的專用接口,
/// 查詢有新軌跡就按客戶要求推送。如沒有最新軌跡,兩個小時后會再次觸發接口調用,如有更新就將全量數據推送給用戶,如果沒有更新,最晚每2小時輪詢,直到運單簽收。
/// </summary>
/// <param name="context"></param>
public void ProcessRequest (HttpContext context) {
context.Response.ContentType = "text/plain";
//接收請求 獲取到快遞鳥推送過來的請求報文
var requestData = context.Request.Form["RequestData"];
var requestType = context.Request.Form["RequestType"];
var dataSign = context.Request.Form["DataSign"];
//調試階段存儲日志 方便追蹤問題
WriteTextLog("RequestData:", requestData);
WriteTextLog("RequestType:", requestType);
WriteTextLog("DataSign:", dataSign);
// 這里提供給快遞鳥的接口一定不要做登錄權限驗證,否則快遞鳥無法推送信息。
//推送接口要在5S內對快遞鳥請求做出響應,返回快遞鳥所需的參數。成功獲取到報文以后,儲存並迅速返回響應,
//內部邏輯業務可異步處理。每個客戶處理的業務邏輯復雜程度不一樣,如果客戶對數據進行處理,再做出響應,會造成網絡超時,傳輸效率低下。
//在沒有返回信息或者返回超時, 以及返回不符合規定的內容,快遞鳥會判斷為客戶接收失敗。
//接收失敗后會重試推送2次,首次間隔15分鍾,二次間隔30分鍾,重試2次都未成功,不再推送,直到下次有新軌跡時再次推送。我們一定要嚴格按照技術文檔進行返回
PushResponse response = new PushResponse();
response.EBusinessID = "1151847";
response.UpdateTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
response.Success = true;
response.Reason = "成功";
string result = ToJson(response);
//聯調的時候可以返回固定的接收成功的報文
// result = "{\"EBusinessID\": \"1151847\", \"UpdateTime\": \""+DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")+"\", \"Success\": true, \"Reason\": \"成功\" }";
context.Response.Write(result);
}
public bool IsReusable {
get {
return false;
}
}
/// <summary>
/// 寫入日志到文本文件
/// </summary>
/// <param name="action">動作</param>
/// <param name="strMessage">日志內容</param>
public static void WriteTextLog(string action, string strMessage)
{
try
{
DateTime time = DateTime.Now;
string path = AppDomain.CurrentDomain.BaseDirectory + @"\LogInfo\";
if (!Directory.Exists(path))
Directory.CreateDirectory(path);
string fileFullPath = path + time.ToString("yyyy-MM-dd") + ".System.txt";
StringBuilder str = new StringBuilder();
str.Append("Time: " + time.ToString() + "\r\n");
str.Append("Action: " + action + "\r\n");
str.Append("Message: " + strMessage + "\r\n");
str.Append("-----------------------------------------------------------\r\n\r\n");
StreamWriter sw;
if (!File.Exists(fileFullPath))
{
sw = File.CreateText(fileFullPath);
}
else
{
sw = File.AppendText(fileFullPath);
}
sw.WriteLine(str.ToString());
sw.Close();
sw.Dispose();
}
catch (Exception e)
{
}
}
public class PushResponse
{
/// <summary>
/// 訂閱用戶ID
/// </summary>
public string EBusinessID
{
get;
set;
}
/// <summary>
/// 時間
/// </summary>
public string UpdateTime
{
get;
set;
}
/// <summary>
/// 成功與否:true,false
/// </summary>
public bool Success
{
get;
set;
}
/// <summary>
/// 失敗原因
/// </summary>
public string Reason
{
get;
set;
}
}
/// <summary>
/// 序列化JSON數據
/// </summary>
/// <param name="o"></param>
/// <returns></returns>
public static string ToJson(object o)
{
IsoDateTimeConverter timeFormat = new IsoDateTimeConverter();
timeFormat.DateTimeFormat = "yyyy-MM-dd HH:mm:ss";
return JsonConvert.SerializeObject(o, Newtonsoft.Json.Formatting.None, timeFormat);
}
/// <summary>
/// 反序列化JSON數據
/// </summary>
/// <typeparam name="T"></typeparam>
/// <param name="json"></param>
/// <returns></returns>
public static T ToObject<T>(string json)
{
return JsonConvert.DeserializeObject<T>(json);
}
}
提供源碼下載:
https://download.csdn.net/download/yanghanwen/12139326
調用第三方物流接口,替換自己的key就能直接使用,主要實現了物流在線軌跡查詢,訂單訂閱,軌跡推送,支持500多家的快遞查詢接口,包括主流的四通一達,支持上門取件服務,其他接口調用,修改調用指令和參數就能實現。