订单 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"
  }'