快递查询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接口通过快递单号自动识别物流公司并返回中文物流信息，适用于电商、物流系统等需要实时跟踪包裹的场景。调用时需提供快递单号，若开启密钥访问则需同时传递`key`参数。当前支持中通、圆通、邮政等主流快递（不含顺丰/京东/菜鸟）。 --- ### 请求说明 - **请求地址**：`https://api.xunjinlu.fun/api/kuaidi/v1.php` - **HTTP 方法**：`GET` - **常用请求头**： - `Accept: application/json`（建议显式声明） - 若需密钥：`key` 参数需通过 Query 传递 --- ### 请求参数表 | 参数名 | 类型 | 必填 | 说明 | |-------------|--------|------|--------------------------| | `key` | string | 是 | 接口访问密钥（开启密钥时必填） | | `trackingNo` | string | 是 | 快递运单号（6-30位字母数字，如`YT1234567890123`） | --- ### 返回字段表 | 字段路径 | 类型 | 说明 | |-------------------------|--------|--------------------------| | `code` | int | 状态码（200表示成功） | | `message` | string | 响应描述 | | `data.trackingNo` | string | 运单号 | | `data.totalCount` | int | 包裹数量 | | `data.packageInfoList` | array | 包裹信息列表（对象数组） | | `data.stateStatList` | array | 状态统计列表（对象数组） | | `api_info` | object | API 提供方信息 | #### `packageInfoList` 对象字段 | 字段名 | 类型 | 说明 | |--------------------|--------|--------------------------| | `cp` | string | 快递公司代码（如`YTO`） | | `cpName` | string | 快递公司名称（如`圆通速递`） | | `state` | string | 包裹状态（如`AGENT`） | | `signFlag` | string | 签收标识（如`AUTOMATIC`） | | `operateMessage` | string | 最新物流描述 | | `operateTime` | string | 最新物流时间 | | `trackingDetails` | array | 详细物流轨迹（对象数组） | #### `trackingDetails` 对象字段 | 字段名 | 类型 | 说明 | |-----------|--------|------------------| | `time` | string | 物流时间 | | `context` | string | 物流描述 | | `state` | string | 状态标识 | --- ### 返回 JSON 示例 #### 成功响应 ```json { "code": 200, "message": "查询成功", "data": { "trackingNo": "YT1234567890123", "totalCount": 1, "packageInfoList": [ { "cpName": "圆通速递", "state": "AGENT", "operateMessage": "您的快件已到达[兔喜生活]...", "operateTime": "2026-03-24 06:17:31", "trackingDetails": [ { "time": "2026-03-24 06:17:31", "context": "您的快件已到达[兔喜生活]...", "state": "AGENT" } ] } ] } } ``` #### 失败响应 ```json { "code": 400, "message": "快递单号格式错误", "data": null } ``` --- ### 错误与状态 - **常见 HTTP 状态码**： - `200`：查询成功 - `400`：参数错误（如单号格式错误） - `401`：密钥无效（开启密钥时） - `404`：快递公司不支持 - **业务错误码**：以返回的 `message` 字段描述为准（如 `"快递单号不存在"`） --- ### 调用示例 #### 直接访问 ```url https://api.xunjinlu.fun/api/kuaidi/v1.php?trackingNo=YT1234567890123 ``` > 在浏览器中打开此 URL 可直接查看 JSON 响应 #### cURL ```bash curl -G "https://api.xunjinlu.fun/api/kuaidi/v1.php" \ -d "trackingNo=YT1234567890123" \ -H "Accept: application/json" ``` #### Python requests ```python import requests url = "https://api.xunjinlu.fun/api/kuaidi/v1.php" params = {"trackingNo": "YT1234567890123"} headers = {"Accept": "application/json"} response = requests.get(url, params=params, headers=headers) data = response.json() print(data["message"]) # 输出：查询成功 ``` #### PHP ```php 'YT1234567890123' ]; $url = "https://api.xunjinlu.fun/api/kuaidi/v1.php?" . http_build_query($params); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']); $response = curl_exec($ch); $data = json_decode($response, true); echo $data['message']; // 输出：查询成功 curl_close($ch); ?> ``` #### HTML ```html ```