实时快递单号查询技术文档
一、实时快递查询接口
用户向接口提交快递单号后，接口会实时调取快递公司的单号信息并返回此单号最新的物流信息，包括物流轨迹、状态、时间等。
注意：请控制每一单查询频率至少在半小时以上，否则会造成锁单。
1.1 请求地址
https://poll.kuaidi100.com/poll/query.do
1.2 请求类型
post
1.3 输入参数
请求参数（header）
| 名称 | 类型 | 默认值 |
|---|---|---|
| Content-Type | string | application/x-www-form-urlencoded |
请求参数（body）
| 名称 | 类型 | 是否必需 | 示例值 | 描述 |
|---|---|---|---|---|
| customer | String | 是 | 授权码，请申请企业版获取 | |
| sign | String | 是 | 签名， 用于验证身份， 按param + key + customer 的顺序进行MD5加密（注意加密后字符串一定要转32位大写）， 不需要加上“+”号 | |
| Θparam | Object | 是 | 由其他字段拼接 | |
| └ com | string | 是 | yuantong | 查询的快递公司的编码， 一律用小写字母 下载编码表格 |
| └ num | string | 是 | 12345678 | 查询的快递单号， 单号的最小长度6个字符，最大长度32个字符 |
| └ phone | string | 否 | 13888888888 | 收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰速运、顺丰快运必填，其他快递公司选填。如座机号码有分机号，分机号无需传入；如号码是电商虚拟号码需传入“-“后的后四位。查看详情） |
| └ from | string | 否 | 广东深圳 | 出发地城市，需要时效预测信息 |
| └ to | string | 否 | 北京朝阳 | 目的地城市，到达目的地后会加大监控频率；需要时效预测信息，即入参resultv2=8时必填 |
| └ resultv2 | string | 否 | 1 | 添加此字段表示开通行政区域解析功能。空：关闭（默认）； 1：开通行政区域解析功能以及物流轨迹增加物流状态名称； 4: 开通行政解析功能以及物流轨迹增加物流高级状态名称、状态值并且返回出发、目的及当前城市信息； 8：在4的基础上额外返回预计到达时间和预计轨迹信息，支持的快递公司见在途时效预估支持的快递公司 |
| └show | String | 否 | 0 | 返回格式：0：json格式（默认），1：xml，2：html，3：text |
| └order | String | 否 | desc | 返回结果排序:desc降序（默认）,asc 升序 |
| └lang | String | 否 | en | 返回结果语言版本:支持中文和英文，zh:中文,en:英文 |
| └needCourierInfo | Boolean | 否 | True | 默认为false，当入参为true时，会尝试从物流轨迹中提取出快递员姓名和快递员电话并返回 |
1.4 请求参数示例
customer = **********
sign = ******************
param = {
"com": "ems",
"num": "em263999513jp",
"phone": "13868688888",
"from": "广东省深圳市南山区",
"to": "北京市朝阳区",
"resultv2": "4",
"show": "0",
"order": "desc",
"lang":"zh",
}
1.5 返回结果
| 字段名称 | 类型 | 字段含义 |
|---|---|---|
| message | String | 消息体，请忽略 |
| state | String | 快递单当前状态，默认为0在途，1揽收，2疑难，3签收，4退签，5派件，8清关，14拒签等10个基础物流状态，如需要返回高级物流状态，请参考 resultv2 传值 |
| status | String | 通讯状态，请忽略 |
| condition | String | 快递单明细状态标记，暂未实现，请忽略 |
| ischeck | String | 是否签收标记，0未签收，1已签收，请忽略，明细状态请参考state字段 |
| com | String | 快递公司编码,一律用小写字母 |
| nu | String | 单号 |
| Θdata | data | 最新查询结果，数组，包含多项，全量，倒序（即时间最新的在最前），每项都是对象，对象包含字段请展开 |
| └ context | String | 内容 |
| └ time | String | 时间，原始格式 |
| └ ftime | String | 格式化后时间 |
| └status | String | 本数据元对应的物流状态名称或者高级状态名称，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现 |
| └statusCode | String | 本数据元对应的高级物流状态值，实时查询接口中提交resultv2=4标记后才会出现 |
| └areaCode | String | 本数据元对应的行政区域的编码，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现 |
| └areaName | String | 本数据元对应的行政区域的名称，实时查询接口中提交resultv2=1或者resultv2=4标记后才会出现 |
| └areaCenter | String | 本数据元对应的行政区域经纬度，实时查询接口中提交resultv2=4标记后才会出现 |
| └location | String | 本数据元对应的快件当前地点，实时查询接口中提交resultv2=4标记后才会出现 |
| └areaPinYin | String | 本数据元对应的行政区域拼音，实时查询接口中提交resultv2=4标记后才会出现 |
| arrivalTime | String | 预计到达时间，格式为："2025-04-18 06"，实时查询接口中提交resultv2=8标记后才会出现 |
| totalTime | String | 平均耗时，格式为："1天19小时"，实时查询接口中提交resultv2=8标记后才会出现 |
| remainTime | String | 到达还需多少时间："0天0小时"，实时查询接口中提交resultv2=8标记后才会出现 |
| ΘpredictedRoute | data | 物流节点数据，包含物流轨迹上各个节点的信息，节点排序为从发货地址到收货地址，实时查询接口中提交resultv2=8标记后才会出现 |
| └arriveTime | String | 到达节点时间，格式为："2025-04-16 10:36:46" |
| └leaveTime | String | 离开节点时间，格式为："2025-04-16 10:39:03" |
| └province | String | 节点所在省，例如"湖北" |
| └city | String | 节点所在市，例如"宜昌市" |
| └district | String | 节点所在区，例如"点军区" |
| └name | String | 节点名称，例如"武汉转运中心" |
| └state | String | 当前节点状态：已经过节点、当前停留节点、预估途径节点 |
| └type | String | 当前节点类型：转运中心、网点 |
| ΘcourierInfo | data | 从物流轨迹中提取出的快递员信息，当且仅当入参needCourierInfo=True时会返回 |
| └pickupManName | String | 揽件快递员姓名，例如："张三"，如提取不到会返回空字符串 |
| └pickupManPhone | String | 揽件快递员手机号，格式为："12335467890"，如提取出多个手机号，会使用逗号分隔，例如"1234567890,1983782937",提取不到会返回空字符串 |
| └deliveryManName | String | 派件快递员姓名，例如："李四"，如提取不到会返回空字符串 |
| └deliveryManPhone | String | 派件快递员手机号，格式为："12335467890"，如提取出多个手机号，会使用逗号分隔，例如"1234567890,1983782937",提取不到会返回空字符串 |
1.6 运单快递状态（state)说明
| 物流状态值 | 物流状态名称 | 高级物流状态值 | 高级物流状态名称 | 含义 |
|---|
| 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 | 破损 | 快件破损 | ||
| 210 | 销单 | 寄件人申请撤销寄件 | ||
| 8 | 清关 | 8 | 清关 | 快件清关 |
| 10 | 待清关 | 快件等待清关 | ||
| 11 | 清关中 | 快件正在清关流程中 | ||
| 12 | 已清关 | 快件已完成清关流程 | ||
| 13 | 清关异常 | 货物在清关过程中出现异常 |
注：如需物流状态高级状态名称及状态值需要 resultv2 传 “4” 返回
1.7 正确返回示例
JSON格式
{
"message": "ok",
"nu": "YT25569986666541",
"ischeck": "0",
"com": "yuantong",
"status": "200",
"data": [
{
"time": "2025-06-13 15:56:19",
"context": "您的快件离开【安徽省六安市叶集实验区】，已发往【安徽省六安市】",
"ftime": "2025-06-13 15:56:19",
"areaCode": "CN341522000000",
"areaName": "安徽,六安市,霍邱县",
"status": "在途",
"location": "六安市,霍邱县",
"areaCenter": "116.277912,32.353038",
"areaPinYin": "huo qiu xian",
"statusCode": "0"
},
{
"time": "2025-06-13 15:53:52",
"context": "您的快件在【安徽省六安市叶集实验区】已揽收",
"ftime": "2025-06-13 15:53:52",
"areaCode": "CN341522000000",
"areaName": "安徽,六安市,霍邱县",
"status": "揽收",
"location": "六安市,霍邱县",
"areaCenter": "116.277912,32.353038",
"areaPinYin": "huo qiu xian",
"statusCode": "1"
}
],
"state": "0",
"condition": "00",
"routeInfo": {
"from": {
"number": "CN430112000000",
"name": "湖南,长沙市,望城区"
},
"cur": {
"number": "CN341522000000",
"name": "安徽,六安市,霍邱县"
},
"to": {
"number": "CN320583104000",
"name": "江苏,苏州市,昆山市,花桥镇"
}
},
"isLoop": false,
"arrivalTime": "2025-06-14 13",
"totalTime": "0天21小时",
"remainTime": "0天20小时",
"predictedRoute": [
{
"arriveTime": "2025-06-13 15:53:52",
"leaveTime": "2025-06-13 15:56:19",
"province": "安徽",
"city": "六安市",
"district": "叶集区",
"name": "安徽省六安市叶集实验区",
"state": "已经过节点",
"type": "网点"
},
{
"arriveTime": "2025-06-13 19:05:19",
"leaveTime": "2025-06-13 19:59:19",
"province": "安徽",
"city": "六安市",
"district": "金安区",
"name": "安徽省六安市",
"state": "预估途径节点",
"type": "网点"
},
{
"arriveTime": "2025-06-13 23:09:19",
"leaveTime": "2025-06-13 23:16:19",
"province": "安徽",
"city": "合肥市",
"district": "肥东县",
"name": "合肥转运中心",
"state": "预估途径节点",
"type": "转运中心"
},
{
"arriveTime": "2025-06-14 06:58:19",
"leaveTime": "2025-06-14 07:17:19",
"province": "江苏",
"city": "无锡市",
"district": "新吴区",
"name": "苏州转运中心",
"state": "预估途径节点",
"type": "转运中心"
},
{
"arriveTime": "2025-06-14 12:29:19",
"leaveTime": "2025-06-14 13:46:19",
"province": "江苏",
"city": "苏州市",
"district": "昆山市",
"name": "江苏省昆山市城区",
"state": "预估途径节点",
"type": "网点"
}
]
}
1.8 错误返回示例
JSON格式
{
"result": false,
"returnCode": "400",
"message": "找不到对应公司"
}
1.8 信息代码含义
| 信息代码 | 信息内容描述 | 原因及建议处理方式 |
|---|---|---|
| 200 | 查询成功 | 查询成功 |
| 400 | 找不到对应公司 | 提交数据不完整或者账号未充值, 检查提交的格式是否为x-www-form-urlencoded的post格式 |
| 408 | 快递公司参数异常：验证码错误 | 电话号码校验不通过，检查是否提交了收、寄件人正确的电话号码 |
| 500 | 查询无结果，请隔段时间再查 | 未查询到物流信息，需确认快递公司和快递单号是否正确，是否已发货 |
| 501 | 服务器错误 | 快递100的服务器出现间歇或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数没有按照文档规定填写等，也会报此错误 |
| 502 | 服务器繁忙 | 快递100的服务器出现间歇或临时性异常，请联系快递100排查原因 |
| 503 | 验证签名失败 | 请检查加密方式，param + key + customer 的顺序进行MD5加密，加密后字符串转大写 |
| 601 | key已过期 | 没有可用单量，账号需要充值使用 |
二、快递公司编码
如果您需要的公司不在此列表，请联系在线客服添加
