圆通快递查询V1

# 快递物流查询 API 接口文档 (V1) ## 接口概述 圆通快递物流查询V1接口是一个实时查询快递物流信息的API，通过传入快递单号，一次性返回该快递的完整物流轨迹、当前状态、揽收时间、运输路径等详细信息。 ## 接口地址 ``` GET/POST https://api.xunjinlu.fun/api/kuaidi/yt/v1.php ``` ## 请求方式 - `GET` - 通过 URL Query 参数传递 - `POST` - 通过表单或 JSON Body 传递 ## 请求参数 ### 参数列表 | 参数名 | 类型 | 必填 | 描述 | |--------|------|------|------| | number | string | 是 | 要查询的快递单号 | ### 参数说明 - **number**：快递单号，支持以 "YT" 开头的圆通单号，长度12位以上 ### 传参方式 #### 方式一：GET 请求 ``` GET https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?number=YT123456789012 ``` #### 方式二：POST 表单提交 ``` POST https://api.xunjinlu.fun/api/kuaidi/yt/v1.php Content-Type: application/x-www-form-urlencoded number=YT123456789012 ``` #### 方式三：POST JSON Body ``` POST https://api.xunjinlu.fun/api/kuaidi/yt/v1.php Content-Type: application/json { "number": "YT123456789012" } ``` ## 响应参数 ### 成功响应 ```json { "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 } } ``` ### 错误响应 #### 缺少必要参数 ```json { "code": 400, "msg": "缺少参数：请提供快递单号（number）", "data": null } ``` #### 单号格式错误 ```json { "code": 400, "msg": "单号格式错误：圆通单号应以YT开头，后面为数字", "data": null } ``` #### 未查询到物流信息 ```json { "code": 404, "msg": "未查询到物流信息，请检查单号是否正确", "data": { "waybillNo": "YT000000000000", "raw_response": null } } ``` #### 接口请求失败 ```json { "code": 500, "msg": "解析响应失败", "data": { "raw_response": "..." } } ``` #### 网络请求错误 ```json { "code": 500, "msg": "请求失败：Connection timeout", "data": null } ``` ## 响应字段说明 ### 根字段 | 字段 | 类型 | 说明 | |------|------|------| | code | int | 状态码，200为成功，其他为失败 | | msg | string | 状态描述信息 | | data | object/null | 返回的物流数据，失败时为 null | ### data 字段（成功响应） | 字段 | 类型 | 说明 | |------|------|------| | waybillNo | string | 快递单号 | | waybillProcessInfo | array | 物流轨迹信息数组（按时间倒序） | | personalOrder | bool | 是否为个人订单 | | signPic | bool | 是否有签收图片 | ### waybillProcessInfo 数组元素 | 字段 | 类型 | 说明 | |------|------|------| | opTime | string | 操作时间（格式：YYYY-MM-DD HH:mm:ss） | | opOrgName | string | 操作地点/网点名称 | | opName | string | 操作名称（如：揽收、派件、入库等） | | description | string | 详细描述信息 | | weight | string | 包裹重量（单位：kg） | ## 错误码说明 | 错误码 | 描述 | |--------|------| | 200 | 查询成功 | | 400 | 参数错误（缺少参数或单号格式不正确） | | 404 | 未查询到物流信息（单号不存在或暂无物流记录） | | 500 | 服务器内部错误（请求失败或解析失败） | ## 技术特性 - **多方式传参**：支持 GET、POST 表单、POST JSON Body 三种传参方式 - **实时查询**：实时获取最新物流信息 - **完整轨迹**：返回从揽收到签收的完整物流轨迹 - **CORS 支持**：已配置跨域访问，支持前端直接调用 - **HTTPS 安全**：全程使用 HTTPS 加密传输 ## 物流状态说明 | 状态名称 | 说明 | |----------|------| | 业务员收件 | 快递员已揽收快件 | | 装件入车扫描 | 快件已装入运输车辆 | | 下车扫描 | 快件已到达转运中心或派件网点 | | 派件扫描 | 快递员正在为您派件 | | 入柜\|入库 | 快件已放入快递柜或代收点 | | 签收 | 快件已签收 | | 问题件 | 存在异常情况，请查看详情 | ## 注意事项 1. **返回格式**：接口返回 UTF-8 编码的美化 JSON 数据 2. **请求超时**：建议客户端设置较长的超时时间（建议 30 秒以上） 3. **单号格式**：目前仅支持以 "YT" 开头的快递单号 4. **调用频率**：请合理控制请求频率，避免对服务器造成过大压力 5. **数据时效**：物流信息可能有几分钟延迟，请以实际情况为准 ## 调用示例 ### cURL 调用 ```bash # GET 请求 curl "https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?number=YT123456789012" # POST 表单 curl -X POST "https://api.xunjinlu.fun/api/kuaidi/yt/v1.php" \ -d "number=YT123456789012" # POST JSON curl -X POST "https://api.xunjinlu.fun/api/kuaidi/yt/v1.php" \ -H "Content-Type: application/json" \ -d '{"number":"YT123456789012"}' ``` ### JavaScript 调用 ```javascript // GET 请求 fetch('https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?number=YT123456789012') .then(res => res.json()) .then(data => console.log(data)); // POST JSON 请求 fetch('https://api.xunjinlu.fun/api/kuaidi/yt/v1.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ number: 'YT123456789012' }) }) .then(res => res.json()) .then(data => console.log(data)); ``` ### PHP 调用 ```php 'YT123456789012' ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($data)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result); ?> ``` ## 开发者信息 - **开发者**：尋鯨錄 - **博客**：[https://www.xunjinlu.fun](https://www.xunjinlu.fun) - **API 平台**：[https://api.xunjinlu.fun](https://api.xunjinlu.fun)

> 声明：本文档由 AI 根据平台配置自动生成；示例为片段。 ## 接口简介 圆通快递查询V1接口是一个实时查询快递物流信息的API，通过传入快递单号，一次性返回该快递的完整物流轨迹、当前状态、揽收时间、运输路径等详细信息。该接口支持GET和POST两种请求方式，返回JSON格式的数据。用户需提供接口访问密钥和快递单号即可查询物流信息。接口适用于电商网站、物流管理系统等多种应用场景。 ## 请求说明 - **方法**：GET, POST - **请求头**：Content-Type: application/json - **请求地址**：https://api.xunjinlu.fun/api/kuaidi/yt/v1.php ## 请求参数表 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | key | string | 是 | 接口访问密钥（开启密钥访问时必填） | | number | string | 是 | 需要查询的圆通快递单号 | ## 返回字段表 | 字段名 | 类型 | 说明 | |-------|------|------| | code | number | 状态码，200表示成功 | | msg | string | 返回信息 | | data.waybillNo | string | 快递单号 | | data.waybillProcessInfo | array | 物流轨迹信息数组 | | data.personalOrder | boolean | 是否为个人订单 | | data.signPic | boolean | 是否有签收图片 | ## 返回示例 ### 成功示例 ```json { "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" } ], "personalOrder": false, "signPic": false } } ``` ### 失败示例 ```json { "code": 400, "msg": "查询失败，请检查单号是否正确" } ``` ## 错误码 | 错误码 | 说明 | |-------|------| | 200 | 查询成功 | | 400 | 请求参数错误 | | 401 | 密钥验证失败 | | 404 | 快递单号不存在 | | 500 | 服务器内部错误 | ## 调用示例 ### 浏览器直接访问 ``` https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?key=您的密钥&number=YT123456789012 ``` ### cURL ```bash curl "https://api.xunjinlu.fun/api/kuaidi/yt/v1.php?key=您的密钥&number=YT123456789012" ``` ### Python ```python import requests url = "https://api.xunjinlu.fun/api/kuaidi/yt/v1.php" params = { "key": "您的密钥", "number": "YT123456789012" } response = requests.get(url, params=params) print(response.json()) ``` ### PHP ```php "您的密钥", "number" => "YT123456789012" ]; $context = stream_context_create([ "http" => [ "method" => "GET", "header" => "Content-Type: application/json\r\n", "content" => http_build_query($params) ] ]); $response = file_get_contents($url, false, $context); echo $response; ?> ``` ### HTML ```html

查询

```