商品与 SKU

GET /products

分页获取所有已上架商品。

Query 参数

参数	类型	必填	默认	说明
page	number	否	1	页码
page_size	number	否	20	每页 1～100 条

响应

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "slug": "example-product",
      "title": { "zh-CN": "示例商品", "en-US": "Example Product" },
      "description": { "zh-CN": "商品描述" },
      "content": {},
      "seo_meta": {},
      "images": ["https://example.com/image.jpg"],
      "tags": ["hot"],
      "price_amount": "7.90",
      "fulfillment_type": "auto",
      "manual_form_schema": null,
      "is_active": true,
      "category_id": 1,
      "skus": [
        {
          "id": 11,
          "sku_code": "SKU-1",
          "spec_values": { "类型": "标准" },
          "price_amount": "7.90",
          "stock_status": "in_stock",
          "stock_quantity": 100,
          "is_active": true
        }
      ],
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

Product 字段

字段	类型	说明
id	number	商品 ID
slug	string	商品 URL 标识
title	object	多语言标题
description	object	多语言描述
content	object	多语言详情内容
seo_meta	object	SEO 元信息
images	string[]	图片列表
tags	string[]	标签
price_amount	string	实际售价
original_price	string	原价，有折扣时返回
member_price	string	会员价，有会员折扣时返回
fulfillment_type	string	auto 或 manual
manual_form_schema	object	人工交付表单结构
category_id	number	分类 ID
skus	array	SKU 列表

SKU 字段

字段	类型	说明
id	number	创建订单时使用的 sku_id
sku_code	string	稳定的业务映射编码
spec_values	object	规格键值
price_amount	string	SKU 实际售价
original_price	string	原价
member_price	string	会员价
stock_status	string	库存状态
stock_quantity	number	-1 表示无限库存
is_active	boolean	是否启用

sku_code 与 sku_id

本地配置建议保存 sku_code，同步商品时解析成当前 sku_id。调用 POST /orders 时必须提交数字 sku_id，不能直接提交 sku_code。

库存状态

状态	说明
unlimited	无限库存，stock_quantity = -1
in_stock	库存充足
low_stock	低库存
out_of_stock	已售罄

GET /products/:id

按商品 ID 获取单个商品，成功时返回：

{
  "ok": true,
  "product": {}
}

错误码	HTTP	说明
product_not_found	404	商品不存在
product_unavailable	404	商品已下架

分页同步建议

1. 使用 page_size=100。
2. 逐页请求，直到累计数量达到 total。
3. 以 sku_code 作为外部映射键，同时更新 sku_id、价格与库存。
4. 不要只请求第一页。

完整分页实现已经包含在 Python 客户端和 Go 客户端中。