地图轨迹推送接口文档

一、订阅接口

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

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

1.1 接口格式

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

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

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

1.2 请求地址

http://poll.kuaidi100.com/pollmap

请求参数（header）

请求参数（body）

param数据结构：

parameters数据结构：

1.3 请求示例

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

1.4 订阅返回结果

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

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

1.6 信息代码含义

二、推送接口

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

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

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

2.1 推送请求地址

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

2.2 推送请求方式

post

2.3 推送输入参数

请求参数（header）

请求参数（body）

param数据结构

lastResult数据结构

2.4 推送输入参数示例

param = {
	"status": "polling",
	"billstatus": "got",
	"message": "",
	"lastResult": {
		"message": "ok",
		"state": "0",
		"status": "200",
		"condition": "F00",
		"ischeck": "0",
		"com": "ems",
		"nu": "V030344422",
		"data": [{
			"context": "【深圳市】 快件已在 【新南山科技北】 签收, 签收人: 家门口",
			"time": "2020-12-19 16:33:19",
			"ftime": "2020-12-19 16:33:19",
			"status": "签收",
			"areaCode": "CN440305000000",
			"areaName": "广东,深圳市,南山区",
			"location": "新南山科技北",
			"areaCenter": "113.923552,22.528499",
			"areaPinYin": "nan shan qu",
			"statusCode": "3", 
		}, {
			"context": "[深圳市】 【新南山科技北]正在第1次派件",
			"time": "2020-12-19 15:30:10",
			"ftime": "2020-12-19 15:30:10",
			"status": "派件",
			"areaCode": "CN440305000000",
			"areaName": "广东,深圳市,南山区",
			"location": "新南山科技北",
			"areaCenter": "113.923552,22.528499",
			"areaPinYin": "nan shan qu",
			"statusCode": "5"
		}],
		"routeInfo": {
			"from": {
				"number": "CN410202000000",
				"name": "吉林,辽源市,东丰县"
			},
			"cur": {
				"number": "CN440305000000",
				"name": "广东,深圳市,南山区"
			},
			"to": {
				"number": "CN440305000000",
				"name": "广东,深圳市,南山区"
			}
		},
		"isLoop": false,
		"trailUrl": "https://api.kuaidi100.com/tools/map/bc80574d538262aecc897a469151f0e3",
		"arrivalTime": "2020-12-19 16",
		"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。

  对于40天内重复提交的快递单，结算时只计一次费用，对于从首次查询时间起算，超出40天的重复提交的快递单，结算两次费用。

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

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

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

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

2.7 推送返回示例

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

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

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

2.8 运单签收状态（state)说明

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

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

三、快递公司编码

下载表格

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