第三方物流快递单号查询接口如何快速免费申请APIKey

时间:2024-02-17 11:29:27

快递鸟是中国领先的第三方物流接口服务商,国家高新技术企业,已先后完成四轮融资,一直专注于企业级物流API技术研发和打通物流各节点信息服务,致力于成为全球最大的物流信息枢纽中心,为零售电商企业级提供标准的物流接口和物流模块整体解决方案,为开发者聚合600+快递物流公司接口,可一次性快速对接完成,实现物流轨迹信息查询、电子面单批量打印、预约快递员上门取件等一站式物流模块功能植入,免费注册申请APIKey立即对接,可申请免费试用。

快递鸟API查询接口支持包括顺丰、中通、韵达、圆通、申通、百世、EMS、邮政等600家以上快递物流公司,是专注做物流接口的, 第三方物流接口中做的比较好的。详情点击查看快递鸟支持的快递公司列表

快递鸟目前每日物流数据服务量达上千万单,上下游数据交换上千亿次,经过将近10年的物流接口产品打磨,一直专注于企业级快递API技术研发,拥有海量级快递物流信息传输、存储、计算能力,接口及时准确稳定性非常好,腾讯、12306、跟谁学、猿辅导、蘑菇街、建设银行、中通云仓、旺旺集团、美柚、美团、美的集团、唯品会、斑马会员,药师帮,屈臣氏、贝店、云集、趣店、学而思、水滴筹、凯叔讲故事、网易云音乐、中国电信、快手电商等知名企业都在用快递鸟API提供的物流接口服务。

对接快递查询接口获取物流轨迹应用场景

嵌入ERP、网站、APP,实时查看物流轨迹

商家发货后,实现轨迹查询的实时更新,根据物流轨迹自动判断物流状态并推送给ERP系统:如已揽件、到达派件城市、派送中、已签收、问题件等信息节点。用户可根据对应的状态发送短信、跟踪订单等操作。

对接使用流程

1、将快递单号和快递公司编码发送給快递鸟

2、快递鸟根据单号和快递公司查询到物流轨迹状态

3、快递鸟将查询到的物流轨迹状态反馈給电商平台或ISV服务商

4、电商平台或ISV服务商接收数据并实时处理做数据展示或应用

 

接口描述说明

(1)查询接口支持按照运单号查询(单个查询)。
(2)接口需要指定快递单号的快递公司编码,格式不对或则编码错误都会返失败的信息。
如:EMS物流单号应选择快递公司编码(EMS)查看下载快递鸟快递公司编码
(3)返回的物流跟踪信息按照发生的时间升序排列。
(4)接口指令1002。
(5)接口支持的消息接收方式为HTTP POST,请求方法的编码格式(utf-8):"application/x-www-form-urlencoded;charset=utf-8"。
(6)测试调用地址:
(7)正式调用地址:

(8)返回类型:JSON

(9)调试页面:

(10)调试工具:去调试(使用快递鸟账号登录)

请求系统级参数说明:

参数名称类型说明必须要求
RequestData String 请求内容需进行URL(utf-8)编码。请求内容JSON格式,须和DataType一致。 R
EBusinessID String 商户ID,请在我的服务页面查看。 R
RequestType String 请求指令类型:1002 R
DataSign String 数据内容签名:把(请求内容(未编码)+AppKey)进行MD5加密,然后Base64编码,最后 进行URL(utf-8)编码。详细过程请查看Demo。 R
DataType String 请求、返回数据类型:2-json; O

备注:R-必填(Required),O-可选(Optional),C-报文中该参数在一定条件下可选(Conditional)

【接口参数】

请求内容字段定义:

参数名称类型说明必须要求
OrderCode String 订单编号 O
ShipperCode String 快递公司编码 R
LogisticCode String 物流单号 R

返回参数定义:

参数名称类型说明必须要求
EBusinessID String 用户ID R
OrderCode String 订单编号 O
ShipperCode String 快递公司编码 R
LogisticCode String 物流运单号 O
Success Bool 成功与否 R
Reason String 失败原因 O
State String 物流状态:2-在途中,3-签收,4-问题件 R
Traces
AcceptTime String 时间 R
AcceptStation String 描述 R
Remark String 备注 O

示例

请求示例 JSON

{
                "OrderCode": "",
                "ShipperCode": "SF",
                "LogisticCode": "118650888018"
                }

返回示例 JSON

没有物流轨迹的
        {
        "EBusinessID": "1109259",
        "Traces": [],
        "OrderCode": "",
        "ShipperCode": "SF",
        "LogisticCode": "118461988807",
        "Success": false,
        "Reason": null
        }
        有物流轨迹的
        {
        "EBusinessID": "1109259",
        "OrderCode": "",
        "ShipperCode": "SF",
        "LogisticCode": "118461988807",
        "Success": true,
        "State": 3,
        "Reason": null,
        "Traces": [
        {
        "AcceptTime": "2014/06/25 08:05:37",
        "AcceptStation": "正在派件..(派件人:邓裕富,电话:18718866310)[深圳 市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/25 04:01:28",
        "AcceptStation": "快件在 深圳集散中心 ,准备送往下一站 深圳 [深圳市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/25 01:41:06",
        "AcceptStation": "快件在 深圳集散中心 [深圳市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/24 20:18:58",
        "AcceptStation": "已收件[深圳市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/24 20:55:28",
        "AcceptStation": "快件在 深圳 ,准备送往下一站 深圳集散中心 [深圳市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/25 10:23:03",
        "AcceptStation": "派件已签收[深圳市]",
        "Remark": null
        },
        {
        "AcceptTime": "2014/06/25 10:23:03",
        "AcceptStation": "签收人是:已签收[深圳市]",
        "Remark": null
        }
        ]
        }

前期准备工作

快递鸟官网免费注册一个账号,免费获得一个apiKey(接口权限验证需要),完成实名认证流程,订购一个免费或付费套餐(也可找快递鸟工作人员免费申请付费的接口测试联调)

快递鸟技术开发文档下载 快递鸟DEMO下载

注:登录快递鸟用户管理后台后获得用户ID和APIKey对应各demo中的EBusinessID、AppKey。

小知识:EBusinessID跟APIKey是什么?EBusinessID跟APIKey您在快递鸟网站注册之后快递鸟分配的密钥(对应官网上的用户ID和API key),用于保证应用来源的可靠性,避免应用伪造,被不法使用。

请求完整报文(示例)

RequestData=%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27JTSD%27%2c%27LogisticCode%27%3a%27jt0000052600488%27%7d&
EBusinessID=1264783&RequestType=1002&DataSign=MTYyMDU4NWQ2NmU1ZDI2MDEzNGE5YmVlM2YxYzEzMTM%3d&DataType=2

成功返回报文(示例)

{
"LogisticCode": "JT0000052600488",
"ShipperCode": "JTSD",
"Traces": [
{
"AcceptStation": "【芜湖市】【芜湖镜湖网点】的邓拥军 17855364213已取件",
"AcceptTime": "2020-03-16 16:26:13"
},
{
"AcceptStation": "【芜湖市】【芜湖镜湖网点】的邓拥军 17855364213已取件",
"AcceptTime": "2020-03-16 16:41:33"
},
{
"AcceptStation": "【芜湖市】【芜湖镜湖网点】已收件",
"AcceptTime": "2020-03-16 17:39:21"
},
{
"AcceptStation": "【芜湖市】快件离开【芜湖镜湖网点】已发往【芜湖转运中心】",
"AcceptTime": "2020-03-16 17:40:27"
},
{
"AcceptStation": "【芜湖市】快件到达【芜湖转运中心】",
"AcceptTime": "2020-03-16 19:36:32"
},
{
"AcceptStation": "【芜湖市】快件离开【芜湖转运中心】已发往【合肥转运中心】",
"AcceptTime": "2020-03-16 20:47:03"
},
{
"AcceptStation": "【合肥市】快件到达【合肥转运中心】",
"AcceptTime": "2020-03-16 23:40:10"
},
{
"AcceptStation": "【合肥市】快件离开【合肥转运中心】已发往【广州花都转运中心】",
"AcceptTime": "2020-03-17 00:10:48"
},
{
"AcceptStation": "【广州市】快件到达【广州花都转运中心】",
"AcceptTime": "2020-03-17 20:45:00"
},
{
"AcceptStation": "【广州市】快件离开【广州花都转运中心】已发往【深圳宝安转运中心】",
"AcceptTime": "2020-03-18 00:17:55"
},
{
"AcceptStation": "【深圳市】快件到达【深圳宝安转运中心】",
"AcceptTime": "2020-03-18 03:00:17"
},
{
"AcceptStation": "【深圳市】快件离开【深圳宝安转运中心】已发往【深圳福田网点】",
"AcceptTime": "2020-03-18 04:44:39"
},
{
"AcceptStation": "【深圳市】【深圳福田网点】的邹俊林 17679495647正在派件",
"AcceptTime": "2020-03-18 08:10:09"
},
{
"AcceptStation": "【深圳市】【深圳福田网点】的赵凯 15919817730正在派件",
"AcceptTime": "2020-03-18 09:55:19"
},
{
"AcceptStation": "【深圳市】快件已签收,签收人是【代收】,如有疑问请联系:15919817730,期待再次为您服务",
"AcceptTime": "2020-03-18 14:53:54"
}
],
"State": "3",
"EBusinessID": "1264783",
"Success": true
}


失败返回报文(示例)

{
"LogisticCode": "JT0000052600488",
"ShipperCode": "JTSD",
"Traces": [],
"State": "0",
"EBusinessID": "1264783",
"Reason": "业务错误[没有可用套餐]",
"Success": false
}

说明:未实名认证,未订购套餐,套餐可用查询量已经用完 都会返回此报文信息
去实名认证 / 了解套餐详情

无轨迹返回报文(示例)

{
"LogisticCode": "JT0000052600488",
"ShipperCode": "JTSD",
"Traces": [],
"State": "0",
"EBusinessID": "1264783",
"Reason": "暂无轨迹信息",
"Success": true
}

分步讲解(C#版本)
请求数据包结构

C#调用代码示例

//电商ID
string eEBusinessID = "test1617571";
 //电商加密私钥,快递鸟提供,注意保管,不要泄漏
string appKey= "554343b2-7252-439b-b4eb-1af42c8f2175";
 //请求url
string reqURL = "http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json";
//请求指令 
string reqType="1002";
//2-json 
string dataType = "2"; 
//字符编码采用UTF-8 
string charset = "UTF-8"; 
//JSON字符串string 
string jsonStr = 
"{\"OrderCode\":\"\",\"ShipperCode\":\"JTSD\",\"LogisticCode\":\"JT0000052600488\"}" ;
//把(jsonStr+APIKey)进行MD5加密
string md5Str=MD5(jsonStr + apiKey, charset);
//把md5Str 进行Base64编码
string base64Str=base64(md5Str,charset);
//进行URL编码 (utf-8)
string datasign = HttpUtility.UrlEncode(base64Str, charset); 
//请求报文参数 
string postStr = "RequestType=reqType&EBusinessID= eEBusinessID&RequestData=jsonStr 
&DataSign= datasign&DataType=dataType"; 
//通讯协议使用Http协议Post请求方式 返回轨迹数据
string post = SendPost(reqURL, postStr);
//获取到的post数据就是快递鸟返回的完整报文,接下来自己写一个解析json的方法就能获取到里面的字段信息。

C#调用方法

///<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));
}
 /// <summary>
    /// Post方式提交数据,返回网页的源代码
    /// </summary>
    /// <param name="url">发送请求的 URL</param>
    /// <param name="postData">请求报文参数</param>
    /// <returns>远程资源的响应结果</returns>
    private string SendPost(string url, string postData)
    {
        string result = "";
        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.ToString();
        }
        return result;
    }


关于签名

快递鸟和第三方电子商务公司系统进行对接,有一定的安全机制。采用 IP 认证加签名
的方式对接,具体方案如下:

防止数据被篡改 
在 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 编码),生成摘要,对比两者的摘要是否相同,如果不同,说明传递过程中发生数据篡改。 
调用接口的身份认证 
注册成为快递鸟用户后,会生成对应的用户 ID 和 APIKey,用户 ID 相当于用户名, 
APIKey 相当于密码。

13.返回码定义

100 成功
101 缺少必要参数
102 校验问题
103 格式问题

14、关于沙箱调试

在沙箱调试平台配置回调地址,测试推送接口。回调地址是用户提供,用于接收快递鸟推送的物流信息的,只要是外网可以访问的就行。测试、配置步骤如下:

(沙箱调试平台地址:

a、填写回调地址:

b、点击【生成】后 应用级参数报文(RequestData)就是推送到用户第一步时填写的回调地址上的测试物流信息。

c、点击【调用】,用户接收到测试的物流信息后,用户需要在 应用级参数报文区域 返回成功接收的信号给快递鸟(注:字段间不要存在空格,空格会影响返回结果),

返回格式:{"EBusinessID":"1237100","UpdateTime":"2015-03-11 16:26:11","Success":true,"Reason": ""}

d、调用结果显示为请求成功后即用户开发的推送接口通过测试。

e、测试通过后回到第一步填写回调地址的位置点击【配置】,弹出弹框,填写手机号(必须是注册快递鸟账号的手机号)、验证码、

回调地址,点击【保存】配置成功即可在正式环境使用,下次如果需要修改回调地址同初次配置回调地址步骤一致。

​对接中的其他说明

1、物流查询(免费版)会员套餐为免费版,有效期1年结束后,如在近3个月内有数据交互系统会自动免费续期;

2、即时查询(RequestType:1002/8001)日查询次数<=3000次对接即时查询接口

3、请求接口之前需要先实名认证,开通相关会员服务,否则会请求失败并返回提示“未申请开通接口”;

4、接口开发可以下载“快递鸟接口技术文档”进行参考;即时查询,参考技术文档中的4.1或5.1.1部分;

5、物流跟踪(RequestType:1008/8008)日查询次数>3000次对接物流跟踪接口

6、测试订阅接口,对照技术文档正确返回代表订阅接口对接成功,详情可见技术文档。

7、开发推送接口,无demo提供,推送时会推送requestType、requestData和DataSign三个参数,您开发一个推送接口接收这三个参数就行,成功接收后需要在5S内给快递鸟返回成功收数据的报文,否则超时。RequestData中包含应用级参数,即物流轨迹(详情看技术文档);

8、订阅接口、推送接口分别测试成功后,可使用正式地址进行订阅真实的快递单号,快递鸟一般会在2-12小时内推送物流信息至您已经配置好的回调地址上;

可能还关心的问题解答

1、问题:快递鸟接口有并发要求吗?

快递鸟即时查询接口并发不超过10次/秒,物流跟踪接口订阅不超过30次/秒,电子面单接口下单不超过20次/秒。

2、问题:快递鸟api收费标准是什么?

快递鸟查询接口和电子面单等接口有免费提供的,如果您对数据的状态时效、服务等有特别的需求,可联系快递鸟工作人员,为您量身定制专属解决方案,具体收费会根据您的需求进行商定。

3、问题:快递鸟数据更新实时性如何?

即时查询接口:实时获取当前最新轨迹信息,数据与官网信息一致。

物流跟踪接口:快递鸟每2小时到快递公司获取轨迹,如果您订阅的单号没有轨迹更新,间隔2小时后再次到快递公司获取轨迹,依次循环直到有物流轨迹更新,获取到新轨迹后进行排队序列推送。

4、问题:快递鸟数据准确性,会不会存在物流状态不准确的问题?

轨迹信息准确度大于99.9%。物流轨迹信息保持与快递公司官网一致,偶尔存在快递公司提供的接口数据与官网不一致的情况,不一致情况小于0.1%。

5、问题:快递鸟即时查询接口和物流跟踪接口有什么区别?

(1)接入方式不一样:

即时查询接口,根据快递单号和快递公司编码实时查询物流轨迹信息。

物流跟踪接口,用户订阅快递号,快递鸟系统会定时推送新的物流信息。

(2)实现的功能不一样:

即时查询接口,单次请求只能查询一个单的物流信息,支持10次/S的并发请求。

物流跟踪接口,订阅推送的模式获取轨迹信息,发起一次订阅后,快递鸟会持续监控推送更新的轨迹信息,直到签收。

(3)查询单量不一样:

即时查询每日查询次数<=3000次,物流跟踪不限制订阅单量,并可一直获得每个单号的更新信息。

6、问题: 快递鸟物流跟踪数据的时效性怎样?

在接收到新的快递单后,会立即加入监控队列,有结果的话会即时内返回,没有结果的话,会等待一定时间(如2小时)再进行下一次监控。对于这些后续的监控,如果某运单号在快递公司官网对应的结果B,B最新一条状态所对应的时间为T1,快递鸟将B推送给贵公司的时间为T2,那么|T2-T1|一般在0~2~4 个小时以内,但我方会不断地向贵方进行推送,使运单状态能持续地更新。

7、问题:快递鸟物流跟踪是需要我们自己开发接收接口是吗?

对接物流跟踪接口,你需要开发订阅接口(将单号和快递公司编码订阅给快递鸟。有订阅接口的.net,php和java版本demo,你可以参考下。还有自己开发一个推送接口(接收快递鸟推送的物流轨迹),开发完后登录快递鸟沙箱后台调试推送接口,调试成功后可在沙箱后台自助配置推送接口。

8、问题:快递鸟物流跟踪的推送接口怎么做?

推送接口是用于接收推送的物流信息,推送接口是我们调用你的接口,你只需要接收参数,在沙箱后台配置你的回调地址就行,RequestData中包含应用级参数,即物流轨迹,推送时会推送requestType、requestData和DataSign三个参数(详情看技术文档),您开发一个推送接口接收这三个参数就行。

9、问题:快递鸟的物流跟踪API实现原理是什么?

订阅接口的工作原理是:用户将快递单号订阅给我们,我们即刻加入队列去物流公司官方接口查询,查询有轨迹就给用户推送。如果没有更新数据,两个小时后会再次去物流公司官方接口查询,有新数据就将全量数据推送给用户,如果没有更新数据,两个小时后再重复上述动作,直到运单签收。