库存变动 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"
  }
}