快递100轨迹查询-电商快递地图轨迹推送服务API接口案例代码

原创

快递100API

修改于 2021-05-18 10:10:24

1.7K0

修改于 2021-05-18 10:10:24

文章被收录于专栏：程序员也要懂业务

一、地图轨迹订阅接口

1.1 接口格式

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

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

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

1.2 请求地址

http://poll.kuaidi100.com/pollmap

请求报文：

参数名	是否必填	类型	说明
schema	否	string	默认是json
param	是	Object	主体参数对象

param数据结构：

参数名	是否必填	类型	说明
key	是	string	授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取
company	是	string	订阅的快递公司的编码，一律用小写字母
number	是	string	订阅的快递单号，单号的最大长度是40个字符
from	是	string	快递寄件地址
to	是	string	快递收件地址
parameters	是	Object	辅助参数

parameters数据结构：

参数名	是否必填	类型	说明
callbackurl	是	string	回调接口的地址
salt	否	string	签名用随机字符串
phone	否	string	收寄件人的移动电话号码（只能填写一个，顺丰单号必填，其他快递公司选填）
ordertime	否	string	订单下单时间，格式“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 订阅返回结果

字段名称	类型	是否必填	字段含义
result	Boolean	是	true表示成功，false表示失败
returnCode	string	是	返回状态码，详细见1.6附表
message	string	是	状态信息

1.5 订阅响应报文示例（json格式）

{

  "result": true,

  "returnCode": "200",

  "message": "提交成功"

}

1.6 状态码附表

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

二、推送接口

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

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

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

2.1 推送请求地址

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

2.2 推送请求方式

post

2.3 推送输入参数

请求参数（header）

名称	类型	默认值
Content-Type	string	application/x-www-form-urlencoded

请求报文（body）

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

param对应参数

参数名	是否必填	类型	说明
status	String	polling	监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于status=abort的状态，需要增加额外的处理逻辑
billstatus	String	got	包括got、sending、check三个状态，由于意义不大，已弃用，请忽略
message	String		监控状态相关消息，如:3天查询无记录，60天无变化
autoCheck	String	1	快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码，1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
comOld	String	yuantong	贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
comNew	String	ems	我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段
lastResult	Object		最新查询轨迹结果

lastResult对应参数

字段名称	类型	字段含义
message	String	消息体，请忽略
state	Integer	快递单当前状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回，7转单，10待清关，11清关中，12已清关，13清关异常，14收件人拒签等13个状态
status	Integer	通讯状态，请忽略
condition	String	快递单明细状态标记，暂未实现，请忽略
ischeck	Integer	是否签收标记，请忽略，明细状态请参考state字段
com	String	快递公司编码,一律用小写字母
nu	String	单号
trailUrl	String	轨迹地图链接
arrivalTime	String	预计到达时间
totalTime	String	平均耗时
remainTime	String	到达还需多少时间
isLoop	Boolean	是否存在环路
ΘrouteInfo		路由信息
└Θfrom		出发地行政区信息
└number		政区信息编码
└name		政区信息名
└Θcur		当前地行政区信息
└number		政区信息编码
└name		政区信息名
└Θto		目的地行政区信息
└number		政区信息编码
└name		政区信息名
Θdata	data	最新查询结果，数组，包含多项，全量，倒序（即时间最新的在最前），每项都是对象，对象包含字段请展开
└ context	String	内容
└ time	String	时间，原始格式
└ ftime	String	格式化后时间
└status	String	本数据元对应的签收状态，只有实时查询接口中提交resultv2标记后才会出现
└areaCode	String	本数据元对应的行政区域的编码，只有实时查询接口中提交resultv2标记后才会出现
└areaName	String	本数据元对应的行政区域的名称，只有实时查询接口中提交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 推送响应报文及错误码解释

参数名	说明
result	true表示成功，false表示失败。如果提交回调接口的地址失败，30分钟后重新回调，3次仍旧失败的，自动放弃
returnCode	200: 提交成功 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	收件人拒签	收件人明确拒收

三、快递公司编码

一、地图轨迹推送服务API产品介绍

快递100地图轨迹推送服务接口提供快递单号的地图轨迹展示、物流节点文字信息及预计送达时间，可视化展示物流轨迹信息。

通过地图轨迹推送服务接口，企业提交快递单号，快递100接收到后便对这些运单进行跟踪，当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息和地图轨迹推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待下一次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。