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

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

中文 | 英文（English）

一、订阅接口

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

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

1.1 订阅请求地址

https://poll.kuaidi100.com/poll

1.2 订阅请求类型

post

1.3 订阅输入参数

请求参数（header）

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

请求参数（body）

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

1.4 订阅请求参数示例

schema = json
param = {
    "company": "yuantong",
    "number": "YT6186594166532",
    "key": "XXX ",
    "parameters": {
        "callbackurl": "您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...",
        "salt": "XXXXXXXXXX",
        "phone": "13868688888",
        "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 推送输入参数示例

sign = ******
param = {
	"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 破损 快件破损
210 销单 寄件人申请撤销寄件
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

在线客服

一对一咨询

  • 电话图标

    电话咨询

    0755-86719032

    专业客服团队为您服务

  • 二维码图标

    联系商务

    二维码

    扫码添加工作人员

  • 小程序图标

    小程序

    小程序

    扫码进入企业助手