接口文档

所有接口通过 HTTPS 提供，基础地址为 https://api.kuaidichaxunapi.com。 请求与响应均为 UTF-8 编码的 JSON。

一分钟跑通

注册后在控制台生成密钥，替换下方命令中的占位符即可：

# 查询菜鸟国际运单
curl -X POST https://api.kuaidichaxunapi.com/v1/tracking/trace \
  -H "Authorization: Bearer API_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"courierCode":"cainiao","trackingNumber":"CGD0000123456"}]}'

还没有密钥？首页的在线演示使用公开测试密钥，可先直接体验（按 IP 限频）。

认证方式

所有请求都需要在 Authorization 请求头中携带密钥对， 格式为 Bearer API_KEY:SECRET_KEY（两段之间用英文冒号连接）：

Authorization: Bearer pk_xxxxxxxx:sk_xxxxxxxx

密钥在控制台生成。Secret Key 只在生成时展示一次，请妥善保存； 泄露后可在控制台吊销并重新生成。

查询物流轨迹

POST /v1/tracking/trace

请求体

附加必填项（extra）

少数快递公司除运单号外还要求附加信息（例如顺丰要求收件人手机号后四位）。 这类字段按位置传入 extra 数组：extra[0] 对应该公司声明的第 1 个字段， extra[1] 对应第 2 个，以此类推。各公司需要哪些字段可通过 GET /v1/tracking/couriers 的 requiredFields（含 key、标签与格式提示）获取。

# 顺丰：extra[0] = 收件人手机号后四位
{ "items": [{ "courierCode": "sf", "trackingNumber": "SF1234567890123", "extra": ["1234"] }] }

缺少或格式不符时分别返回 MISSING_REQUIRED_FIELD / INVALID_REQUIRED_FIELD， 响应中的 fieldIndex/fieldKey 标明具体字段，均不计费。 每家公司的字段顺序永久固定：新增只会追加到末尾，不会插入或改变现有位置，可放心按位置对接。

响应示例

{
  "isSuccess": true,
  "data": {
    "results": [
      {
        "success": true,
        "data": {
          "courierCode": "cainiao",
          "courierName": "菜鸟国际",
          "trackingNumber": "CGD0000123456",
          "deliveryStatus": "DELIVERED",
          "deliveryStatusText": "已签收",
          "isDelivered": true,
          "progresses": [
            {
              "dateTime": "2026-06-11 17:47:55",
              "status": "用户已签收",
              "statusCode": "DELIVERED",
              "location": "已妥投"
            }
          ]
        }
      }
    ],
    "summary": { "total": 1, "successful": 1, "failed": 0 }
  }
}

单条失败时

批量查询中某条失败不会影响整体请求：对应条目的 success 为 false， 并在 error 中给出错误码：

{
  "success": false,
  "error": {
    "code": "COURIER_PREPARING",
    "message": "该快递公司的查询功能正在准备中，即将支持。",
    "billable": false
  }
}

获取快递公司列表

GET /v1/tracking/couriers

返回当前支持的快递公司编码、名称与状态（active 可查询 / preparing 开发中）。

curl https://api.kuaidichaxunapi.com/v1/tracking/couriers \
  -H "Authorization: Bearer API_KEY:SECRET_KEY"

快递公司编码表

「开发中」的公司：请求会返回 COURIER_PREPARING，不消耗额度； 该运单号会作为样本用于优先排期上线。

统一状态码

各家快递公司的原始状态统一归一为以下 12 个状态码：

错误码

调用限制

超出限制会返回 429。需要更高额度请联系我们。