跳至主要內容

API接口设计

HSXISAWD2026/3/20大约 3 分钟

API 接口设计

API 规范

基础信息

项目说明
基础路径/api/
协议HTTP/HTTPS
数据格式JSON
认证方式JWT Bearer Token

请求格式

GET /api/products/?page=1&page_size=10 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    "count": 100,
    "next": "http://api.example.com/api/products/?page=2",
    "previous": null,
    "results": [...]
  }
}

错误响应

{
  "code": 400,
  "message": "参数错误",
  "errors": {
    "field_name": ["错误信息"]
  }
}

认证接口

用户登录

POST /api/auth/login/

请求体:

{
  "username": "admin",
  "password": "password123"
}

响应:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "user": {
      "id": 1,
      "username": "admin",
      "nickname": "管理员"
    }
  }
}

Token 刷新

POST /api/auth/refresh/

请求体:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

响应:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

用户登出

POST /api/auth/logout/
Authorization: Bearer <token>

请求体:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

用户接口

获取当前用户信息

GET /api/user/info/
Authorization: Bearer <token>

响应:

{
  "code": 200,
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "管理员",
    "email": "admin@example.com",
    "phone": "13800138000",
    "gender": "male",
    "avatar": "/media/avatar/default.png",
    "is_active": true
  }
}

更新用户信息

PATCH /api/user/info/
Authorization: Bearer <token>

请求体:

{
  "nickname": "新昵称",
  "email": "new@example.com"
}

用户列表 (管理员)

GET /api/user/?page=1&page_size=10
Authorization: Bearer <token>

查询参数:

参数类型说明
pageint页码
page_sizeint每页数量
usernamestring用户名筛选
is_activeboolean状态筛选

商品接口

商品列表

GET /api/products/
Authorization: Bearer <token>

查询参数:

参数类型说明
pageint页码
page_sizeint每页数量
goods_namestring商品名称搜索
statusstring商品状态
sp_biz_typestring商品分类
orderingstring排序字段

响应:

{
  "code": 200,
  "data": {
    "count": 50,
    "results": [
      {
        "id": 1,
        "goods_name": "iPhone 14 Pro",
        "goods_desc": "全新未拆封",
        "original_price": "8999.00",
        "price": "7500.00",
        "item_biz_type": "normal",
        "sp_biz_type": "phone",
        "status": "active",
        "outer_id": "SKU001",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

创建商品

POST /api/products/
Authorization: Bearer <token>

请求体:

{
  "goods_name": "iPhone 14 Pro",
  "goods_desc": "全新未拆封，国行正品",
  "original_price": 8999.00,
  "price": 7500.00,
  "item_biz_type": "normal",
  "sp_biz_type": "phone",
  "outer_id": "SKU001",
  "category_id": 10001
}

获取商品详情

GET /api/products/{id}/
Authorization: Bearer <token>

更新商品

PUT /api/products/{id}/
Authorization: Bearer <token>

删除商品

DELETE /api/products/{id}/
Authorization: Bearer <token>

批量操作

POST /api/products/batch/
Authorization: Bearer <token>

请求体:

{
  "action": "delete",
  "ids": [1, 2, 3]
}

发布接口

发布任务列表

GET /api/autoPublish/tasks/
Authorization: Bearer <token>

创建发布任务

POST /api/autoPublish/tasks/
Authorization: Bearer <token>

请求体:

{
  "name": "批量发布任务",
  "template_id": 1,
  "goods_ids": [1, 2, 3, 4, 5],
  "schedule_time": "2024-01-15T10:00:00Z"
}

执行发布任务

POST /api/autoPublish/tasks/{id}/execute/
Authorization: Bearer <token>

停止发布任务

POST /api/autoPublish/tasks/{id}/stop/
Authorization: Bearer <token>

模板接口

模板列表

GET /api/autoPublish/templates/
Authorization: Bearer <token>

创建模板

POST /api/autoPublish/templates/
Authorization: Bearer <token>

请求体:

{
  "name": "手机发布模板",
  "title_template": "{brand} {model} {condition}",
  "desc_template": "品牌：{brand}\n型号：{model}\n成色：{condition}",
  "price_strategy": "original",
  "category_id": 10001
}

更新模板

PUT /api/autoPublish/templates/{id}/
Authorization: Bearer <token>

删除模板

DELETE /api/autoPublish/templates/{id}/
Authorization: Bearer <token>

图片接口

上传图片

POST /api/autoPublish/images/upload/
Authorization: Bearer <token>
Content-Type: multipart/form-data

请求体:

file: (binary)
type: goods  // goods | context | tag

响应:

{
  "code": 200,
  "data": {
    "id": 123,
    "url": "/media/images/abc123.jpg",
    "thumbnail": "/media/images/abc123_thumb.jpg"
  }
}

商品图片列表

GET /api/autoPublish/goods-images/?goods_id=1
Authorization: Bearer <token>

删除图片

DELETE /api/autoPublish/images/{id}/
Authorization: Bearer <token>

分类接口

获取分类树

GET /api/products/categories/tree/
Authorization: Bearer <token>

响应:

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "手机数码",
      "children": [
        {
          "id": 10,
          "name": "手机",
          "children": [...]
        }
      ]
    }
  ]
}

区域接口

获取区域列表

GET /api/products/regional/
Authorization: Bearer <token>

查询参数:

参数类型说明
p_idint父级ID (0 为省级)
area_typestring区域类型

移动端接口

订单列表

GET /api/mobile/orders/
Authorization: Bearer <token>

查询参数:

参数类型说明
statusstring订单状态
start_datedate开始日期
end_datedate结束日期

订单详情

GET /api/mobile/orders/{id}/
Authorization: Bearer <token>

更新订单状态

PATCH /api/mobile/orders/{id}/
Authorization: Bearer <token>

请求体:

{
  "status": "shipped"
}

状态码说明

状态码说明
200请求成功
201创建成功
204删除成功
400请求参数错误
401未认证
403无权限
404资源不存在
500服务器错误

分页说明

默认使用 DRF 的分页器：

  • page: 页码，从 1 开始
  • page_size: 每页数量，默认 10，最大 100

响应包含：

  • count: 总数量
  • next: 下一页 URL
  • previous: 上一页 URL
  • results: 数据列表
Default footer
Copyright © 2026 HSXISAWD