参数名	类型	必填	说明
key	string	是	接口调用密钥
num	string	是	单号
code	string	否	发件人\|收件人尾号

通用快递

接口说明

该接口提供通用快递物流信息查询服务，支持通过快递单号实时获取包裹的完整物流轨迹详情。主要适用于需要集成快递查询功能的开发者及企业应用，调用需携带密钥，接口支持 GET 和 POST 请求方式。

调用地址

https://api.vsaa.cn/api/express/niao/index.php

请求方式

支持 GET 与 POST 两种请求方式。

鉴权说明

调用接口时必须在请求中携带有效的调用密钥。密钥通过查询参数（Query Parameter）传递，参数名为 key。例如在 URL 末尾追加 ?key=您的密钥。该接口实行收费策略，频率限制约为每分钟 61 次。

请求参数

参数名	类型	必填	说明
key	string	是	接口调用密钥，需通过 Query 参数传递（`?key=…`）。
num	string	是	快递单号。
code	string	否	发件人或收件人电话尾号。在部分快递公司的物流详情查询中，若仅凭单号无法定位，提供此参数可辅助匹配。

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "routeMapUrlCode": null,
    "routeMapUrl": null,
    "shipperCode": "EMS",
    "shipperName": "EMS",
    "traces": [
      {
        "acceptTime": "2026-01-13 17:00:29",
        "acceptStation": "中国邮政已收取快件",
        "location": "中山市",
        "action": "1"
      },
      {
        "acceptTime": "2026-01-13 17:00:35",
        "acceptStation": "快件已在【中山市电商客户小榄大宗揽收部】完成分拣，准备发出",
        "location": "中山市",
        "action": "2"
      }
    ],
    "specialShipper": 0
  },
  "success": true,
  "error": false
}

响应字段说明

字段名	类型	说明
`code`	integer	状态码。`200` 表示请求处理成功。
`msg`	string	状态描述。成功时固定为“操作成功”。
`success`	boolean	是否成功标志。成功时为 `true`。
`error`	boolean	是否错误标志。成功时为 `false`。
`data`	object	业务数据对象，包含物流详情信息。
`data.shipperCode`	string	快递公司代码，如 `EMS`、`SF` 等。
`data.shipperName`	string	快递公司名称。
`data.specialShipper`	integer	特殊快递商标识。`0` 表示普通快递，非 `0` 表示需配合 `code` 参数使用或属于特殊服务商。
`data.routeMapUrlCode`	string/null	路由地图编码。目前多为 `null`，预留字段。
`data.routeMapUrl`	string/null	路由地图链接。目前多为 `null`，预留字段。
`data.traces`	array	物流轨迹列表，按时间顺序或状态顺序排列。

data.traces 数组元素字段：

字段名	类型	说明
`acceptTime`	string	轨迹发生时间，格式：`YYYY-MM-DD HH:mm:ss`。
`acceptStation`	string	轨迹详细内容，包含当前状态、所在网点、备注等信息。
`location`	string	轨迹发生的地点（城市级）。
`action`	string	动作类型代码。用于辅助判断物流阶段，例如：`1` 揽收、`2` 运输/到达/离开、`202` 派送中、`412` 代收/驿站待取、`302` 已签收/取走。具体含义可能因快递公司而异，建议主要依据 `acceptStation` 文本内容判断业务状态。

错误响应示例

调用接口时，若发生鉴权失败、参数错误、服务异常或业务逻辑拦截，系统将返回统一的 JSON 结构。错误响应中 code 通常为 0，errcode 字段包含具体的业务错误码，msg 字段提供人类可读的错误描述。

示例：密钥错误

{
    "code": 0,
    "msg": "密钥错误",
    "errcode": 11002
}

示例：请求过于频繁（QPM 限制）

{
    "code": 0,
    "msg": "请求过于频繁（QPM 限制）",
    "errcode": 11005
}

示例：未提供调用密钥

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

业务错误码说明

下表列出了通用快递接口可能返回的所有业务错误码及其含义。

错误码 (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 -G "https://api.vsaa.cn/api/express/niao/index.php" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "num=9876543210" \
  --data-urlencode "code=1234"

PHP

// PHP 示例
$ch = curl_init();
$url = "https://api.vsaa.cn/api/express/niao/index.php";
$params = [
"key" => "YOUR_API_KEY",
"num" => "98****10",
"code" => "1234"
];
$query = http_build_query($params);
$fullUrl = $url . "?" . $query;

curl_setopt($ch, CURLOPT_URL, $fullUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/x-www-form-urlencoded"));

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP Status: " . $status . "\n";
echo "Response: " . $response . "\n";

注意事项

密钥安全：密钥（key）通过 Query 参数传递，必须妥善保管。严禁将密钥硬编码在前端代码、客户端 App 或公开仓库中，以防止泄露导致额度被盗用或产生额外费用。
频率限制：接口存在调用频率限制（约 61 次/分钟）。高频批量查询场景下，请务必在客户端实现请求节流或队列机制，避免触发限流导致请求被拒绝。
参数校验：
- num（单号）为必填项，需确保格式正确且对应真实存在的物流单据，否则将返回错误信息。
- code 为选填项，仅在单号相同且需区分具体收发关系时提供尾号，无需此信息时请留空或省略该参数，切勿填写无效字符。
响应处理：建议始终校验返回 JSON 中的 success 字段及 code 值。仅当 success 为 true 且 code 为 200 时，方可解析 data 中的物流轨迹数据；异常情况下请依据 msg 字段进行错误处理。
数据安全：返回结果中包含收件人、快递员电话等敏感信息，务必通过 HTTPS 协议传输（当前调用地址已为 HTTPS），并在存储或展示时对非业务必要信息进行脱敏处理，符合数据安全合规要求。

免责声明

欢迎使用 万象数据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

注意事项

快速上手

在线测试

接口反馈

免责声明

免责声明

推荐接口

语言合成_v2