快递查询V1

# 快递物流查询 API 接口文档 ## API 描述 这是一个通过快递单号自动查询物流跟踪信息的API接口。用户仅需提供快递单号（无需密钥）即可调用，系统会自动识别快递公司并返回美化后的中文物流数据。 **支持快递公司：** 中通快递、圆通速递、中国邮政、申通快递、极兔速递、韵达快递、德邦快递 **暂不支持：** 顺丰速运、京东物流、菜鸟裹裹 > 调用频率限制：60 次 / 每分钟 --- ## 请求信息 | 项目 | 说明 | | --- | --- | | **请求地址** | `https://你的域名/v1.php` | | **请求方式** | `GET` | | **返回类型** | `JSON` | | **字符编码** | `UTF-8` | --- ## 请求参数 | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `trackingNo` | `string` | 是 | 快递运单号，例如 `YT1234567890123` | --- ## 响应示例 ### ✅ 查询成功 ```json { "code": 200, "message": "查询成功", "data": { "trackingNo": "YT1234567890123", "totalCount": 1, "packageInfoList": [ { "sendCode": "", "trackingNo": "YT1234567890123", "cp": "YTO", "cpName": "圆通速递", "state": "FINISH", "stateDesc": "已签收", "signFlag": "AUTOMATIC", "signFlagDesc": "自动签收", "operateMessage": "您的快件已签收，签收人：本人签收", "operateTime": "2026-03-25 14:30:00", "isTracking": 0, "getcode": "", "address": "", "onboxTime": "", "cabinetLocation": { "locationSystem": "GCJ02", "latitude": "", "longitude": "" }, "trackingFlag": 2, "cpLinkList": [], "trackingDetails": [ { "time": "2026-03-25 14:30:00", "context": "您的快件已签收，签收人：本人签收", "state": "FINISH" }, { "time": "2026-03-25 08:15:22", "context": "快递员正在为您派件，联系电话：13800138000" }, { "time": "2026-03-24 22:10:05", "context": "您的快件已到达【北京转运中心】" }, { "time": "2026-03-24 18:00:33", "context": "您的快件已离开【上海转运中心】" }, { "time": "2026-03-24 15:45:12", "context": "您的快件已到达【上海转运中心】" }, { "time": "2026-03-24 14:20:08", "context": "您的快件已揽收" } ] } ], "stateStatList": [ { "state": "FINISH", "total": 1 } ] }, "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### ❌ 缺少参数 ```json { "code": 400, "message": "缺少必要参数 trackingNo（快递单号）", "data": null, "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### ❌ 查询错误 - 当前不可查 ```json { "code": 500, "message": "查询错误，当前不可查，等待站长优化", "data": null, "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### ❌ 查询错误 - 未查询到物流信息 ```json { "code": 500, "message": "查询错误，未查询到物流信息，请确认单号是否正确", "data": null, "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### ❌ 查询错误 - 网络或服务异常 ```json { "code": 500, "message": "查询错误，请稍后重试", "data": null, "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` --- ## 响应状态码说明 | 状态码 | 含义 | | --- | --- | | `200` | 查询成功 | | `400` | 缺少必要参数 | | `500` | 查询错误（不可查 / 单号错误 / 未查到 / 服务异常） | --- ## 响应字段说明 ### data 字段 | 字段 | 类型 | 说明 | | --- | --- | --- | | `trackingNo` | `string` | 查询的快递运单号 | | `totalCount` | `int` | 包裹总数 | | `packageInfoList` | `array` | 包裹信息列表 | | `stateStatList` | `array` | 物流状态统计列表 | ### packageInfoList 字段 | 字段 | 类型 | 说明 | | --- | --- | --- | | `trackingNo` | `string` | 运单号 | | `cp` | `string` | 快递公司编码 | | `cpName` | `string` | 快递公司名称 | | `state` | `string` | 物流状态编码 | | `stateDesc` | `string` | 物流状态中文描述 | | `signFlag` | `string` | 签收标志编码 | | `signFlagDesc` | `string` | 签收标志中文描述 | | `operateMessage` | `string` | 最新物流描述 | | `operateTime` | `string` | 最新操作时间（已格式化为 `YYYY-MM-DD HH:mm:ss`） | | `onboxTime` | `string` | 上架时间（已格式化） | | `cabinetLocation` | `object` | 柜机位置信息 | | `trackingDetails` | `array` | 物流轨迹详情列表 | ### trackingDetails 字段 | 字段 | 类型 | 说明 | | --- | --- | --- | | `time` | `string` | 轨迹时间（已格式化为 `YYYY-MM-DD HH:mm:ss`） | | `context` | `string` | 轨迹描述 | | `state` | `string` | 该节点物流状态编码 | ### 物流状态编码映射 | 状态编码 | 中文描述 | | --- | --- | | `FINISH` | 已签收 | | `TRANSPORT` | 运输中 | | `PICKUP` | 已揽收 | | `SIGN` | 已签收 | | `RETURN` | 退回中 | | `REJECT` | 拒收 | | `EXCEPTION` | 异常件 | | `DELIVERING` | 派送中 | ### 签收标志编码映射 | 标志编码 | 中文描述 | | --- | --- | | `AUTOMATIC` | 自动签收 | | `MANUAL` | 人工签收 | | `PROXY` | 代签收 | | `SELF` | 自提签收 | | `DROP` | 投放签收 | --- ## 调用示例 ### 直接请求 ``` GET https://你的域名/v1.php?trackingNo=YT1234567890123 ``` ### cURL ```bash curl "https://你的域名/v1.php?trackingNo=YT1234567890123" ``` ### JavaScript ```javascript fetch('https://你的域名/v1.php?trackingNo=YT1234567890123') .then(res => res.json()) .then(data => console.log(data)); ``` ### PHP ```php $url = 'https://你的域名/v1.php?trackingNo=' . urlencode('YT1234567890123'); $response = file_get_contents($url); $data = json_decode($response, true); print_r($data); ``` --- ## 注意事项 1. 免费调用，频率限制 **60 次 / 每分钟** 2. 用户仅需提供快递单号，**无需密钥** 3. 错误只返回两种：缺少参数（`400`）、查询错误（`500`），查询错误根据情况提示不同描述 4. 所有 JSON 数据中文不转义，时间自动转为可读格式，直接可用 5. 支持跨域请求（CORS），可直接在前端调用

> **由 AI 生成**：本接口文档由 AI 根据配置信息自动生成，仅供参考，实际接口行为以服务端返回为准。 ## 接口简介 快递查询V1是一个无需密钥即可调用的物流跟踪接口，支持中通、圆通、邮政等7家主流快递公司。用户仅需提供快递单号，系统自动识别快递公司并返回中文物流轨迹信息。若后台开启密钥验证，则需在请求中携带`key`参数。 ## 请求说明 - **URL**：`https://api.xunjinlu.fun/api/kuaidi/v1.php` - **方法**：`GET` - **请求头**： ```http Accept: application/json ``` ## 请求参数 | 名称 | 类型 | 必填 | 说明 | |------------|--------|------|--------------------------| | `key` | string | 是 | 接口密钥（密钥开启时必填） | | `trackingNo` | string | 是 | 快递运单号（6-30位字母数字） | ## 返回字段表 | 字段 | 类型 | 说明 | |--------------------------|--------|----------------------------------------------------------------------| | `code` | int | 状态码（200成功） | | `message` | string | 响应消息 | | `data.trackingNo` | string | 查询的快递单号 | | `data.totalCount` | int | 物流轨迹总条数 | | `data.packageInfoList` | array | 快件信息列表（见下方子结构） | | `data.stateStatList` | array | 物流状态统计 | | `api_info` | object | 接口提供方信息（开发者/博客/平台） | **子结构说明**： - `packageInfoList` 对象字段： - `cp`：快递公司代码（如`YTO`） - `cpName`：快递公司名称 - `state`：当前状态（如`AGENT`） - `operateMessage`：最新操作描述 - `trackingDetails`：物流轨迹详情数组（含`time`/`context`） ## 返回 JSON 示例 ### 成功响应 ```json { "code": 200, "message": "查询成功", "data": { "trackingNo": "YT1234567890123", "totalCount": 1, "packageInfoList": [ { "cp": "YTO", "cpName": "圆通速递", "state": "AGENT", "operateMessage": "您的快件已到达...", "trackingDetails": [ {"time": "2026-03-24 06:17:31", "context": "您的快件已到达..."} ] } ], "stateStatList": [{"state": "AGENT", "total": 1}] }, "api_info": {...} } ``` ### 失败响应 ```json { "code": 400, "message": "快递单号格式错误" } ``` ## 错误与状态 - `200`：查询成功 - `400`：请求参数错误（如单号格式无效） - `404`：快递公司不支持 - `500`：服务器内部错误 > 注：具体错误信息以返回的`message`字段为准。 ## 调用示例 ### 直接访问 ``` https://api.xunjinlu.fun/api/kuaidi/v1.php?trackingNo=YT1234567890123 ``` ### cURL ```bash curl "https://api.xunjinlu.fun/api/kuaidi/v1.php?trackingNo=YT1234567890123" ``` ### Python requests ```python import requests url = "https://api.xunjinlu.fun/api/kuaidi/v1.php" params = {"trackingNo": "YT1234567890123"} response = requests.get(url, params=params) print(response.json()) ``` ### PHP ```php $url = "https://api.xunjinlu.fun/api/kuaidi/v1.php"; $params = http_build_query(["trackingNo" => "YT1234567890123"]); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url . "?" . $params); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $result = curl_exec($ch); curl_close($ch); echo $result; ``` ### HTML ```html ```