商品 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
  }'