商品 API

创建、查询、更新和删除商品目录中的商品。

接口列表

GET

/products

products:read

获取商品分页列表。支持按状态、分类和关键词筛选。

GET

/products/:id

products:read

根据 ID 获取单个商品。

POST

/products

products:write

在商品目录中创建新商品。

PUT

/products/:id

products:write

更新现有商品。支持部分更新。

DELETE

/products/:id

products:write

软删除商品。可在 30 天内恢复。

字段参考

字段	类型	必填	描述
id	string	否	唯一商品标识符（只读）
sku	string	是	库存单位编码
name	string	是	商品名称
description	string	否	商品描述（支持 HTML）
barcode	string	否	产品主条码（UPC/EAN）
brand	string	否	产品品牌名称
categoryId	string	否	分类标识符
unitPrice	integer	是	价格（单位：分，例如 1999 = $19.99）
normalPrice	integer	否	原价/标价（单位：分，用于显示折扣）
purchasePrice	integer	否	采购价/成本价（单位：分）
weight	string	否	重量（克）
isActive	boolean	否	产品是否激活/已发布（默认：true）
stockTotal	integer	否	所有仓库的总可用库存（只读）
images	string[]	否	产品图片URL
createdAt	datetime	否	ISO 8601 时间戳（只读）
updatedAt	datetime	否	ISO 8601 时间戳（只读）

查询参数（列表）

字段	类型	必填	描述
page	integer	否	页码（默认：1）
limit	integer	否	每页条数（默认：20，最大：100）

示例

分页获取商品列表

bash

curl "https://api.mercozy.com/api/v1/external/products?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

创建商品

bash

curl -X POST "https://api.mercozy.com/api/v1/external/products" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "WDG-001",
    "name": "Premium Widget",
    "unitPrice": 2999,
    "normalPrice": 3999,
    "brand": "Acme Corp",
    "isActive": true
  }'