文档中心
一、订阅接口 二、推送接口 三、快递公司编码 四、demo下载 五、实时关注推送情况 API调试工具

快递订阅查询快递api接口技术文档

一、订阅接口

通过订阅接口提交快递单号,接口接收到后便对这些运单进行跟踪,当运单状态发生变化的时候,通过调用回调接口将运单的跟踪信息推送给贵公司,直到这些运单号的生命周期结束(一般以“已签收”为准)。

注意:对于同一快递公司同一个快递单号,每月最大订阅次数为4次,超过4次的订阅在提交时会报重复订阅。

1.1 订阅请求地址

https://poll.kuaidi100.com/poll

1.2 订阅请求类型

post

1.3 订阅输入参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

名称类型是否必需示例值描述
schemaStringjson返回的数据格式,json(默认) ,xml
Θparamparam 由其他字段拼接
└ companyStringems订阅的快递公司的编码,一律用小写字母,下载编码表格
└ numberString1136281381675订阅的快递单号, 单号的最小长度6个字符,最大长度32个字符
└ fromString广东省深圳市南山区出发地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,请尽量提供
└ toString北京市朝阳区目的地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,且到达目的地后会加大监控频率,请尽量提供
└ keyString 授权码,请申请企业版获取
Θparametersparameters 附加参数信息
└- callbackurlString 回调接口的地址,默认仅支持http,如需兼容https请联系快递100技术人员处理
└- saltStringXXXXXXXXXX签名用随机字符串
└- resultv2String1添加此字段表示开通行政区域解析功能。空:关闭(默认),1:开通行政区域解析功能以及物流轨迹增加物流状态名称 4: 开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息
└- autoComString1添加此字段且将此值设为1,则表示开启智能判断单号所属公司的功能,开启后,需确保company字段为空,即只传运单号(number字段),我方收到后会根据单号判断出其所属的快递公司(即company字段)。建议只有在无法知道单号对应的快递公司(即company的值)的情况下才开启此功能。
└- interComString1添加此字段表示开启国际版,开启后,若订阅的单号(即number字段)属于国际单号,会返回出发国与目的国两个国家的跟踪信息,本功能暂时只支持邮政体系(国际类的邮政小包、EMS)内的快递公司,若单号我方识别为非国际单,即使添加本字段,也不会返回destResult元素组
└- departureCountryStringCN出发国家编码
└- departureComStringems出发的快递公司的编码
└- destinationCountryStringJP目的国家编码
└- destinationComStringjapanposten目的的快递公司的编码
└- phoneString13488888888收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运丰网速运必填,其他快递公司选填。如座机号码有分机号,分机号无需上传。)

1.4 订阅请求参数示例

schema = json
param = {
    "company": "yuantong",
    "number": "YT6186594166532",
    "key": "XXX ",
    "parameters": {
        "callbackurl": "您的回调接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
        "salt": "XXXXXXXXXX",
        "resultv2": "4"
    }
}

1.5 订阅返回信息代码含义

result: true表示成功,false表示失败

信息代码信息内容描述原因及建议处理方式
200提交成功订阅提交成功
500服务器错误快递100的服务器出理间隙或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误
501重复订阅此单已经订阅成功且目前还在跟踪过程中。若要提交多次订阅,请在收到单号的status=abort或shutdown后隔半小时再提交订阅
502提交内容含有敏感关键字,被安全防护拦截回调地址、提交内容包含敏感词,请联系快递100工作人员
600您不是合法的订阅者(即授权Key出错)账号无可用单量,需要充值
601POLL: KEY 已过期账号无可用单量,需要充值
700不支持的快递公司拒绝订阅的快递公司,检查快递公司编码是否有误
701订阅方的订阅数据存在错误(如不支持的快递公司、单号为空、单号超长等)或错误的回调地址请检查快递公司编码、对照技术文档检查参数、在后台调试工具测试回调地址
702POLL:识别不到该单号对应的快递公司快递公司编码错误或者无可用单量,需要充值

1.6 订阅返回示例(JSON格式)

{
    "result": true,
    "returnCode": "200",
    "message": "提交成功"
}
         

二、推送接口

2.1 推送请求地址

由贵司在订阅请求中通过callbackurl字段提供

2.2 推送请求类型

post

2.3 推送输入参数

请求参数(header)

名称类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body)

名称类型示例值描述
signString 订阅参数salt值不为null时,推送数据将包含该加密签名,加密方式:md5(param+salt),注意加密后字符串一定要转32位大写。注意: salt值为空串时,推送的数据也会包含sign。
Θparam 由其他字段拼接
└ statusStringpolling监控状态:polling:监控中,shutdown:结束,abort:中止,updateall:重新推送。其中当快递单为已签收时status=shutdown,当message为“3天查询无记录”或“60天无变化时”status= abort ,对于status=abort的状态,需要增加额外的处理逻辑
└ billstatusStringgot包括got、sending、check三个状态,由于意义不大,已弃用,请忽略
└ messageString 监控状态相关消息,如:3天查询无记录,60天无变化
└ autoCheckString1快递公司编码是否出错,0为本推送信息对应的是贵司提交的原始快递公司编码,1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果,我方会(1)判断一次贵司提交的快递公司编码是否正确,如果正确,给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=0、comOld与comNew都为空;(2)如果贵司提交的快递公司编码出错,我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控(后续如果监控到单号有更新就给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码);并且给贵方的回调接口(callbackurl)推送一条含有如下字段的信息:status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
└ comOldStringyuantong贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
└ comNewStringems我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
ΘlastResultlastResult 最新查询结果,若在订阅报文中通过interCom字段开通了国际版,则此lastResult表示出发国的查询结果,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个基础物流状态,如需要返回高级物流状态,请参考 resultv2 传值
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记,0未签收,1已签收
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
└- dataObject 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途物流状态名称或者高级状态名称,提交resultv2=1或者resultv2=4标记后才会出现
└-- statusCodeString1002本数据元对应的高级物流状态值,提交resultv2=4标记后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,提交resultv2=1或者resultv2=4标记后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenterString17.200983,39.084158本数据元对应的行政区域经纬度,提交resultv2=4标记后才会出现
└--locationString深圳中心本数据元对应的快件当前位置,提交resultv2=4标记后才会出现
└--areaPinYinStringtianjin本数据元对应的行政区域拼音,提交resultv2=4标记后才会出现
Θ destResultdestResult 表示最新的目的国家的查询结果,只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元,全量,倒序(即时间最新的在最前)
└- messageString 消息体,请忽略
└- stateString0快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个基础物流状态,如需要返回高级物流状态,请参考 resultv2 传值
└- statusString200通讯状态,请忽略
└- conditionStringF00快递单明细状态标记,暂未实现,请忽略
└- ischeckString0是否签收标记,0未签收,1已签收
└- comStringyuantong快递公司编码,一律用小写字母
└- nuStringV030344422单号
Θ datadata 数组,包含多个对象,每个对象字段如展开所示
└-- contextString上海分拨中心/装件入车扫描内容
└-- timeString2012-08-28 16:33:19时间,原始格式
└-- ftimeString2012-08-28 16:33:19格式化后时间
└-- statusString在途本数据元对应的物流状态名称或者高级状态名称,提交resultv2=1或者resultv2=4标记后才会出现
└-- statusCodeString1002本数据元对应的高级物流状态值,提交resultv2=4标记后才会出现
└-- areaCodeString310000000000本数据元对应的行政区域的编码,提交resultv2=1或者resultv2=4标记后才会出现
└-- areaNameString上海市本数据元对应的行政区域的名称,提交resultv2=1或者resultv2=4标记后才会出现
└--areaCenterString17.200983,39.084158本数据元对应的行政区域经纬度,提交resultv2=4标记后才会出现
└--locationString深圳中心本数据元对应的快件当前位置,提交resultv2=4标记后才会出现
└--areaPinYinStringtianjin本数据元对应的行政区域拼音,提交resultv2=4标记后才会出现

2.4 推送输入参数示例

{
	"status": "polling",
	"billstatus": "got",
	"message": "寄件",
	"lastResult": {
		"message": "ok",
		"nu": "YT6186594166532",
		"ischeck": "0",
		"com": "yuantong",
		"status": "200",
		"data": [{
				"time": "2021-12-15 20:15:14",
				"context": "【苏州转运中心】 已发出 下一站 【无锡转运中心公司】",
				"ftime": "2021-12-15 20:15:14",
				"areaCode": "CN320500000000",
				"areaName": "江苏,苏州市",
				"status": "干线",
				"location": "",
				"areaCenter": "120.585315,31.298886",
				"areaPinYin": "su zhou shi",
				"statusCode": "1002"
			},
			{
				"time": "2021-12-15 20:11:25",
				"context": "【苏州转运中心公司】 已收入",
				"ftime": "2021-12-15 20:11:25",
				"areaCode": "CN320500000000",
				"areaName": "江苏,苏州市",
				"status": "干线",
				"location": "",
				"areaCenter": "120.585315,31.298886",
				"areaPinYin": "su zhou shi",
				"statusCode": "1002"
			},
			{
				"time": "2021-12-15 19:18:27",
				"context": "【江苏省无锡市锡新开发区公司】 已收入",
				"ftime": "2021-12-15 19:18:27",
				"areaCode": "CN320200000000",
				"areaName": "江苏,无锡市",
				"status": "在途",
				"location": "",
				"areaCenter": "120.31191,31.491169",
				"areaPinYin": "wu xi shi",
				"statusCode": "0"
			},
			{
				"time": "2021-12-15 17:10:09",
				"context": "【江苏省苏州市北桥公司】 已揽收",
				"ftime": "2021-12-15 17:10:09",
				"areaCode": "CN320507004000",
				"areaName": "江苏,苏州市,相城区,北桥",
				"status": "揽收",
				"location": "",
				"areaCenter": "120.606531,31.505825",
				"areaPinYin": "bei qiao jie dao",
				"statusCode": "1"
			}
		],
		"state": "0",
		"condition": "F00",
		"routeInfo": {
			"from": {
				"number": "CN320507004000",
				"name": "江苏,苏州市,相城区,北桥"
			},
			"cur": {
				"number": "CN320200000000",
				"name": "江苏,无锡市"
			},
			"to": null
		},
		"isLoop": false
	}
}

2.5 运单签收状态(state)说明

物流状态值 物流状态名称 高级物流状态值 高级物流状态名称 含义
1 揽收 1 揽收 快件揽件
101 已下单 已经下快件单
102 待揽收 待快递公司揽收
103 已揽收 快递公司已经揽收
0 在途 0 在途 快件在途中
1001 到达派件城市 快件到达收件人城市
1002 干线 快件处于运输过程中
1003 转递 快件发往到新的收件地址
5 派件 5 派件 快件正在派件
501 投柜或驿站 快件已经投递到快递柜或者快递驿站
3 签收 3 签收 快件已签收
301 本人签收 收件人正常签收
302 派件异常后签收 快件显示派件异常,但后续正常签收
303 代签 快件已被代签
304 投柜或站签收 快件已从快递柜或者驿站取出签收
6 退回 6 退回 快件正处于返回发货人的途中
4 退签 4 退签 此快件单已退签
401 已销单 此快件单已撤销
14 拒签 收件人拒签快件
7 转投 7 转投 快件转给其他快递公司邮寄
2 疑难 2 疑难 快件存在疑难
201 超时未签收 快件长时间派件后未签收
202 超时未更新 快件长时间没有派件或签收
203 拒收 收件人发起拒收快递,待发货方确认
204 派件异常 快件派件时遇到异常情况
205 柜或驿站超时未取 快件在快递柜或者驿站长时间未取
206 无法联系 无法联系到收件人
207 超区 超出快递公司的服务区范围
208 滞留 快件滞留在网点,没有派送
209 破损 快件破损
8 清关 8 清关 快件清关
10 待清关 快件等待清关
11 清关中 快件正在清关流程中
12 已清关 快件已完成清关流程
13 清关异常 货物在清关过程中出现异常
14 拒签 \ \ 收件人拒签快件

注:如需物流状态高级状态名称及状态值需要 resultv2 传 “4” 返回

2.6 推送响应报文及错误码解释

字段名称字段含义
resulttrue表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode200: 提交成功 500: 服务器错误 其他错误请自行定义
message返回的提示

2.7 推送返回示例

当我方调用贵方的回调接口(callbackurl)时,贵方需要先将我方提交的数据保存至贵方的数据库,接着向我方返回是否成功接收的响应报文及代码,即贵公司直接在回调接口的地址的response中填写如下内容:

{
    "result":true,
    "returnCode":"200",
    "message":"成功"
}      

注意:对于status= abort(message中包含“3天查询无记录”或者“60天无变化”)的快递单,也需要返回成功接收的响应报文及代码。

三、快递公司编码

下载表格

如果您需要的公司不在此列表,请联系在线客服添加

四、demo下载

JAVA示例代码    PHP示例代码    PYTHON示例代码    .NET示例代码

五、实时关注推送情况

扫码打开企业助手小程序实时关注账号里的推送成功情况,确保系统稳定运行。 https://cdn.kuaidi100.com/images/openApiWeb/common/code_1.jpg