物流跟踪API-快递单推送
Posted 老杨占线
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了物流跟踪API-快递单推送相关的知识，希望对你有一定的参考价值。
快递单号查询之物流轨迹推送，推送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多家的快递查询接口，包括主流的四通一达，支持上门取件服务，其他接口调用，修改调用指令和参数就能实现。
以上是关于物流跟踪API-快递单推送的主要内容，如果未能解决你的问题，请参考以下文章