快递查询接口种类及对接方法

Posted 2020-10-08 简幽

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了快递查询接口种类及对接方法相关的知识，希望对你有一定的参考价值。

目前快递查询接口有两种方式可以对接，一是和顺丰、圆通、中通、天天、韵达、德邦这些快递公司一一对接接口，二是和快递鸟这样第三方集成接口一次性对接多家常用快递。第一种耗费时间长，但是是直接和快递公司合作，第二种虽然是间接对接，但是对接简便，对后期的接口维护可以省很多时间和人力成本。

集成接口还有其他公司提供，有其他需要可以去找，快递鸟其实能满足电商、ERP系统商这些企业需求了。这里就以快递鸟为例说说对接方法。

快递鸟物流查询接口有免费和收费版本，对接周期大概在一天左右，他们有写好的demo，可以直接使用。

一.即时查询接口（免费）

1. 接口规则

(1)、查询接口支持按照运单号查询(单个查询，并发不超过10个/S)。

(2)、指定的物流运单号选择相应的快递公司编码，格式不对或则编码错误都会返失败的信息。如EMS物流单号应选择快递公司编码（EMS）

(3)、返回的物流跟踪信息按照发生的时间升序排列。

(4)、接口指令1002。

(5)、请求地址：http://api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx

2. 系统级和应用级输入参数

系统级输入参数	类型	应用级输入参数	必须要求	说明
RequestData	String	OrderCode	O	订单编号	请求内容，JSON格式,和DataType一致
		ShipperCode	R	快递公司编码
		LogisticCode	R	物流单号
EBusinessID	String		R	电商ID
RequestType	String		R	请求指令类型：1002
DataSign	String		R	数据内容签名
DataType	String		R	请求、返回数据类型： 2-json；

3. 返回结果参数

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

4. 示例

//请求示例
{
    "OrderCode": "",
    "ShipperCode": "SF",
    "LogisticCode": "118650888018"
}

//返回示例
//没有物流轨迹的
{
    "EBusinessID": "1109259",
    "Traces": [],
    "OrderCode": "",
    "ShipperCode": "SF",
    "LogisticCode": "118461988807",
    "Success": true,
    "Reason": null
}
//有物流轨迹的
{
    "EBusinessID": "1109259",
    "OrderCode": "",
    "ShipperCode": "SF",
    "LogisticCode": "118461988807",
    "Success": true,
    "CallBack":"",
    "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
        }
    ]
}

二.物流跟踪接口（免费）

2.1请求接口

物流跟踪接口和即时查询接口的区别：

查询次数-物流跟踪接口不限次数，即时查询接口每天只能查询3000次

接口使用-物流跟踪接口使用订阅单号异步推送的方式，就是如有物流轨迹更新，则推送给用户，后期用户需要查询的时候调用本地数据库就可以了，而即时查询接口是即时返回的方式，就是请求一次，返回一次

1. 接口规则

(1)、订单接收的信息(分给了的网点，业务员的信息)，会通过推送接口推给客户（订阅并发不超过30次/S）客户需要按要求实现接口。

(2)、仅支持Json格式。

(3)、请求指令1008。

(4)、测试接口地址：http://testapi.kdniao.cc:8081/api/dist

(5)、联调通过后请更换为正式地址：http://api.kdniao.cc/api/dist

(6)、分发及订阅接口需要客户方实现回调接口，回调RequestType(1008)

2. 系统级和应用级输入参数

系统级输入参数	应用级输入参数			类型	是否必须	描述
RequestData（必填参数，请求内容，JSON格式,须和DataType一致））	CallBack			String	O	用户自定义回调信息
	MemberID			String	O	会员标识(备用字段)
	WareHouseID			String	O	仓库标识(备用字段)
	CustomerName			String	O	电子面单客户账号（与快递网点申请）
	CustomerPwd			String	O	电子面单密码
	SendSite			String	O	收件网点标识
	ShipperCode			String	R	快递公司编码
	LogisticCode			String	R	快递单号
	OrderCode			String	O	订单编号
	MonthCode			String	O	月结编码
	PayType			Int	O	邮费支付方式: 1-现付，2-到付，3-月结，4-第三方支付
	ExpType			String	O	快递类型：1-标准快件
	Cost			Double	O	寄件费（运费）
	OtherCost			Double	O	其他费用
	Receiver	Company		String	O	收件人公司
		Name		String	O	收件人
		Tel		String	O	电话
		Mobile		String	O	手机
		PostCode		String	O	收件人邮编
		ProvinceName		String	O	收件省（如广东省，不要缺少“省”）
		CityName		String	O	收件市（如深圳市，不要缺少“市”）
		ExpAreaName		String	O	收件区（如福田区，不要缺少“区”或“县”）
		Address		String	O	收件人详细地址
	Sender	Company		String	O	发件人公司
		Name		String	O	发件人
		Tel		String	O	发件人电话
		Mobile		String	O	发件人手机
		PostCode		String	O	发件人邮编
		ProvinceName		String	O	发件省（如广东省，不要缺少“省”）
		CityName		String	O	发件市（如深圳市，不要缺少“市”）
		ExpAreaName		String	O	发件区（如福田区，不要缺少“区”或“县”）
		Address		String	O	发件详细地址
	StartDate			String	O	上门取货时间段: "yyyy-MM-dd HH:mm:ss"格式化，本文中所有时间格式相同
	EndDate			String	O	上门取货时间段: "yyyy-MM-dd HH:mm:ss"格式化，本文中所有时间格式相同
	Weight			Double	O	物品总重量kg
	Quantity			Int	O	件数/包裹数
	Volume			Double	O	物品总体积m3
	Remark			String	O	备注
	IsNotice			Int	O	是否分发到快递公司：1-不分发；0-分发.默认为0
	IsSendMessage			Int	O	是否订阅短信 0-不需要；1-需要
	AddService		Name	String	0	增值服务名称
			Value	String	0	增值服务值
			CustomerID	String	0	客户标识(选填)
	Commodity		GoodsName	String	O	商品名称
			GoodsCode	String	O	商品编码
			Goodsquantity	Int	O	件数
			GoodsPrice	Double	O	商品价格
			GoodsWeight	Double	O	商品重量kg
			GoodsDesc	String	O	商品描述
			GoodsVol	Double	O	商品体积m3
EBusinessID				String	R	商户ID
RequestType				String	R	请求指令类型：1008
DataSign				String	R	数据内容签名
DataType				String	R	请求、返回数据类型：2-json；

3. 返回结果参数（同步返回是否调用成功）

参数名称	类型	必须要求	说明
EBusinessID	String	R	电商用户ID
UpdateTime	String	R	时间
Success	Bool	R	成功与否:true,false
Reason	String	O	失败原因
EstimatedDeliveryTime	String	O	订单预计到货时间yyyy-mm-dd

4. 调用示例

//请求示例
 {
    "ShipperCode":"SF",
    "OrderCode":"SF201608081055208281",
    "LogisticCode":"3100707578976",
    "PayType":"1",
    "ExpType":"1",
    "CustomerName":"",
    "CustomerPwd":"",
    "MonthCode":"",
    "IsNotice":"0",
    "Sender":{
        "Name":"1255760",
        "Tel":"",
        "Mobile":"13700000000",
        "ProvinceName":"广东省",
        "CityName":"深圳市",
        "ExpAreaName":"福田区",
        "Address":"测试地址"
    },
    "Receiver":{
        "Name":"1255760",
        "Tel":"",
        "Mobile":"13800000000",
        "ProvinceName":"广东省",
        "CityName":"深圳市",
        "ExpAreaName":"龙华新区",
        "Address":"测试地址2"
    },
    "Commodity":[
        {
            "GoodsName":"书本"
        }
    ]
}

//返回示例
{
    "EBusinessID": "1151847",
    "UpdateTime": "2016-08-09 16:42:38",
    "Success": true,
    "Reason": ""
    "EstimatedDeliveryTime":"2016-8-12"
}

2.2接收接口

这个是用户在订阅单号成功且有物流轨迹更新后，快递鸟的推送

客户通过下单、订阅接口，把运单号在快递鸟系统订阅。运单物流信息有更新，快递鸟通过推送接口把更新的信息推送给客户。推送接口由用户按照快递鸟规则实现。商户开放接口，快递鸟定时将最新的物流轨迹推送到商户平台。

优点：客户不需要关注轨迹变化，一旦有更新，快递鸟自动推送。

缺点：对客户的服务器性能有所要求，快递鸟定时请求接口，对客户的服务器有一定的影响，客户服务器异常将接受不到最新数据。

快递鸟推送接口根据业务不同，会根据RequestType的分类推送不同的数据，用户需对推送的数据进行分类保存。原推送接口无需变化，快递鸟会根据推送版本进行推送。

1. 接口规则

(1)、客户服务器必须稳定，并且有一定的接受数据能力（需要在5S内给快递鸟返回成功示例，超时会判断推送失败）。快递鸟通过多线程推送物流信息给客户。

(2)、客户需要按快递鸟要求开发接口，保证信息的正常接收。客户接数据后，存储并马上返回接收响应。如果客户对数据进行处理，再做出响应。这会造成网络超时，传输效率低下。

(3)、主动推送时物流信息接收接口由客户提供，接口必须按照快递鸟的要求实现。

(4)、客户提供接口地址，用户登陆用户管理后台-----调试平台-----推送接口进行测试---（成功返回示例后）才可以配置。

(5)、接口只支持Json数据格式。

(6)、POST方式请求。

2. 系统级和应用级输入参数

系统级输入参数	应用级输入参数	类型	必须要求	说明
RequestData	EBusinessID	String	R	用户电商ID	推送数据经url转码utf-8
	PushTime			推送时间
	Count			推送物流单号轨迹个数
	Data			推送物流单号轨迹集合
RequestType		String	R	101-轨迹查询结果, 107-货款状态
DataSign		String	R	数据内容签名（把(请求内容(未编码)+AppKey)进行MD5加密，然后Base64编码）

3. 订阅查询结果（RequestType：101）

通过轨迹查询（订阅查询）接口订阅到快递鸟的数据，快递鸟推送时，会将推送的RequestType的值置为101，同时返回下列数据

参数名称		类型	必须要求	说明
Data	EBusinessID	String	O	电商用户ID
	OrderCode	String	O	订单编号
	ShipperCode	String	R	快递公司编码
	LogisticCode	String	R	物流运单号
	Success	Bool	R	成功与否
	Reason	String	O	失败原因
	State	String	R	物流状态: 0-无轨迹 2-在途中 3-签收 4-问题件
	CallBack	String	O	订阅接口的Bk值
	Traces	String	R	物流轨迹详情
	EstimatedDeliveryTime	String	O	预计到达时间yyyy-mm-dd
	PickerInfo	Object	O	收件员信息
	SenderInfo	Object	O	派件员信息

注：通过订单分发与电子面单接口自动订阅的运单，会返回预计达到时间,收派件人员网点信息,当前快件所在省市等字段

参数名称		类型	必须要求	说明
Traces	AcceptTime	String	R	时间
	AcceptStation	String	R	描述
	Remark	String	O	备注

3. 订阅查询（增值版）结果（RequestType：102）

这个是增值收费项，不想用收费的不支付就不会有这个服务，通过轨迹查询（订阅查询）接口订阅到快递鸟的数据，快递鸟推送时，会将推送的RequestType的值置为102，同时返回下列数据

参数名称		类型	必须要求	说明
Date	EBusinessID	String	O	电商用户ID
	OrderCode	String	O	订单编号
	ShipperCode	String	R	快递公司编码
	LogisticCode	String	R	物流运单号
	Success	Bool	R	成功与否
	Reason	String	O	失败原因
	State	String	R	物流状态: 0-无轨迹 2-在途中 3-签收 4-问题件
	StateEx	String	O	增值物流状态： 1-已揽收 2-在途中 201-到达派件城市 202-派件中 211-已放入快递柜或驿站 3-已签收 311-已取出快递柜或驿站 4-问题件 401-发货无信息 402-超时未签收 403-超时未更新 404-拒收（退件） 412-快递柜或驿站超时未取
	Location	String	O	当前城市
	CallBack	String	O	订阅接口的Bk值
	Traces	String	R	物流轨迹详情
	EstimatedDeliveryTime	String	O	预计到达时间yyyy-mm-dd
	PickerInfo	Object	O	收件员信息
	SenderInfo	Object	O	派件员信息

注：通过订单分发与电子面单接口自动订阅的运单，会返回预计达到时间,收派件人员网点信息,当前快件所在省市等字段

参数名称		类型	必须要求	说明
Traces	AcceptTime	String	R	时间
	AcceptStation	String	R	描述
	Location	String	O	当前城市
	Action	String	O	当前状态
	Remark	String	O	备注

4. 货款状态（RequestType：107）

用户通过电子面单使用快递鸟货到付款等金融服务时，快递鸟会将该订单的金融状态通过接口推送给用户。

参数名称		类型	必须要求	说明
Response	EBusinessID	String	O	电商用户ID
	OrderCode	String	O	订单编号
	ShipperCode	String	R	快递公司编码
	LogisticCode	String	R	物流运单号
	Success	Bool	R	成功与否
	Reason	String	O	失败原因
	State	String	R	物流状态: 0-无轨迹 2-在途中 3-签收 4-问题件
	CallBack	String	O	订阅接口的Bk值
	OrderState	String	O	订单货款状态： 1-待出款； 2-已出款； 3-已收款
	AccountName	String	O	返款银行卡开户人（例：*伟、佳）
	AccountTel	String	O	返款银行卡手机末四位
	AccountNum	String	O	返款银行卡末四位

注：通过订单分发与电子面单接口自动订阅的运单，会返回预计达到时间,收派件人员网点信息,当前快件所在省市等字段

4. 返回结果参数

参数名称	类型	必须要求	说明
EBusinessID	String	R	用户ID
UpdateTime	String	R	时间
Success	String	R	成功与否
Reason	String	O	失败原因

5. 示例

//快递鸟请求接收接口示例
订阅查询结果示例：
{
    "EBusinessID": "1109259",
    "Count": "2",
    "PushTime": "2015-03-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": ""
                }
            ]
        }
    ]
}

货款状态：
{
    "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"
        }
    ]
}

//用户接收后返回
{
    "EBusinessID": "1109259",
    "UpdateTime": "2015-03-11 16: 26: 11",
    "Success": true,
    "Reason": ""
}

以上是关于快递查询接口种类及对接方法的主要内容，如果未能解决你的问题，请参考以下文章

国际快递查询轨迹API接口如何对接？

php 实现快递鸟API接口快递查询对接签名验证

快速实现常用快递单号查询api接口对接方法

快递查询API接口对接方法

免费物流快递单号查询接口快速对接指南

顺丰快递单号查询api对接（全代码）