訂單串接教學

本篇帶你把 LifeERP 的訂單流程接進自己的系統。涵蓋四個最常用的場景，全部使用 defaultApi 的真實端點：

1. 查詢訂單清單
2. 建立訂單
3. 查詢訂單明細
4. 取消訂單與建立退貨

:::tip 前置作業 開始前請先完成 認證，取得 access_token。以下範例都假設你已帶上 Authorization: Bearer <token>。 :::

所有端點皆為 POST，Base URL 為 https://oms.lifecom.com.tw。

---

1. 查詢訂單清單

POST /api/v2/default/apiOrderList/searchList

用各種條件篩選訂單。欄位採 orders.<欄位> 命名，支援區間查詢（@start / @end）。

常用篩選欄位

欄位	說明
orders.markets_order_no	賣場訂單編號
orders.orders_id	LifeERP 訂單編號
orders.delivery_name	收件人姓名
orders.orders_amt@start / @end	訂單金額區間
orders.markets_no	賣場通路：1 Upload、6 Shopee、13 Upload(公司倉)、14 Upload(公司退貨倉)
orders.orders_status	訂單狀態（7 = 已成立，完整 enum 見 API 參考）
orders.process_flag	作業狀態：0 未處理、4 揀貨中、9 退貨完成、22 出貨結案…

範例：查詢「已成立」且來自 Shopee 的訂單

curl -X POST https://oms.lifecom.com.tw/api/v2/default/apiOrderList/searchList \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "orders.orders_status": "7",
    "orders.markets_no": "6"
  }'

💡 實務上常以「定時輪詢 + process_flag 條件」抓出需要處理的新單；若要即時，建議改用 Webhook 串接。

---

2. 建立訂單（推單進 OMS）

POST /api/v2/default/action/createOrders

把外部通路的訂單批次推進 LifeERP。請求以 batch 陣列承載多筆訂單，一次可送多筆。

關鍵欄位

欄位	必填	說明
markets_order_no	✓	賣場訂單編號（你系統的單號）
markets_no	✓	賣場通路代碼（如 13）
customers_name / delivery_name	✓	購買人 / 收件人姓名
delivery_mobile / delivery_address	✓	收件人電話 / 地址
products_model	✓	商品貨號
markets_products_qty	✓	數量
markets_products_cost	✓	單價
orders_amt	✓	訂單總金額
warehouse_no	✓	出貨倉別
payment_type / ship_type	✓	付款方式 / 配送方式
order_valid_time_ts		訂單成立時間 YYYY-MM-DD HH:mm:ss
invoice_data		發票資料（JSON 陣列字串）
delivery_info		跨境/海外收件人結構化地址（JSON）

範例：批次建立兩筆訂單

curl -X POST https://oms.lifecom.com.tw/api/v2/default/action/createOrders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "batch": [
      {
        "markets_order_no": "SHOP-20260610-001",
        "markets_no": "13",
        "markets_order_type": "0",
        "customers_name": "王曉明",
        "delivery_name": "王曉明",
        "order_user_mobile": "0988122122",
        "delivery_mobile": "0988122122",
        "delivery_postcode": "221",
        "delivery_address": "新北市汐止區新台五路一段102號11樓B室",
        "order_valid_time_ts": "2026-06-10 17:21:00",
        "products_name": "測試商品 A",
        "products_model": "5A000236",
        "markets_products_cost": "500",
        "markets_products_qty": "1",
        "orders_amt": "700",
        "ship_fee": "0",
        "warehouse_no": "1000",
        "payment_type": "4",
        "ship_type": "6"
      }
    ]
  }'

:::caution 冪等性 請以 markets_order_no 作為你方的唯一單號，並在重送前先用 查詢訂單清單 確認該單是否已存在，避免重複建立。 :::

---

3. 查詢訂單明細

POST /api/v2/default/apiOrderList/searchDetail

拿到訂單清單後，用訂單編號查單筆的完整商品明細、金額拆解與物流資訊。

curl -X POST https://oms.lifecom.com.tw/api/v2/default/apiOrderList/searchDetail \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "orders.markets_order_no": "SHOP-20260610-001"
  }'

---

4. 取消訂單與建立退貨

取消訂單

POST /api/v2/default/action/cancelOrder

對尚未出貨的訂單執行取消。請帶上訂單識別欄位（如 markets_order_no）。

curl -X POST https://oms.lifecom.com.tw/api/v2/default/action/cancelOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "markets_order_no": "SHOP-20260610-001" }'

建立退貨單

POST /api/v2/default/action/createReturnOrders

對已出貨訂單建立退貨。退貨完成後，訂單的 process_flag 會進到 9（退貨完成）。退貨確認另有 POST /api/v2/orders/confirmReturn 可呼叫。

---

典型整合流程

flowchart LR
    A[通路新訂單] -->|createOrders| B[OMS 建立訂單]
    B --> C{輪詢 / Webhook}
    C -->|searchList + process_flag| D[追蹤揀貨/出貨]
    D --> E[出貨結案 process_flag=22]
    B -.取消.-> F[cancelOrder]
    E -.退貨.-> G[createReturnOrders]

下一步

• 想即時收到物流狀態？→ Digiwin Webhook 串接
• 查完整欄位與線上試打 → V2 API 參考