跳至主要内容

Digiwin Webhook 串接

LifeERP 透過 Digiwin（鼎新） 介接第三方物流與倉儲。本篇說明如何接收 Digiwin 推送的出貨訂單與進退貨單，以及如何用 callback_url 回拋處理結果。

:::info 適用對象 此 API 供物流商 / WMS / 倉儲系統串接。一般電商通路串接訂單請改看 訂單串接教學。 :::

認證方式​

與 OMS 主 API 不同，Digiwin 端點採 API Key（標頭） 認證：

Authorization: <你的 API Key>

API Key 由 LifeCOM 核發。

一、推送出貨訂單​

POST /digiwin/orders/order
Content-Type: application/json
Authorization: <API Key>

主要欄位​

欄位必填說明
internal_name✓自訂編號（唯一值，最長 30）
name✓電商訂單編號
customer_name✓顧客姓名（最長 25）
delivery_name✓收件人姓名
phone✓顧客電話
delivery_charge✓運費
products✓商品陣列（見下）
address / city收件地址（超商取貨可為空）
callback_url處理完成後 LifeERP 回拋的網址
note備註
store_pickup_label_data超商取貨標籤資料（全家 / 萊爾富 / 7-11）

products[] 商品欄位​

欄位必填說明
sku✓商品貨號（最長 125）
quantity✓數量
storage_type✓商品倉別
combo_sku組合商品貨號
name品名
price單價
batch / identifier批號 / 識別碼

範例​

curl -X POST https://oms.lifecom.com.tw/digiwin/orders/order \
  -H "Content-Type: application/json" \
  -H "Authorization: $DIGIWIN_API_KEY" \
  -d '{
    "internal_name": "DGW-20260610-0001",
    "name": "SHOP-20260610-001",
    "customer_name": "王曉明",
    "delivery_name": "王曉明",
    "phone": "0988122122",
    "delivery_charge": 60,
    "address": "新北市汐止區新台五路一段102號11樓B室",
    "city": "新北市",
    "callback_url": "https://your-wms.example.com/lifeerp/callback",
    "products": [
      {
        "sku": "5A000236",
        "name": "測試商品 A",
        "quantity": 1,
        "storage_type": "1",
        "price": 500
      }
    ]
  }'

成功時回應 200。

二、推送進退貨單​

POST /digiwin/purchases/purchase

用於進貨、退貨、進貨停收三種單據。

欄位必填說明
form_no✓進貨/退貨單號（最長 255）
internal_form_no✓內部單號
form_type✓單據類型：1 進貨、2 退貨、3 進貨停收
shipping_type✓配送類型：1 廠商自取、2 物流配送、3 廠商配送
callback_url✓處理結果回拋網址
products✓商品陣列
sender_name / sender_address寄件人資訊

三、Callback 回拋機制​

當你在請求中提供 callback_url，LifeERP 在單據處理完成後，會以 POST 將結果回拋到該網址。你的端點應：

  1. 驗證來源（建議用白名單 IP 或共享密鑰）。
  2. 解析 body 取得單據狀態與託運/物流編號。
  3. 立即回應 200，把後續業務處理丟到佇列非同步執行，避免逾時。
sequenceDiagram
    participant W as 你的 WMS
    participant L as LifeERP / Digiwin
    W->>L: POST /digiwin/orders/order (含 callback_url)
    L-->>W: 200 已受理
    Note over L: OMS 內部處理出貨、產生託運單
    L->>W: POST callback_url (處理結果 + 託運編號)
    W-->>L: 200 已收到

:::tip 回拋失敗怎麼辦 請讓你的 callback_url 具備冪等性（以單號去重），因為重試機制可能造成同一結果被回拋多次。若你長時間未回 200，可改以 訂單清單查詢 主動對帳。 :::

相關 API 參考​

完整欄位、enum 與線上試打：