跳转到内容

商品 API

GET /api/v1/products

查询参数:

  • page —— 页码(默认:1)
  • per_page —— 每页条数(默认:20,最大 100;超过 100 会被截断)
  • category —— 按分类 slug 过滤
  • search —— 按标题/描述搜索

响应:

{
"products": [
{
"id": "uuid",
"title": "Acme Ceramic Mug",
"slug": "acme-ceramic-mug",
"sku": "ACME-MUG",
"price": 24.00,
"currency": "USD",
"inventory_quantity": 142,
"weight": 0.4,
"weight_unit": "kg",
"is_active": true,
"image_url": "https://...",
"categories": [{ "id": "uuid", "name": "Gear", "slug": "gear" }]
}
],
"meta": { "page": 1, "per_page": 20, "total": 53, "total_pages": 3 }
}

meta.total 是过滤后跨页的总条数, meta.total_pages = ceil(total / per_page) —— 分页请依据它, 不要靠猜。

GET /api/v1/products/:id

返回完整商品详情,包括变体、图片和分类。

POST /api/v1/products
Authorization: Bearer <admin_token>
{
"title": "Product Name",
"slug": "product-name",
"description": "...",
"sku": "SKU-001",
"price": 29.99,
"currency": "USD",
"inventory_quantity": 100,
"weight": 0.5,
"weight_unit": "kg",
"is_active": true
}
PATCH /api/v1/products/:id
Authorization: Bearer <admin_token>

部分更新——只包含要修改的字段。

DELETE /api/v1/products/:id
Authorization: Bearer <admin_token>

软删除(设置 is_active = false)。

GET /api/v1/products/:id/variants
POST /api/v1/products/:id/variants
PATCH /api/v1/products/:id/variants/:variant_id
DELETE /api/v1/products/:id/variants/:variant_id
GET /api/v1/products/:id/images
POST /api/v1/products/:id/images
DELETE /api/v1/products/:id/images/:image_id