Version: 1.0.0
訂單類(14 個,
採購單類(5 個,
訂單/採購單 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_type | DefaultOrders / DefaultPurchase | DefaultOrdersV2 / 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 窗口。