跳至主要内容
Version: 1.0.0

訂單/採購單 callback API

方向說明:這是 LifeERP 主動送出的請求(outbound webhook)​

本頁每一個項目,都是 LifeERP 主動以 HTTP POST 送到串接方設定的 webhook_url 的請求。 串接方不需要(也無法)呼叫我方端點,因此頁面不提供可試打的 URL 與 curl 範例。

項目內容
送出方LifeERP OMS(訂單/採購單狀態變更時觸發)
接收方串接方自行提供的 URL(設定於 webhook_setting.webhook_url)
方法POST,Content-Type: application/json,連線逾時 60 秒
簽章標頭Signature:小寫 hex 的 HMAC-SHA256(金鑰=option_json.webhook_secret)
回應要求請回 HTTP 200(詳見「回應約定」)
重試最多 3 次,間隔 10 秒、100 秒(指數退避)
順序不保證事件順序(各自獨立佇列 job)

兩種信封:v1 與 v2​

兩種信封只差「外層三欄」,內層資料容器與欄位完全相同;由 webhook_setting.webhook_type 決定。

v1 信封v2 信封
成功旗標result(boolean)done(boolean)
訊息msg(string)msg(string)
資料容器data(object)retval(object)
webhook_typeDefaultOrders / DefaultPurchaseDefaultOrdersV2 / DefaultPurchaseV2

成功時 msg 為系統語系字串「執行成功」;查無資料或發生例外時成功旗標為 false, msg 帶錯誤訊息,資料容器為空。

驗簽方式​

簽章是對 原始 request body 位元組 計算,不是對重新排序後的 JSON:

Signature = hex_lower( HMAC-SHA256( key = webhook_secret, message = raw_request_body ) )
  • 請用收到的原始 body 字串驗簽,不要先 parse 再 json_encode(鍵序與空白會改變結果)。
  • webhook_secret 為必填:請於設定時提供一組高強度隨機字串,並在接收端同一把金鑰驗簽。
  • 沒有時間戳、沒有 nonce,不具防重放能力;重複投遞請以 body 內容(如 orders_id + 事件)做幂等。

回應約定​

  • 請回 HTTP 200 表示已接收。
  • 回其他 2xx(例如 201、204)會被視為業務失敗而重送同一份 payload(最多再 3 次)。
  • 非 2xx:HTTP 層重試 3 次(間隔 10 秒、100 秒),最終失敗後不再重送,我方會發失敗通知信給維運。

觸發事件(共 19 個)​

訂單類(14 個,trigger_type = orders)​

trigger_event語意觸發條件(orders_status = os)
salesPrepared訂單確認出貨(POS 送單)os=7 且 process_flag=0;或平台已開立發票(receipt_status=311)且備有發票資料/發票號
salesShipped已出貨os=220 且有出貨日期
orderIn已轉入os=1
PRESHIP預備出貨os=5、6
CHECKED風控確認os=7
TOWMS已產出給倉庫os=8
PADDING暫不出貨os=25
STORE已到店os=270
ARRIVED配達消費者os=230
FINISHED結案os=300
PICKED消費者已取件os=290
salesCanceled出貨前取消os=24
returnFinished退貨單結案退貨單且 os=300
returnPrepared退貨取號成功、準備轉倉process_flag=1 且 os=267

採購單類(5 個,trigger_type 為採購單對應設定)​

trigger_event語意觸發條件(purchase_header.status)
purchaseWait等待處理60
purchaseQcFinish品保結案62
purchaseClosed結案(採購完成)69
purchaseClosedErr結案失敗401
purchaseCancelled取消24

串接方需提供與設定的項目​

設定必填說明
webhook_url是接收端完整 URL,我方只 POST 這個 URL,不附加任何 path 參數
trigger_event是上表事件字串
webhook_type是DefaultOrders / DefaultOrdersV2 / DefaultPurchase / DefaultPurchaseV2,決定信封格式
refer_target_type / refer_target_id是訂單:App\Models\Markets + markets_no;採購:App\Models\Warehouse + warehouse_no
option_json.webhook_secret是簽章金鑰,請提供高強度隨機字串(文件要求必填)
option_json.skipped_trade_ids否排除不送的 trade_id 清單

未建立對應的 webhook_setting 資料列時,我方不會送出任何回拋。

幂等與去重​

  • 同一組(設定 + 單號)在成功前只會排入一次;但重試會讓同一份 payload 多次到達,接收端必須幂等。
  • 建議以「事件 + 主鍵(orders.orders_id 或 purchase.purchase_header_id)+ 狀態」為幂等鍵。

不在本文件範圍​

客製回拋格式(特定通路/客戶專屬)與其他非公開整合,未列於公開文件;需要時請洽 LifeCOM 窗口。