圆通快递查询V1接口文档

接口说明

圆通快递物流查询V1接口是一个实时查询快递物流信息的API，通过传入快递单号，一次性返回该快递的完整物流轨迹、当前状态、揽收时间、运输路径等详细信息。本接口支持GET和POST两种请求方式，采用密钥鉴权机制，免费调用。

调用地址

https://api.xunjinlu.fun/api/kuaidi/yt/v1.php

请求方式

• GET
• POST

鉴权方式

本接口支持以下三种鉴权方式，调用方需至少选择一种进行身份验证：

1. Query参数鉴权：在URL查询参数中传递key参数
2. Header鉴权：在HTTP请求头中设置X-API-Key字段
3. Bearer Token鉴权：在HTTP请求头中设置Authorization: Bearer

请求参数

参数列表

参数说明

• key：您的个人访问密钥，用于身份验证和调用计数。请妥善保管，避免泄露。
• number：需要查询物流信息的圆通快递单号，请确保单号准确无误。

请求示例

GET请求示例

GET https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?key=sk_xxxxxxxxxxxxxxxx&number=YT1234567890123 HTTP/1.1
Host: api.xunjinlu.fun

POST请求示例（application/x-www-form-urlencoded）

POST https://api.xunjinlu.fun/api/kuaidi/yt/v1.php HTTP/1.1
Host: api.xunjinlu.fun
Content-Type: application/x-www-form-urlencoded

key=sk_xxxxxxxxxxxxxxxx&number=YT1234567890123

POST请求示例（application/json）

POST https://api.xunjinlu.fun/api/kuaidi/yt/v1.php HTTP/1.1
Host: api.xunjinlu.fun
Content-Type: application/json

{
  "key": "sk_xxxxxxxxxxxxxxxx",
  "number": "YT1234567890123"
}

Header鉴权示例

GET https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?number=YT1234567890123 HTTP/1.1
Host: api.xunjinlu.fun
X-API-Key: sk_xxxxxxxxxxxxxxxx

Bearer Token鉴权示例

GET https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?number=YT1234567890123 HTTP/1.1
Host: api.xunjinlu.fun
Authorization: Bearer sk_xxxxxxxxxxxxxxxx

成功响应示例

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "waybillNo": "YT123456789012",
    "waybillProcessInfo": [
      {
        "opTime": "2026-05-20 14:30:00",
        "opOrgName": "广东省深圳市南山区",
        "opName": "签收",
        "description": "您的快件已签收，签收人：本人",
        "weight": "1.5"
      },
      {
        "opTime": "2026-05-20 09:00:00",
        "opOrgName": "广东省深圳市南山区",
        "opName": "派件扫描",
        "description": "【广东省深圳市南山区】的张三（138****8888）正在为您派件",
        "weight": "1.5"
      },
      {
        "opTime": "2026-05-19 22:00:00",
        "opOrgName": "深圳转运中心",
        "opName": "下车扫描",
        "description": "您的快件已经到达【深圳转运中心】",
        "weight": "1.5"
      },
      {
        "opTime": "2026-05-19 18:00:00",
        "opOrgName": "广州转运中心",
        "opName": "装件入车扫描",
        "description": "您的快件离开【广州转运中心】，已发往【深圳转运中心】",
        "weight": "1.5"
      },
      {
        "opTime": "2026-05-18 10:00:00",
        "opOrgName": "浙江省杭州市西湖区",
        "opName": "业务员收件",
        "description": "您的快件在【浙江省杭州市西湖区】已揽收，揽收人：李四（139****9999）",
        "weight": "1.5"
      }
    ],
    "personalOrder": false,
    "signPic": false
  }
}

响应字段说明

顶层响应字段

data对象字段

waybillProcessInfo数组元素字段

错误响应示例

当请求失败时，API将返回相应的错误信息：

未提供密钥

{
  "code": 0,
  "msg": "未提供访问密钥",
  "errcode": 11001
}

密钥错误

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

密钥已禁用

{
  "code": 0,
  "msg": "访问密钥已被禁用",
  "errcode": 11003
}

积分不足

{
  "code": 0,
  "msg": "账户积分不足",
  "errcode": 11004
}

请求过于频繁

{
  "code": 0,
  "msg": "请求过于频繁，请稍后再试",
  "errcode": 11005
}

维护中

{
  "code": 0,
  "msg": "系统维护中，请稍后再试",
  "errcode": 11006
}

接口已禁用

{
  "code": 0,
  "msg": "该接口已被禁用",
  "errcode": 11007
}

鉴权方式错误

{
  "code": 0,
  "msg": "鉴权方式错误",
  "errcode": 11012
}

业务错误码说明

频率限制

本接口设有频率限制，每分钟约允许60次请求。请合理控制调用频率，避免触发限流机制。

调用示例（PHP）

// 圆通快递查询V1接口调用示例
$url = 'https://api.xunjinlu.fun/api/kuaidi/yt/v1.php';
$params = [
    'key' => 'sk_xxxxxxxxxxxxxxxx', // 替换为您的实际密钥
    'number' => 'YT1234567890123' // 替换为需要查询的快递单号
];

// 初始化cURL会话
$ch = curl_init();

// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);

// 执行请求
$response = curl_exec($ch);

// 检查是否有错误
if (curl_errno($ch)) {
    echo '请求错误: ' . curl_error($ch);
} else {
    // 处理响应数据
    $result = json_decode($response, true);
    if ($result['code'] == 200) {
        // 查询成功，处理物流数据
        echo "运单号: " . $result['data']['waybillNo'] . "\n";
        echo "物流轨迹:\n";
        foreach ($result['data']['waybillProcessInfo'] as $item) {
            echo $item['opTime'] . " - " . $item['opName'] . ": " . $item['description'] . "\n";
        }
    } else {
        // 查询失败，显示错误信息
        echo "查询失败: " . $result['msg'] . " (错误码: " . $result['errcode'] . ")\n";
    }
}

// 关闭cURL会话
curl_close($ch);

注意事项

1. 请确保传入的快递单号准确无误，错误的单号将导致查询失败
2. 接口返回的物流轨迹按时间倒序排列，最新状态在最前面
3. 请妥善保管您的访问密钥，避免泄露造成不必要的损失
4. 本接口为免费调用，但设有频率限制，请合理使用
5. 如遇技术问题，请保存完整的请求和响应信息以便排查