快递查询接口对接指南：从零到第一个请求

2026-07-20 · 阅读约 6 分钟

给自己的系统加一个「查快递」能力，最快的路径是接一个现成的快递查询接口，而不是逐家研究快递公司的页面结构。本文用本站接口演示完整对接流程：获取密钥 → 发送请求 → 解析统一返回。全程只需要能发 HTTP 请求的任意语言。

一、准备：获取密钥

注册账号（邮箱即可，无需企业认证），进入控制台点击「生成密钥」，会得到一对密钥：

API Key（pk_ 开头）：标识你的账号
Secret Key（sk_ 开头）：只展示一次，务必立即保存

还没想好要不要注册？首页的在线演示用公开测试密钥就能先跑一遍。

二、发送第一个请求

查询接口是 POST /v1/tracking/trace，认证方式为 Authorization: Bearer API_KEY:SECRET_KEY（两段用英文冒号连接）：

curl -X POST https://api.kuaidichaxunapi.com/v1/tracking/trace \
  -H "Authorization: Bearer pk_xxx:sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"courierCode":"cainiao","trackingNumber":"CGD0000123456"}]}'

JavaScript（Node 18+ 或浏览器）版本：

// 查询单个运单号
const res = await fetch('https://api.kuaidichaxunapi.com/v1/tracking/trace', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.KUAIDI_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [{ courierCode: 'cainiao', trackingNumber: 'CGD0000123456' }],
  }),
});
const json = await res.json();
const jieguo = json.data.results[0];

三、解析返回

关注三个字段就够了：

字段	说明
`data.deliveryStatus`	归一后的状态码，共 12 个，如 `IN_TRANSIT`（运输中）、`DELIVERED`（已签收）
`data.deliveryStatusText`	状态码对应的中文名称，可直接展示
`data.isDelivered`	是否已签收，做「待收货/已完成」分类时直接用它
`data.progresses`	轨迹数组，最新在前，每条含 `dateTime`、`status`、`statusCode`、`location`

统一状态码是这个接口最省事的地方：不同快递公司的原始描述五花八门（「已妥投」「派件已签收」「本人签收」……），代码里只需要判断 statusCode === 'DELIVERED' 一种情况。完整状态码表见文档。

四、处理失败条目

批量查询时某条失败不会让整个请求报错，逐条检查 success 即可：

for (const r of json.data.results) {
  if (r.success) {
    console.log(r.data.trackingNumber, r.data.deliveryStatus);
  } else {
    // COURIER_PREPARING / NOT_FOUND / INVALID_TRACKING_NUMBER…
    console.warn(r.error.code, r.error.message);
  }
}

常见的两个错误码：NOT_FOUND 是查询成功但暂无轨迹（新单常见，稍后重查即可）； COURIER_PREPARING 是该公司查询功能还在开发中，这类请求不消耗额度。

五、几个实践建议

密钥放服务端：不要把 Secret Key 打包进前端代码，浏览器里谁都能看到。
缓存结果：物流状态几十分钟才变一次，同一单号做 10–30 分钟缓存能省大量额度。
已签收就停：isDelivered 为 true 后不必再查，这单已经终态。

更完整的字段与限制说明见接口文档。跨境包裹（AliExpress 等）的查询有些特别之处，见下一篇：用 API 查询 AliExpress 跨境包裹的物流轨迹。