快递物流查询

接口说明

传入快递单号即可查询包裹的实时物流轨迹，返回快递公司信息、当前物流状态、最新节点以及包含时间与描述的完整轨迹记录。接口同时提供物流状态统计汇总，并支持返回自提柜经纬度坐标等附加信息，适用于电商订单物流展示与客服系统查询场景。该接口为收费接口，调用时需携带有效的接口调用密钥（通过 Query 参数 key 传递）。

调用地址

http://api.tmini.net/apis/autonumber

请求方式

GET

鉴权说明

本接口必须携带密钥方可调用。调用时通过 Query 参数传递密钥，参数名为 key，取值为后台分配的调用密钥。

示例：

http://api.tmini.net/apis/autonumber?key=后台KEY&trackingNo=12345678

未携带密钥或密钥无效时，请求将无法通过校验。本接口为计费接口，每次成功调用均计入用量，请妥善保管密钥，避免泄露。

请求参数

请求方式：GET，密钥通过 Query 参数 key 传递（http://api.tmini.net/apis/autonumber?key=后台KEY&trackingNo=12345678）。

参数取值说明：

• key：在后台获取的调用密钥，缺失或无效时请求将被拒绝。
• trackingNo：需查询的快递单号，单次查询一个单号，号码需完整且与实际承运公司一致。

成功响应示例

{
  "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
      }
    ]
  }
}

响应字段说明

错误响应示例

调用未通过校验或计费失败时，返回结构中的 code 不为 0，并在 errcode 中给出具体业务错误码：

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

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

业务错误码说明

调用示例

终端 curl（bash）

curl -G "http://api.tmini.net/apis/autonumber" \
  --data-urlencode "key=后台KEY" \
  --data-urlencode "trackingNo=12345678"

PHP

// PHP 示例（密钥通过 Query 参数 key 传递）
$query = http_build_query([
    'key'        => '后台KEY',
    'trackingNo' => '12345678',
]);

$url = 'http://api.tmini.net/apis/autonumber?' . $query;
$body = file_get_contents($url);

$result = json_decode($body, true);

if ($result['code'] === '0000000000') {
    foreach ($result['data']['packageInfoList'] as $package) {
        echo $package['cpName'] . ' ' . $package['trackingNo'] . PHP_EOL;
        echo '最新节点：' . $package['operateMessage'] . ' ' . $package['operateTime'] . PHP_EOL;

        foreach ($package['trackingDetails'] as $detail) {
            echo $detail['time'] . ' ' . $detail['context'] . PHP_EOL;
        }
    }
}

注意事项

• 调用地址必须原样使用：http://api.tmini.net/apis/autonumber，请求方式为 GET，请勿修改域名、路径或大小写，否则将无法正常路由。
• 密钥通过 Query 参数 key 传递，请在服务端完成拼接与请求，切勿把密钥写入前端页面、小程序包、浏览器可访问的脚本或公开代码仓库，防止被盗刷。密钥泄露后请立即在后台重置。
• 本接口为收费接口，按调用次数计费。请对同一单号的结果做本地缓存（物流轨迹分钟级更新即可），避免短时间内重复轮询同一单号造成不必要的费用；无效单号、格式错误的请求同样会产生计费，请在调用前校验参数。
• trackingNo 为必填，只传纯数字或字母数字组合的完整快递单号，不要包含空格、连字符等分隔符，也不要传订单号、运单条码的明文替代值，否则可能查不到轨迹或被识别为错误单号。
• 返回的 cp/cpName 由系统自动识别，state、signFlag、trackingFlag 等为状态标识字符串，业务侧应按原文透传或自行建立映射，不要臆测其取值含义后做写死判断。
• operateTime、trackingDetails[].time 为 YYYYMMDDHHmmss 格式（如 20260627121900），解析时注意补齐分隔符并统一为本地时区展示。
• cabinetLocation 中的经纬度可能为空字符串，且坐标系以 locationSystem 字段为准（如 GCJ02），在地图上展示前请按该坐标系处理，避免直接与其它坐标系混用导致偏移。
• 轨迹节点为倒序返回（最新节点在前），展示时请按 time 字段排序并保留原始文案（其中含预计到达时间等信息，勿截断）。
• 请对网络异常、超时、返回码非 0000000000 的情况做重试与降级处理，重试请采用指数退避，避免高频连续请求触发平台限流而被临时封禁。
• 单号刚寄出或快递公司尚未回传数据时，trackingDetails 可能为空，属正常现象，建议隔一段时间再查，而不是立即高频重试。