文档中心
一、订阅接口 二、推送接口 三、快递公司编码

地图轨迹推送接口文档

一、订阅接口

1.1 接口格式

1.使用http协议表单提交的方式进行信息交互,字符编码默认统一采用UTF-8,数据格式:application/x-www-form-urlencoded;

2.字段类型约定:需要严格依据字段表格中给出的参数格式和大小进行开发。

3.字段解析约定:参数字段中的必选字段是每次调用接口时都要求必须传入的;

1.2 请求地址

http://poll.kuaidi100.com/pollmap

请求报文:

参数名是否必填类型说明
schemastring默认是json
paramObject主体参数对象

param数据结构:

参数名是否必填类型说明
keystring授权码,请申请企业版获取
companystring订阅的快递公司的编码,一律用小写字母
numberstring订阅的快递单号,单号的最大长度是40个字符
fromstring快递寄件地址
tostring快递收件地址
parametersObject辅助参数

parameters数据结构:

参数名是否必填类型说明
callbackurlstring回调接口的地址
saltstring签名用随机字符串
phonestring收寄件人的移动电话号码(只能填写一个,顺丰速运和丰网速运必填,其他快递公司选填)
ordertimestring订单下单时间,格式“yyyy-MM-dd HH:mm:ss”

1.3 请求示例

schema = json
param = {
    "company": "ems",
    "number": "1136281381675",
    "from": "广东省深圳市南山区",
    "to": "北京市朝阳区",
    "key": "XXX ",
    "parameters": {
        "callbackurl": "您的回调接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
        "salt": "*",
        "phone": "",
        "ordertime": "2020-12-31 08:09:00"
    }
  }

1.4 订阅返回结果

字段名称类型是否必填字段含义
resultBooleantrue表示成功,false表示失败
returnCodestring返回状态码,详细见1.6附表
messagestring状态信息

1.5 订阅响应报文示例(json格式)

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

1.6 状态码附表

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

二、推送接口

1.使用http协议表单提交的方式进行信息交互,字符编码默认统一采用UTF-8,数据格式:application/x-www-form-urlencoded;

2.字段类型约定:需要严格依据字段表格中给出的参数格式和大小进行开发。

3.字段解析约定:参数字段中的必选字段是每次调用接口时都要求必须传入的;

2.1 推送请求地址

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

2.2 推送请求方式

post

2.3 推送输入参数

请求参数(header)

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

请求报文(body)

参数名是否必填类型说明
signstring订阅参数salt值不为空时,推送数据将包含该加密签名,加密方式:md5(param+salt)
paramObject主体参数对象

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),则回调请求中暂无此字段
lastResultObject 最新查询轨迹结果

lastResult对应参数

字段名称类型字段含义
messageString消息体,请忽略
stateInteger快递单当前状态,包括0在途,1揽收,2疑难,3签收,4退签,5派件,6退回,7转单,10待清关,11清关中,12已清关,13清关异常,14收件人拒签等13个状态
statusInteger通讯状态,请忽略
conditionString快递单明细状态标记,暂未实现,请忽略
ischeckInteger是否签收标记,请忽略,明细状态请参考state字段
comString快递公司编码,一律用小写字母
nuString单号
trailUrlString轨迹地图链接
arrivalTimeString预计到达时间
totalTimeString平均耗时
remainTimeString到达还需多少时间
isLoopBoolean是否存在环路
ΘrouteInfo 路由信息
└Θfrom 出发地行政区信息
└number 政区信息编码
└name 政区信息名
└Θcur 当前地行政区信息
└number 政区信息编码
└name 政区信息名
└Θto 目的地行政区信息
└number 政区信息编码
└name 政区信息名
Θdatadata最新查询结果,数组,包含多项,全量,倒序(即时间最新的在最前),每项都是对象,对象包含字段请展开
└ contextString内容
└ timeString时间,原始格式
└ ftimeString格式化后时间
└statusString本数据元对应的签收状态,只有实时查询接口中提交resultv2标记后才会出现
└areaCodeString本数据元对应的行政区域的编码,只有实时查询接口中提交resultv2标记后才会出现
└areaNameString本数据元对应的行政区域的名称,只有实时查询接口中提交resultv2标记后才会出现

2.4 推送输入参数示例

param = {
	"status": "polling",
	"billstatus": "got",
	"message": "",
	"autoCheck": "1",
	"comOld": "yuantong",
	"comNew": "ems",
	"lastResult": {
		"message": "ok",
		"state": "0",
		"status": "200",
		"condition": "F00",
		"ischeck": "0",
		"com": "yuantong",
		"nu": "V030344422",
		"data": [{
			"context": "上海分拨中心/装件入车扫描 ",
			"time": "2012-08-28 16:33:19",
			"ftime": "2012-08-28 16:33:19",
			"status": "在途",
			"areaCode": "310000000000",
			"areaName": "上海市"
		}, {
			"context": "上海分拨中心/下车扫描 ",
			"time": "2012-08-27 23:22:42",
			"ftime": "2012-08-27 23:22:42",
			"status": "在途",
			"areaCode": "310000000000",
			"areaName": "上海市"
		}],
		"routeInfo": {
			"from": {
				"number": "CN3100",
				"name": "上海市"
			},
			"cur": {
				"number": "CN6101",
				"name": "陕西,西安市"
			},
			"to": {
				"number": "CN6101",
				"name": "陕西,西安市"
			}
		},
		"isLoop": false,
		"trailUrl": "https://api.kuaidi100.com/tools/map/bc80574d538262aecc897a469151f0e3",
		"arrivalTime": "2020-12-19 12:00",
		"totalTime": "2天1小时",
		"remainTime": "1天2小时"
	}
}

2.5 轨迹链接应用示例

重要提醒:

(1)对于status= abort而且message中包含“3天”关键字而且comNew为空的快递单,需要增加以下处理逻辑:

  • 如果有专门的工作人员,可以:将快递单罗列给工作人员,由工作人员判断此单是否为假单:如果此单是真实单,则将此单重新向快递100提交一次;如果此单是假单,则将此单标记为假单,而且不再将此单提交给快递100。如果没有专门的工作人员,请直接用以下第二种方法进行操作;
  • 如果没有专门的工作人员,可以:在收到status=abort而且message中包含“3天”关键字而且comNew为空的提示10分钟后,将此快递单重新向快递100提交订阅,如果重新提交后仍然收到status= abort,则再次重新向快递100提交,如此,在同一月中如果重复提交3~4次都仍然收到status= abort,则此单为假单,不需要再将此单提交给快递100。

    对于同一自然月内重复提交的快递单,结算时只计一次费用,对于跨了两个自然月重复提交的结算单,结算两次费用。

(2)如果判断到status=abort且comNew不为空,则不需要重新提交订阅,且将贵司原来的快递公司编码改为comNew后的值,或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单;

(3)如果判断到status=polling且autoCheck=1,则此单为纠正公司编码后的跟踪信息,应保存。

  • 关于data:我方每次推送的都是完整的、全量的快递查询结果,而不是部分最新、增量的状态。由于同一快递单查询结果的数据源可能变动,不同数据源之间的结果略有差异,建议每次删除旧的数据后再写入新的数据。
  • 时间建议以ftime为准,不要使用time,time的存在仅仅为了兼容。

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

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

2.7 推送返回示例

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

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

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

2.8 运单签收状态(已签收、退回等)增值服务说明

​ 默认状态下,在推送时我们提供了ischeck字段表示快递单是否签收(含正常签收,退回签收两种情况),通过state字段提供签收的具体状态,state具体如下:

状态值名称含义
0在途快件处于运输过程中
1揽收快件已由快递公司揽收
2疑难快递100无法解析的状态,或者是需要人工介入的状态, 比方说收件人电话错误。
3签收正常签收
4退签货物退回发货人并签收
5派件货物正在进行派件
6退回货物正处于返回发货人的途中
7转投货物转给其他快递公司邮寄
10待清关货物等待清关
11清关中货物正在清关流程中
12已清关货物已完成清关流程
13清关异常货物在清关过程中出现异常
14拒签收件人明确拒收

签收状态服务能够对目前市面上大多数快递单状态进行准确判定。

若state=0,则condition如下值代表如下状态:

状态值名称含义
CU001等待清关货物等待清关
CU002清关中货物正在清关流程中
CU003已清关货物已完成清关流程
CU004清关异常货物在清关过程中出现异常
JQ001收件人拒签收件人明确拒收

三、快递公司编码

下载表格

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