訂單 API

查詢訂單、更新訂單狀態和管理物流資訊。

端點列表

GET

/orders

orders:read

取得訂單分頁列表。支援按狀態和日期範圍篩選。

GET

/orders/:id

orders:read

取得包含所有行項目和物流詳情的單一訂單。

PUT

/orders/:id/status

orders:write

更新訂單狀態（例如標記為已出貨）。

POST

/orders/:id/shipment

orders:write

為訂單新增物流追蹤資訊。

欄位參考

欄位	類型	必填	描述
id	string	否	唯一訂單識別碼（唯讀）
orderNumber	string	否	可讀訂單編號（唯讀）
customerId	string	否	客戶ID（訪客訂單無此欄位）
status	string	否	PENDING、CONFIRMED、PROCESSING、SHIPPED、DELIVERED、CANCELLED、REFUNDED
paymentStatus	string	否	pending、paid、refunded、failed
paymentMethod	string	否	使用的支付方式（如 stripe、cod）
total	integer	否	總金額（單位：分，唯讀）
items	OrderLine[]	否	行項目陣列（唯讀）
shippingAddress	Address	否	收貨地址物件
fulfillmentType	string	否	shipping、pickup、delivery 或 digital
createdAt	datetime	否	ISO 8601 時間戳（唯讀）
updatedAt	datetime	否	ISO 8601 時間戳（唯讀）

查詢參數（列表）

欄位	類型	必填	描述
page	integer	否	頁碼（預設：1）
limit	integer	否	每頁筆數（預設：20，最大：100）

範例

取得最近訂單

bash

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

更新訂單狀態

bash

curl -X PUT "https://api.mercozy.com/api/v1/external/orders/ord_abc123/status" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped"
  }'

建立物流追蹤

bash

curl -X POST "https://api.mercozy.com/api/v1/external/orders/ord_abc123/shipment" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "trackingNumber": "7489236401",
    "trackingUrl": "https://www.fedex.com/track?id=7489236401"
  }'