HKAIEHF Logo

香港人工智能教育及健康基金

Hong Kong AI Education & Health Foundation

Webhook 接口文檔

快遞公司可以通過此 Webhook 接口自動更新郵寄狀態，無需人工介入。

Webhook 端點
快遞公司應將回調請求發送到以下 URL
POST https://hk-aiedu-m2lci2i3.manus.space/api/webhook/shipping-update
請求格式
請求必須使用 JSON 格式，Content-Type: application/json

請求參數

trackingNumber (string, 必填) - 快遞單號
status (string, 必填) - 快遞狀態，可選值：
  • • in_transit - 運輸中
  • • out_for_delivery - 派送中
  • • delivered - 已送達
  • • exception - 異常狀態
statusDescription (string, 必填) - 狀態描述
timestamp (string, 必填) - ISO 8601 格式時間戳
location (string, 可選) - 當前位置
courierCode (string, 可選) - 快遞公司代碼

請求示例

{
  "trackingNumber": "SF1234567890",
  "status": "delivered",
  "statusDescription": "包裹已成功送達",
  "timestamp": "2026-01-06T15:30:00Z",
  "location": "香港九龍",
  "courierCode": "sf_express"
}
響應格式
系統將返回 JSON 格式的響應

成功響應 (200 OK)

{
  "success": true,
  "message": "郵寄狀態已更新為 delivered"
}

失敗響應 (400 Bad Request)

{
  "success": false,
  "message": "找不到快遞單號對應的訂單: SF1234567890"
}
狀態映射邏輯
系統如何處理不同的快遞狀態
in_transit
→ 如果當前狀態是「待處理」或「處理中」，更新為「已寄出」
out_for_delivery
→ 如果當前狀態不是「已寄出」或「已送達」，更新為「已寄出」
delivered
→ 更新為「已送達」，記錄送達時間
exception
→ 記錄異常日誌，發送通知給管理員，需要人工處理
自動通知機制
當狀態更新時，系統會自動執行以下操作
  • 更新數據庫中的郵寄狀態和時間戳
  • 自動發送通知給管理員（包含學員姓名、證書編號、新狀態）
  • 記錄狀態變更日誌，便於追蹤和審計
  • 會員可在「我的訂單」頁面即時查看最新郵寄進度