When the user wants to create,…

# 物流轨迹查询接口 API 文档

一、接口基本信息

• 接口名称：物流轨迹查询
• 请求方式：GET
• 请求路径：/api/v1/tracking/{orderNo}
• 接口描述：根据订单号与承运商编码查询物流轨迹信息
• Content-Type：application/json

二、请求参数

| 参数名 | 位置 | 类型 | 必填 | 说明 |

|---|---|---|---|---|

| orderNo | path | string | 是 | 订单号，需URL编码 |

| carrierCode | query | string | 是 | 承运商编码，如 SF、YTO 等自定义编码 |

请求示例：

```

GET /api/v1/tracking/SF1234567890?carrierCode=SF

```

三、响应结构（示例）

```json

{

"code": 0,

"message": "success",

"data": {

"orderNo": "SF1234567890",

"carrierCode": "SF",

"status": "IN_TRANSIT",

"traces": [

{

"time": "2024-01-01 10:00:00",

"location": "深圳市",

"description": "包裹已揽收"

}

]

}

}

```

• code=0 表示成功；常见错误：40001（订单号不存在）、40002（承运商编码无效）——错误码请按贵司实际定义调整
• status 建议枚举：NOT_PICKED_UP / IN_TRANSIT / DELIVERED / EXCEPTION

四、在线调试方案（任选其一）

1. OpenAPI + Swagger UI（推荐）

• 编写 OpenAPI 3.0 规范文件（YAML/JSON）
• 接入 Swagger UI 或 Knife4j（Java 项目），页面自带参数填写与"Try it out"调试

2. Apifox / Postman

• 导入 OpenAPI 文件生成文档页，开启“在线运行”分享链接给外部调用方

3. 自研页面

• 嵌入表单（orderNo、carrierCode 输入框）+ fetch 调用 + 响应展示区，适合对外门户

五、调试注意事项

• 查询类接口建议调试环境开放 GET 无鉴权或提供测试 token
• 展示真实响应耗时与 HTTP 状态码，便于联调排错
• 提供一键复制 cURL 命令功能，方便集成

如需，我可以进一步生成完整的 OpenAPI 3.0 YAML 文件或调试页面 HTML 代码。