快递100查询地图轨迹API接口案例代码

一、 快递查询地图轨迹

1.1 接口格式

提供统一格式的HTTP POST或GET调用接口,并返回格式支持JSON，xml，text，html数据。

1.2 请求地址

https://poll.kuaidi100.com/poll/maptrack.do

请求参数：

参数名	是否必填	类型	说明
customer	是	string	授权码，请<a href="https://api.kuaidi100.com/register/enterprise" target="_blank">申请企业版</a>获取
sign	是	string	签名， 用于验证身份， 按param + key + customer 的顺序进行MD5加密（注意加密后字符串一定要转32位大写）， 不需要加上“+”号
param	是	param	由其他字段拼接

param数据结构：

参数名	是否必填	类型	说明
com	是	string	查询的快递公司的编码， 一律用小写字母
num	是	string	查询的快递单号， 单号的最大长度是32个字符
phone	否	string	收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。）
from	是	string	出发地信息，如：广东省深圳市南山区金蝶软件园
to	是	string	目的地信息，如：北京朝阳区国际金融大厦
show	否	string	返回格式：0：json格式（默认），1：xml，2：html，3：text
order	否	string	返回结果排序:desc降序（默认）,asc 升序
orderTime	否	string	订单下单时间，格式为（yyyy-MM-dd HH:mm:ss）如：2020-12-16 12:59:59

1.3 请求实例

customer=**  sign=**  param={    "com":"ems",    "num":"em263999513jp",    "phone":"13868688888",    "from":"广东省深圳市南山区金蝶软件园",    "to":"北京朝阳区国际金融大厦",    "show":"0",    "order":"desc",    "orderTime":"2020-12-16 12:59:59"  }

1.4 返回结果

字段名称	类型	字段含义
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标记后才会出现

1.5 提供数据内容

{    "message": "ok",    "nu": "YT4781863654577",    "ischeck": "1",    "com": "yuantong",    "status": "200",    "data": [{        "time": "2020-11-30 13:19:56",        "context": "圆通合作点【喵站】快件已到达财富金街院里3号底商驿站,联系电话18744663997",        "ftime": "2020-11-30 13:19:56",        "areaCode": null,        "areaName": null,        "status": "在途"    }, {        "time": "2020-09-12 17:40:58",        "context": "【广东省深圳市平湖公司】 已收件 取件人: 刘杰珍 (18128837173)",        "ftime": "2020-09-12 17:40:58",        "areaCode": "CN440307003000",        "areaName": "广东,深圳市,龙岗区,平湖",        "status": "揽收"    }],    "state": "3",    "condition": "00",    "routeInfo": {        "from": {            "number": "CN4403",            "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小时"}

1.6 运单签收状态服务说明

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

1.7 轨迹链接应用示例

<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/782a47be14834488bd62d3bd4163c37d~tplv-k3u1fbpfcp-zoom-1.image" style="zoom:60%">

1.8 错误返回示例

{"result":false,"returnCode":"400","message":"找不到对应公司"}

信息代码	信息内容描述	原因及建议处理方式
200	查询成功	查询成功
400	参数权限问题	数据不完整，找不到对应公司，非法IP，请申请授权，不支持此快递公司，单号问题等
500	查询无结果，请隔段时间再查	表示查询失败，去快递公司没获取有效数据
501	服务器错误	快递100的服务器出理间隙或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数没有按照文档规定填写等，也会报此错误
502	服务器繁忙	快递100的服务器出理间隙或临时性异常，请联系快递100排查原因
503	验证签名失败	请检查加密方式，param + key + customer 的顺序进行MD5加密，加密后字符串转大写
601	没该功能权限	没有可用单量或没有开启权限

一、快递查询地图轨迹API产品介绍

快递100快递查询地图轨迹接口提供给企业及最终用户快递单号的地图轨迹展示、物流节点文字信息及预计送达时间，可视化展示物流轨迹信息。

通过调用地图轨迹接口，可展示地图轨迹、物流节点信息、预计到达时间、快递单状态等信息，多样化物流信息展示维度，提高客户查询体验。

二、快递查询地图轨迹API应用场景

1. 在电商网页/APP/小程序中，顾客在订单详情里查看购买商品的物流地图轨迹；

2. 和物流轨迹文字信息一同展示给顾客，可视化订单的在途状态；

3. 获得物流途径城市的信息，监控快递时效；

4. 预估包裹的到达时间，以及提示包裹还需多长时间到达，识别快递状态·，发送提醒客户签收短信；

三、快递查询地图轨迹API收费模式

1.收费方式

快递查询地图轨迹属于增值类服务，该服务同时支持物流文字信息以及地图链接，即包含了实时查询接口的功能。注册快递100企业账号后可以在企业管理后台<a href="https://api.kuaidi100.com/service/map" target="_blank">查看地图轨迹套餐</a>价格并购买。

2.收费价格

新品限时特惠，活动时间：2021年1月1日-2021年3月31日，充值后即可开通使用。

原价/元	优惠价/元	单量	赠送/单	优惠单价/元
3000	2000	20000	5000	0.08
1500	1000	10000	2000	约0.084
750	500	5000	500	约0.09
150	100	1000		0.1

快递查询地图轨迹按单计费，一个自然月内同一个运单多次查询只收一次费用。该接口单独计费。

3.开具发票

快递100支持开具增值税发票，用户购买完成后可在企业管理后台-费用中心-支付记录-请求开票。默认开具电子增值税普通发票，1000元以上可支持开具增值税专用发票。

官方源文档：

http://api.kuaidi100.com/document/5ff2c2b9ba1bf00302f5612d.html

http://api.kuaidi100.com/document/5ff2c3e7ba1bf00302f5612e.html