庫存異動 API

追蹤和記錄倉庫間的庫存異動。每一次庫存變化都會被記錄為一筆異動記錄。

端點列表

GET

/stock-movements

stock_movements:read

取得分頁的庫存異動列表。支援依商品、倉庫、類型和日期範圍篩選。

POST

/stock-movements

stock_movements:write

記錄新的庫存異動。庫存數量將自動更新。

欄位參考

欄位	類型	必填	描述
id	string	否	唯一庫存異動識別碼（唯讀）
productId	string	是	商品識別碼
productSku	string	否	商品 SKU（唯讀）
productName	string	否	商品名稱（唯讀）
warehouseId	string	是	倉庫識別碼
warehouseName	string	否	倉庫名稱（唯讀）
variantId	string	否	商品變體識別碼（如適用）
quantity	integer	是	異動數量（正整數）
movementType	string	是	IN、OUT、ADJUSTMENT、TRANSFER_OUT 或 TRANSFER_IN
reference	string	否	參考編號（如採購單號）
unitCost	integer	否	單位成本（以分為單位）
batchNumber	string	否	批次號
notes	string	否	附加備註
createdAt	datetime	否	ISO 8601 時間戳（唯讀）

查詢參數（列表）

欄位	類型	必填	描述
page	integer	否	頁碼（預設：1）
limit	integer	否	每頁筆數（預設：20，最大：100）
productId	string	否	依商品 ID 篩選
warehouseId	string	否	依倉庫 ID 篩選
movementType	string	否	依類型篩選：IN、OUT、ADJUSTMENT、TRANSFER_OUT、TRANSFER_IN
from	string	否	起始日期篩選（ISO 8601）
to	string	否	截止日期篩選（ISO 8601）

範例

取得庫存異動列表

bash

curl "https://api.mercozy.com/api/v1/external/stock-movements?page=1&limit=20&movementType=IN" \
  -H "X-API-Key: mk_live_xxxxx"

建立庫存異動

bash

curl -X POST "https://api.mercozy.com/api/v1/external/stock-movements" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product-uuid",
    "warehouseId": "warehouse-uuid",
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "notes": "Initial stock"
  }'

回應範例

json

{
  "data": {
    "id": "sm_abc123",
    "productId": "product-uuid",
    "productSku": "WDG-001",
    "productName": "Premium Widget",
    "warehouseId": "warehouse-uuid",
    "warehouseName": "Main Warehouse",
    "variantId": null,
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "unitCost": null,
    "batchNumber": null,
    "notes": "Initial stock",
    "createdAt": "2025-12-15T10:30:00Z"
  }
}