查询订单列表 API 文档

端点概述

• 功能：查询订单列表，用于 Android 订单中心的分页展示，支持状态筛选、时间范围过滤与创建时间排序。
• 数据范围：仅返回订单概要字段（id、金额、币种、状态、创建时间、部分商品项）；详情请调用 GET /api/v1/orders/{id}。
• 鉴权：Bearer Token。
• 性能与缓存：相同查询条件在 60 秒内可被 CDN 缓存；建议在客户端列表启用本地分页占位以优化体验。

请求方法

• HTTP 方法与路径：GET /api/v1/orders
• 请求头：
  • Authorization: Bearer
  • Accept: application/json
  • X-Client-Platform: android
• 请求示例：
  • /api/v1/orders?page=1&page_size=20&status=paid&sort=created_at_desc

请求参数

响应示例

• 成功响应（200）

{
  "data": [
    {
      "id": "ord_102938",
      "amount": 128.50,
      "currency": "CNY",
      "status": "paid",
      "created_at": "2025-05-21T09:15:31Z",
      "items": [
        {
          "sku": "SKU-AX12",
          "name": "蓝牙耳机",
          "qty": 1,
          "price": 128.50
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 36,
    "has_next": true
  }
}

• 错误响应示例（以 400 为例）

{
  "error": {
    "code": 400,
    "message": "参数格式错误"
  }
}

错误代码

上传图片资源 API

端点概述

用于Android客户端上传头像或内容图片。服务端会根据用途进行处理：自动将图片长边压缩至不超过1920px；当 purpose=avatar 时额外生成256x256缩略图。成功后返回可访问的原图与缩略图URL及相关元信息。

请求方法

• HTTP 方法：POST
• 路径：/api/v1/media/images
• 鉴权：Bearer Token

请求头

请求参数（multipart/form-data）

响应示例

成功响应（201 Created）

{
  "id": "img_7755",
  "url": "https://cdn.sample.app/i/img_7755.jpg",
  "thumbnail_url": "https://cdn.sample.app/i/img_7755_thumb.jpg",
  "width": 1080,
  "height": 1080,
  "content_type": "image/jpeg",
  "sha256": "a3b1...",
  "created_at": "2025-05-21T09:20:00Z"
}

错误响应（示例）

{
  "error": "bad_request",
  "message": "file is required or purpose is invalid"
}

错误代码

Android 集成提示

• 计算并设置 X-Content-MD5：上传前读取文件流计算MD5（32位hex小写），放入请求头；服务端将进行完整性校验。
• 使用 OkHttp MultipartBody 传 file 与文本字段：file 对应 binary 表单项，purpose/meta 作为 text 表单项。
• 文件限制：单文件<=10MB，格式仅支持 jpg/png/webp；不支持断点续传。