目前快递查询接口有两种方式可以对接,一是和顺丰、圆通、中通、天天、韵达、德邦这些快递公司一一对接接口,二是和快递鸟这样第三方集成接口一次性对接多家常用快递。第一种耗费时间长,但是是直接和快递公司合作,第二种虽然是间接对接,但是对接简便,对后期的接口维护可以省很多时间和人力成本。
集成接口还有其他公司提供,有其他需要可以去找,快递鸟其实能满足电商、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 | ||||
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": ""
}