【订单查询接口文档】本接口文档旨在为开发者提供关于“订单查询”功能的详细说明，包括接口的功能、调用方式、参数定义及响应格式等内容。通过该接口，系统可以实现对用户订单信息的快速获取与展示，适用于电商平台、物流管理系统、客户服务中心等场景。
一、接口概述
接口名称：订单查询接口
接口地址：`/api/order/query`
请求方法：GET / POST
协议类型：HTTP/HTTPS
版本号：v1.0
该接口主要用于根据用户提供的订单编号或相关条件，查询对应的订单信息，返回订单的基本信息、状态、商品详情、支付情况等。
二、请求参数说明
| 参数名 | 类型 | 必填 | 说明 |
|----------------|--------|------|------------------------------|
| order_id | String | 是 | 订单唯一标识符（可选） |
| user_id| String | 否 | 用户唯一标识符（可选） |
| start_time | String | 否 | 查询起始时间（格式：YYYY-MM-DD HH:mm:ss） |
| end_time | String | 否 | 查询结束时间（格式：YYYY-MM-DD HH:mm:ss） |
| status | String | 否 | 订单状态（如：已支付、已发货等） |
| page | Integer| 否 | 当前页码（默认值：1）|
| page_size| Integer| 否 | 每页显示条数（默认值：10） |
> 注意：建议至少提供一个查询条件，如 `order_id` 或 `user_id`，以提高查询效率和准确性。
三、请求示例
示例1：按订单ID查询
```http
GET /api/order/query?order_id=20240801123456 HTTP/1.1
Host: api.example.com
```
示例2：按用户ID和时间范围查询
```http
POST /api/order/query HTTP/1.1
Content-Type: application/json
{
"user_id": "U123456",
"start_time": "2024-08-01 00:00:00",
"end_time": "2024-08-31 23:59:59"
}
```
四、响应内容说明
接口返回数据为 JSON 格式，包含以下字段：
| 字段名 | 类型 | 说明 |
|----------------|--------|------------------------------|
| code | Integer| 状态码（200 表示成功） |
| message| String | 返回信息（如：“查询成功”） |
| data | Object | 返回的数据对象 |
| total| Integer| 总记录数（分页时使用） |
| list | Array| 订单列表，每个元素为订单详情 |
示例响应：
```json
{
"code": 200,
"message": "查询成功",
"data": {
"total": 2,
"list": [
{
"order_id": "20240801123456",
"user_id": "U123456",
"order_time": "2024-08-01 12:34:56",
"status": "已支付",
"amount": "150.00",
"items": [
{"product_id": "P001", "name": "商品A", "price": "50.00", "quantity": 2},
{"product_id": "P002", "name": "商品B", "price": "50.00", "quantity": 1}
]
},
{
"order_id": "20240802789012",
"user_id": "U123456",
"order_time": "2024-08-02 15:23:45",
"status": "已发货",
"amount": "200.00",
"items": [
{"product_id": "P003", "name": "商品C", "price": "100.00", "quantity": 2}
]
}
]
}
}
```
五、错误码说明
| 错误码 | 描述 |
|--------|--------------------------|
| 400| 请求参数缺失或格式错误 |
| 401| 权限不足或未认证 |
| 404| 未找到符合条件的订单 |
| 500| 服务器内部错误 |
六、注意事项
1. 接口支持跨域访问，但需配置相应的 CORS 策略。
2. 建议在高并发场景下使用分页机制，避免一次性返回过多数据。
3. 对于敏感信息（如用户手机号、地址等），应根据业务需求进行脱敏处理。
4. 所有时间参数均使用 UTC 时间格式，确保跨时区一致性。
七、版本更新记录
- v1.0：初始版本，支持基础订单查询功能。
- v1.1：新增按用户ID查询、时间范围筛选等功能。
- v1.2：优化响应结构，增加分页支持。
如需进一步了解接口细节或对接流程，请联系技术支持团队。
