参数名	类型	必填	说明	示例
key	string	是	接口调用密钥
action	string	是	操作方法	query
num	string	是	单号	9831719725623

快递查询

接口说明

提供快递单号物流轨迹查询服务，支持全球3000+快递公司，适用于电商、物流、仓储等场景快速获取快件实时状态。调用方传入授权密钥与快递单号，接口返回完整的物流节点记录、当前位置及末端派送员联系方式。

调用地址

https://api.example.com/api/express/100/index.php

请求方式

支持 GET 和 POST 两种请求方式，推荐使用 POST 方式提交参数。

鉴权说明

本接口采用 Query 参数鉴权方式。调用方需在请求 URL 中附带 key 参数传递接口密钥，例如：?key=YOUR_API_KEY。密钥是调用本接口的必要条件，未携带或携带错误密钥将返回鉴权失败响应。请妥善保管密钥，避免在公开场合泄露。

请求参数

所有参数通过 Query 传递，密钥以 key 参数形式传入。

参数名	类型	必填	说明
key	string	是	接口调用密钥，通过 Query 传递，如 `?key=YOUR_KEY`
action	string	是	操作方法，取值固定为 `query`
num	string	是	快递单号，如 `9831719725623`

成功响应示例

{
  "code": 1,
  "message": "success",
  "data": {
    "hit": 1,
    "status": "200",
    "lastResult": {
      "message": "ok",
      "nu": "9831719725623",
      "routeInfo": {
        "to": { "name": "广东,深圳市", "number": "CN440300000000" },
        "cur": { "name": "广东,深圳市", "number": "CN440300000000" },
        "from": { "name": "浙江,金华市", "number": "CN330700000000" }
      },
      "num": "youzhengguonei",
      "ischeck": "1",
      "com": "youzhengguonei",
      "status": "200",
      "condition": "H100",
      "subStatus": "303",
      "data": [
        {
          "statusCode": "3",
          "time": "2026-05-08 12:02:17",
          "areaName": "广东,深圳市",
          "areaCode": "CN440300000000",
          "status": "签收",
          "location": "广东省,深圳市",
          "areaCenter": "114.057868,22.543099",
          "context": "您的快件已代收【物业代收，家门口】，如有疑问请电联快递员【钟欢，电话:13823191550】，投诉电话【电话:13728675481】。有事呼叫我，少一次投诉，多一份感恩。中国邮政将全心呵护您的所托，服务热线11183。",
          "ftime": "2026-05-08 12:02:17",
          "areaPinYin": "shen zhen shi"
        }
      ],
      "state": "3",
      "isLoop": false
    },
    "courierMobile": "13823191550",
    "company": {
      "code": "youzhengguonei",
      "name": "邮政快递包裹"
    }
  }
}

响应字段说明

字段路径	类型	说明
code	integer	状态码，1 表示请求成功
message	string	状态描述信息
data.hit	integer	是否命中快递公司，1 表示命中
data.status	string	查询状态码，200 表示查询成功
data.lastResult.message	string	底层接口返回消息
data.lastResult.nu	string	快递单号
data.lastResult.routeInfo.to.name	string	目的地城市名称
data.lastResult.routeInfo.to.number	string	目的地行政区划编码
data.lastResult.routeInfo.cur.name	string	当前所在城市名称
data.lastResult.routeInfo.cur.number	string	当前城市行政区划编码
data.lastResult.routeInfo.from.name	string	始发城市名称
data.lastResult.routeInfo.from.number	string	始发城市行政区划编码
data.lastResult.num	string	快递公司编码（与 com 一致）
data.lastResult.ischeck	string	是否已签收，1 表示已签收
data.lastResult.com	string	快递公司编码
data.lastResult.condition	string	天气或路况条件码
data.lastResult.subStatus	string	子状态码，用于区分派送/退回等细分场景
data.lastResult.state	string	物流状态码：1 揽收、2 在途、3 签收
data.lastResult.isLoop	boolean	是否存在循环转运，true 表示存在
data.lastResult.data[]	array	物流轨迹明细列表
data.lastResult.data[].statusCode	string	轨迹状态码：1 揽收、3 签收、其他为中转节点
data.lastResult.data[].time	string	轨迹发生时间，格式 YYYY-MM-DD HH:mm:ss
data.lastResult.data[].areaName	string	轨迹所在城市名称
data.lastResult.data[].areaCode	string	轨迹所在城市行政区划编码
data.lastResult.data[].status	string	轨迹中文状态描述（如：揽收、派件、签收）
data.lastResult.data[].location	string	轨迹详细地址信息
data.lastResult.data[].areaCenter	string	轨迹地点经纬度，格式 lng,lat
data.lastResult.data[].context	string	轨迹详细描述内容
data.lastResult.data[].ftime	string	轨迹发生时间（与 time 一致）
data.lastResult.data[].areaPinYin	string	轨迹城市拼音
data.courierMobile	string	派件快递员手机号码
data.company.code	string	快递公司唯一编码
data.company.name	string	快递公司名称

错误响应示例

当调用发生错误时，接口将返回如下格式的 JSON：

{
  "code": 0,
  "msg": "未提供调用密钥",
  "errcode": 11001
}

各字段说明：

code：固定为 0，表示本次请求未按业务成功流程处理。
msg：人类可读的简短错误描述。
errcode：用于程序判断的具体业务错误码，见下表。

业务错误码说明

errcode	含义
11001	未提供调用密钥
11002	密钥错误
11003	密钥已禁用
11004	积分余额不足
11005	请求过于频繁（QPM 限制）
11006	接口维护中
11007	接口已禁用
11008	接口不可用
11009	密钥校验暂不可用
11010	积分系统暂不可用
11011	收费接口须提供有效密钥
11012	鉴权方式错误
11013	接口不存在
11014	***地址无效
11015	***地址不允许
11016	***请求失败
11017	服务暂不可用
11018	请求方式不允许
11019	当前IP不在白名单内
11020	启用出口代理须提供有效密钥
11021	未配置可用出口代理
11022	出口代理不可用
11023	密钥已过期
11024	令牌分配积分不足

调用示例

终端 curl（bash）

curl -X GET "https://您的域名/api/express/100/index.php?key=您的密钥&action=query&num=9831719725623"

PHP

// PHP
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://您的域名/api/express/100/index.php?key=您的密钥&action=query&num=9831719725623");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

注意事项

接口密钥通过 Query 参数 key 传递，请勿将密钥硬编码至前端代码或公开仓库，避免被恶意调用导致账户损失。
本接口为收费接口，使用前请确保账户余额充足，余额不足时请求将返回相应错误提示。
频率限制为每分钟约 60 次，超出限制将触发限流响应，请合理控制调用频率或申请扩容。
请求需使用 HTTPS 协议，以保障密钥及查询数据在传输过程中的安全性。
action 参数固定传 query，用于查询快递物流轨迹；num 参数为需要查询的快递单号，请确保单号格式正确且与快递公司对应。
接口支持全球 3000+ 快递公司，部分偏远地区或特殊渠道的物流更新可能存在延迟，建议适当延长轮询间隔。
返回数据中的物流节点时间（ftime）为服务器解析时间，可能与快递实际状态存在数分钟延迟，属正常现象。

免责声明

欢迎使用 万象数据API（以下简称“本平台”，域名为 api.vsaa.cn）。在使用本平台提供的任何接口、数据及相关服务之前，请您务必仔细阅读并充分理解本免责声明的全部内容。您对本平台任何服务的使用，均视为您已阅读、理解并同意本声明的全部条款。

1. 本平台仅提供**技术接口与数据聚合服务**，不存储、不生产、不拥有任何原始数据内容。 2. 本平台所返回的数据均来源于公开网络或第三方接口，仅作**技术学习、研究与交流**之用。 3. 本平台不保证任何接口的**持续可用性、准确性、完整性或及时性**，接口可能因第三方原因随时变更、中断或停止。 1. 使用者应遵守中华人民共和国相关法律法规，以及其所在地的所有适用法律。 2. **禁止**将本平台接口用于任何违法违规用途，包括但不限于： - 侵犯他人知识产权、隐私权或其他合法权益； - 从事网络攻击、数据爬取滥用、恶意刷量等行为； - 传播违法、有害、虚假或不良信息； - 用于任何商业转售、二次分发而未获授权的情形。 3. 使用者应自行承担因使用本平台服务而产生的一切后果与法律责任。 1. 本平台**不收集、不存储**使用者的个人敏感信息。 2. 使用者通过接口提交的查询参数，仅用于当次请求处理，不做持久化留存。 3. 若接口涉及第三方数据，其版权与解释权归原数据方所有，本平台不承担相关争议责任。 1. 本平台以**“现状”**和**“现有”**为基础提供服务，不对服务作出任何明示或暗示的担保。 2. 因使用或无法使用本平台服务而导致的任何**直接、间接、偶然或必然损失**，本平台及其运营者均不承担任何责任。 3. 因不可抗力、网络故障、第三方服务中断、政策调整等原因导致的服务异常，本平台不承担责任。 1. 本平台的接口设计、文档、代码及相关标识，其知识产权归本平台所有。 2. 未经书面许可，任何单位或个人不得复制、修改、传播或用于商业用途。 1. 本平台有权随时修改本免责声明，修改后的内容将在本页面公布，不再另行通知。 2. 使用者应定期查阅本声明，继续使用即视为接受变更后的条款。 1. 本声明的最终解释权归 **万象数据API** 所有。 2. 如您不同意本声明的任何内容，请立即停止使用本平台服务。 3. 如因本声明产生争议，双方应友好协商解决；协商不成的，可提交本平台运营者所在地有管辖权的人民法院裁决。

最后更新日期：2026年10月6日

快递查询

接口信息

请求参数

返回示例

详细文档

快递查询

接口说明

调用地址

请求方式

鉴权说明

请求参数

成功响应示例

响应字段说明

错误响应示例

业务错误码说明

调用示例

终端 curl（bash）

PHP

注意事项

快速上手

在线测试

接口反馈

免责声明

免责声明

推荐接口

听友听书