快递查询地图轨迹技术文档
POST
https://poll.kuaidi100.com/poll/maptrack.do1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回格式支持JSON,xml,text,html数据。
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
com | 是 | string | 查询的快递公司的编码, 一律用小写字母 |
num | 是 | string | 查询的快递单号, 单号的最大长度是32个字符 |
phone | 否 | string | 收、寄件人的电话号码(手机和固定电话均可,只能填写一个,顺丰速运和丰网速运必填,其他快递公司选填。如座机号码有分机号,分机号无需上传。) |
from | 是 | string | 出发地信息,如:广东省深圳市南山区金蝶软件园 |
to | 是 | string | 目的地信息,如:北京朝阳区国际金融大厦 |
resultv2 | 否 | string | 添加此字段表示开通行政区域解析功能。0:关闭(默认),1:开通行政区域解析功能以及物流轨迹增加物流状态值,2:开通行政解析功能以及物流轨迹增加物流状态值并且返回出发、目的及当前城市信息 4:开通行政解析功能以及物流轨迹增加物流高级状态名称并且返回出发、目的及当前城市信息 6:开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息 |
show | 否 | string | 返回格式:0:json格式(默认),1:xml,2:html,3:text |
order | 否 | string | 返回结果排序:desc降序(默认),asc 升序 |
orderTime | 否 | string | 订单下单时间,格式为(yyyy-MM-dd HH:mm:ss)如:2021-08-05 15:20:00 |
注:如需物流状态高级状态名称及状态值需要 resultv2 传 “6” 返回,如需物流状态高级状态名称需要 resultv2 传 “4” 返回
6 运单签收状态服务说明
物流状态值 | 物流状态名称 | 高级物流状态值 | 高级物流状态名称 | 含义 |
---|---|---|---|---|
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 | 破损 | 快件破损 | ||
8 | 清关 | 8 | 清关 | 快件清关 |
10 | 待清关 | 快件等待清关 | ||
11 | 清关中 | 快件正在清关流程中 | ||
12 | 已清关 | 快件已完成清关流程 | ||
13 | 清关异常 | 货物在清关过程中出现异常 | ||
14 | 拒签 | \ | \ | 收件人拒签快件 |
注:如需物流状态高级状态名称及状态值需要 resultv2 传 “6” 返回,如需物流状态高级状态名称需要 resultv2 传 “4” 返回
7 轨迹链接应用示例
8 错误返回示例
{
"result": false,
"returnCode": "400",
"message": "找不到对应公司"
}
Copy
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
200 | 查询成功 | 查询成功 |
400 | 参数权限问题 | 数据不完整,找不到对应公司,非法IP,请申请授权,不支持此快递公司,单号问题等 |
500 | 查询无结果,请隔段时间再查 | 表示查询失败,去快递公司没获取有效数据 |
501 | 服务器错误 | 快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数没有按照文档规定填写等,也会报此错误 |
502 | 服务器繁忙 | 快递100的服务器出现间歇或临时性异常,请联系快递100排查原因 |
503 | 验证签名失败 | 请检查加密方式,param + key + customer 的顺序进行MD5加密,加密后字符串转大写 |
601 | 没该功能权限 | 没有可用单量或没有开启权限 |
请求参数
Body 参数application/x-www-form-urlencoded
customer
string
必需
授权码,请申请企业版获取
sign
string
必需
签名, 用于验证身份, 按param + key + customer 的顺序进行MD5加密(注意加密后字符串一定要转32位大写), 不需要加上“+”号
param
string
由其他字段拼接
示例值:
{ "com": "ems", "num": "em263999513jp", "phone": "13868688888", "from": "广东省深圳市南山区金蝶软件园", "to": "北京朝阳区国际金融大厦", "show": "0", "order": "desc", "orderTime": "2020-12-16 12:59:59"}
示例代码
返回响应
成功(200)
错误返回示例(200)
HTTP 状态码: 200
内容格式: JSONapplication/json
数据结构
message
string
消息体,请忽略
nu
string
单号
ischeck
string
必需
是否签收标记,请忽略,明细状态请参考state字段
com
string
必需
快递公司编码,一律用小写字母
status
string
通讯状态,请忽略
data
array [object {6}]
必需
最新查询结果,数组,包含多项,全量,倒序(即时间最新的在最前),每项都是对象,对象包含字段请展开
time
string
时间,原始格式
context
string
内容
ftime
string
格式化后时间
areaCode
null | string
必需
本数据元对应的签收状态,只有实时查询接口中提交resultv2标记后才会出现
areaName
null | string
必需
本数据元对应的行政区域的编码,只有实时查询接口中提交resultv2标记后才会出现
status
string
必需
本数据元对应的行政区域的名称,只有实时查询接口中提交resultv2标记后才会出现
state
string
必需
快递单当前状态,默认为0在途,1揽收,2疑难,3签收,4退签,5派件,8清关,14拒签等10个主状态,如需要返回高级状态,请参考 resultv2 传值
condition
string
必需
快递单明细状态标记,暂未实现,请忽略
routeInfo
object
必需
from
object
出发地行政区信息
cur
object
当前地行政区信息
to
object
目的地行政区信息
isLoop
boolean
是否存在环路
trailUrl
string
轨迹地图链接
arrivalTime
string
预计到达时间
totalTime
string
平均耗时
remainTime
string
到达还需多少时间
示例
成功示例
{
"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",
"totalTime": "2天1小时",
"remainTime": "1天2小时"
}
最后修改时间: 2 年前