OMS 订单 API
最后更新 2026-10-13
创建草稿销售订单、查询订单、驱动订单状态机与推送 WMS。
创建草稿订单#
POST /api/oms/orders
{
"customer_id": "<uuid>",
"channel_id": "<uuid>",
"channel_order_no": "AMZ-123",
"merchant_id": "<uuid>",
"warehouse_id": "<uuid>",
"retailer_id": "<uuid>",
"carrier_code": "UPS",
"service_code": "GROUND",
"currency": "USD",
"ship_to": { "name": "…", "address": "…", "city": "…", "state": "…", "postal": "…", "country": "US", "phone": "…" },
"discount": 0,
"shipping_fee": 8.5,
"tax": 0,
"required_ship_date": "2026-10-20",
"note": "…",
"lines": [
{ "product_id": "<uuid>", "qty": 10, "price": 12.9 }
]
}
// -> data.order_no = "SO-YYYYMMDD-####", status = "draft"查询订单#
GET /api/oms/orders?statuses=confirmed,allocated&channel_id=<uuid>&q=AMZ-123&created_from=2026-10-01&page=1&page_size=20
// filters: status (single) | statuses (comma-separated) | channel_id | created_from/to (ISO) | q (order_no / channel_order_no / customer fuzzy)
GET /api/oms/orders/<id>
// detail incl. lines, customer, channel; wms_shipments = all linked WMS shipments (no/status/warehouse/carrier/tracking/split flag)订单状态机#
PATCH /api/oms/orders/<id>
{ "action": "submit" } // draft -> pending_review
{ "action": "approve" } // pending_review -> confirmed (ATP check)
{ "action": "allocate", "warehouse_id": "<uuid>" } // confirmed -> allocated
{ "action": "release", "ship_mode": "parcel" } // allocated -> released
{ "action": "fulfill" } // released -> fulfilled
{ "action": "partial_fulfill" }
{ "action": "deliver" }
{ "action": "cancel" } // only before released
// illegal transition -> 400; draft edit mode: { "fields": {…}, "lines": […] } (draft only)- approve 会做 ATP 检查（wms_sync 模式只读查 WMS 库存余额；standalone 查 OMS 库存）。
- release 要求 ship_mode，会建 allocation 行（事件 sales_order.released）。
推送 WMS#
POST /api/oms/orders/<id>/push-to-wms
{ "warehouse_id": "<uuid>", "ship_mode": "parcel" } // both optional
// order status must be confirmed | allocated; result: released + WMS shipment created at commit (inventory locked)push-to-wms 仅在 wms_sync 库存模式下可用；standalone（oms_standalone）订单会被 400 NOT_WMS_SYNC 拒绝。推送后由 WMS 驱动出库单：commit → picking → picked → packed → shipped（带 tracking）→ delivered，每次流转实时镜像回 OMS 事件；OMS 没有 shipped 状态——WMS 发运后回写 OMS 为 fulfilled。