快递查询-v6

接口说明

传入快递单号即可查询包裹的实时物流轨迹，返回快递公司、当前物流状态、最新节点及完整物流轨迹明细。同时提供物流状态统计汇总，并支持返回自提柜经纬度坐标等附加信息，适用于电商订单物流展示及客服系统查询。

调用地址

https://api.xunjinlu.fun/apis/tmautonumber

请求方式

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

鉴权说明

本接口必须携带密钥调用，密钥通过 Query 参数传递，参数名为 key，例如 ?key=您的密钥。未携带或密钥无效时无法获取物流数据。

请求参数

调用地址：https://api.xunjinlu.fun/apis/tmautonumber，请求方式支持 GET 与 POST。

鉴权方式：密钥通过 Query 参数传递，即 key=…。

参数取值说明：

• trackingNo 为待查询的快递运单号，需与快递公司实际单号一致，否则无法返回对应轨迹。
• 频率限制：每分钟约 50 次，超出后请求可能被限制，请合理控制调用节奏。
• 本接口为收费接口，调用将按计费规则扣减额度。

成功响应示例

{
  "code": "0000000000",
  "desc": "OK",
  "data": {
    "serviceCode": 0,
    "packageInfoList": [
      {
        "sendCode": "",
        "trackingNo": "12345678",
        "cp": "DBKD",
        "cpName": "德邦快递",
        "state": "TRANSPORT",
        "signFlag": "AUTOMATIC",
        "operateMessage": "到达济南转运场",
        "operateTime": "20260627121900",
        "trackingDetails": [
          {
            "time": "20260627121900",
            "context": "到达济南转运场",
            "state": "TRANSPORT"
          },
          {
            "time": "20260627105619",
            "context": "离开聊城茌平区永兴路经营分部，下一部门济南转运场，预计到达下一部门时间2026年06月27日20:26:19"
          }
        ],
        "isTracking": 0,
        "getcode": "",
        "address": "",
        "onboxTime": "",
        "cabinetLocation": {
          "locationSystem": "GCJ02",
          "latitude": "",
          "longitude": ""
        },
        "trackingFlag": 2,
        "cpLinkList": []
      }
    ],
    "productRecommend": [],
    "stateStatList": [
      {
        "state": "TRANSPORT",
        "total": 1
      }
    ]
  }
}

响应字段说明

错误响应示例

当请求未通过校验或业务处理失败时，接口返回统一结构的 JSON 报文，code 为 0，msg 为错误描述，errcode 为具体业务错误码。

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

{
  "code": 0,
  "msg": "积分余额不足",
  "errcode": 11004
}

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

业务错误码说明

说明：本接口为收费接口，调用时须在 Query 中携带有效密钥（key=…）。当密钥缺失、错误、被禁用或过期时，将分别返回 11001、11002、11003、11023；当积分不足或令牌分配积分不足时，返回 11004、11024。请求频率超过每分钟约 50 次时返回 11005。接口处于维护、禁用或不可用状态时，返回 11006、11007、11008。鉴权方式不符合要求时返回 11012，请求方式不被允许时返回 11018。涉及地址与请求的异常，返回 11013 至 11016；服务整体不可用时返回 11017。IP 白名单校验不通过返回 11019；出口代理相关异常返回 11020 至 11022。

调用示例

终端 curl（bash）

curl -G "https://api.xunjinlu.fun/apis/tmautonumber" \
  --data-urlencode "key=你的密钥" \
  --data-urlencode "trackingNo=12345678"

PHP

// PHP 示例
$params = [
    'key'        => '你的密钥',
    'trackingNo' => '12345678',
];

$url = 'https://api.xunjinlu.fun/apis/tmautonumber?' . http_build_query($params);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

注意事项

• 密钥仅走 Query 传递：调用时把密钥作为 URL 查询参数 key 传入，例如 https://api.xunjinlu.fun/apis/tmautonumber?key=你的密钥&trackingNo=12345678。请勿把密钥写进前端页面、小程序包、公开仓库或客户端日志，一旦泄露他人可直接消耗你的调用额度。
• 务必使用 HTTPS：调用地址固定为 https://api.xunjinlu.fun/apis/tmautonumber，请勿改成 HTTP 或其它域名，否则密钥可能在传输链路中被截获。
• 本接口为收费接口：每次成功调用都会产生计费，调试阶段建议先用少量真实单号验证，避免用循环脚本批量空跑造成无谓消耗。
• 频率限制约每分钟 50 次：请自行做请求节流与失败重试退避，批量查询时建议串行或小并发，超频可能被限流甚至临时拒绝服务。
• trackingNo 必须为有效单号：单号错误、格式不符或与快递公司不匹配时，可能返回空轨迹或异常状态，请勿传入空字符串、带空格或带前后缀的脏数据。
• key 与 trackingNo 均为必填：缺少任一参数都会导致调用失败，建议在业务侧先做非空校验再发起请求。
• 物流状态字段取值需按业务语义处理：state、trackingFlag、signFlag 等字段用于区分运输中、已签收等不同阶段，请以实际返回值为准做展示映射，不要硬编码假设固定枚举。
• 时间字段为纯数字格式：如 operateTime、trackingDetails[].time 形如 20260627121900，展示前需自行格式化为可读时间。
• 轨迹与坐标可能为空：trackingDetails、cabinetLocation 的经纬度等字段在部分单号或部分阶段下可能为空字符串，前端渲染时需做空值兜底，避免报错。
• 返回结果可能包含多条包裹信息：packageInfoList 为数组，请按 trackingNo 匹配后再展示，不要默认只取第一条。
• 建议对查询结果做短时缓存：同一单号短时间内重复查询既消耗额度又无必要，可在业务侧按单号缓存数分钟至数十分钟。