NAV Navbar
json
中文
English

Webhook(zh-tw)

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

說明

這是 Boxful WEBHOOK API 專用文件，僅提供 Boxful fulfillment 商家使用。

Region

Hook Post 統一格式

主要資料放置於 payload 參數內，請依據各事件回覆格式參考。


若對想驗證資料來源可靠性請透過 validator_code 解碼後可得到完整 payload

{
  "timestamp": 1608202713,
  "region": "tw",
  "event_type": "logistics",
  "event": "update",
  "payload": {},
  "validator_code": "..."
}

可靠性驗證

可靠性驗證採用 AES-256-CBC 加密

Handle 需統一向左側補 0 至 16 碼

function decryptValidatorCode($data = "", $token = "", $handle = "")
{
    $output = '';
    $handle = str_pad($handle, 16, '0', STR_PAD_LEFT);
    $string = openssl_decrypt(hex2bin($data), 'AES-256-CBC', $token, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING,
        $handle);
    $string_ascii = ord(substr($string, -1));
    $stringing_chr = chr($string_ascii);
    if (preg_match("/$stringing_chr{" . $string_ascii . "}/", $string)) {
        $string = substr($string, 0, strlen($string) - $string_ascii);
        parse_str($string, $output);
    }
    return $output;
}

事件網址設定

請提供事件類別.事件項目.傳送網址給 Boxful ex. logistics.create http://api.boxful.com/webhook_url

事件列表

HEAD /Webhook-Description

事件總覽

event_type event 觸發時機 回傳格式
pickup main_update 入倉單(PL)資料異動時 pickup_main_update
pickup item_update 入倉品項資料異動時 pickup_item_update
logistics create 出貨物流單建立時 shipment_and_logistics
logistics update 物流商、物流狀態、發車時間、物流追蹤碼其中一項異動時 shipment_and_logistics
reverse create 逆物流單建立時 reverse_create
reverse update 逆物流單資料異動時 reverse_update
inventory low_warning 當商品抵達庫存水位預警時通知每日一次 inventory_low_warning

接收注意事項

  1. 請以 HTTP 200 回應。非 200 會被視為失敗,同一則訊息最多重試 3 次,超過即不再送出,亦不提供事後補送。
  2. 台灣區收件人資訊為遮蔽值。name、phone、address 在台灣區會以部分遮蔽形式回傳(例:測*1、09*****234);香港、韓國區回傳原文。

狀態對照表

以下對照表供各事件共用。

出貨狀態

適用於 shipment_and_logistics 的 status(出貨單狀態)與 logistics[].logistics_status(該箱物流狀態)。

status 說明
order_created 訂單建立
assigned_picking 指派揀貨
picked 揀貨完成
picking_checked 揀貨驗收完成
shipment 已出貨
closed 到貨結案

入倉單狀態

適用於 pickup_main_update 的 status_code。

status_code 說明
0 等待入倉,預約已成立、貨物尚未抵達
1 貨物已抵達倉庫,尚未完成入倉作業
2 入倉完畢

入倉品項狀態

適用於 pickup_item_update 的 status。正常流程為 padding → padding_qc → machining → assign_position → stored。

status 說明
padding 等待入倉作業
padding_qc 品質檢驗中
machining 加工中
assign_position 指派庫位中
stored 入倉程序完成,庫存已可用
lack 商品短缺

逆物流狀態

適用於 reverse_create / reverse_update 的 status。

status.id 說明
1 申請逆物流
2 等待指派逆物流商
3 逆物流取貨運送中
4 物件已到倉
5 逆物流結案
6 逆物流異常等待排除
7 取消逆物流

status 為物件,包含 id、label(英文代碼)、description(中文說明)三個欄位。

逆物流品項狀態

適用於 reverse_goods[].status。

status 說明
1 等待回倉
2 已回倉
3 已取消

入倉送貨方式

適用於 pickup_main_update 的 logistics_code。

logistics_code 說明
own-self 自送／供應商直送
boxful BOXFUL 派車
processing_in_warehouse 在倉加工

出入倉模式

適用於 retrieve_type、retrieving_type、expected_entering_type、actual_entering_type。

值 說明
piece_out 件出
item_out 箱出
pallet_out 棧板出
bundle_out 組合商品

入倉事件 pickup

EventType
pickup
Event Description Response Format Ref.
main_update 入倉單(PL)更新 pickup_main_update
item_update 入倉品項狀態更新 pickup_item_update

pickup_main_update 欄位說明

pickup_main_update 回傳範例

{
  "timestamp": 1608726033,
  "region": "tw",
  "event_type": "pickup",
  "event": "main_update",
  "payload": {
    "packing_order_id": "TWI1601283742",
    "name": "OwenShih",
    "phone": "0800050777",
    "address": "台北市松山區光復北路11巷44號11樓",
    "email": "owen@boxful.com.tw",
    "logistics_date": "2020-12-20",
    "logistics_time_slot": "1100-1200",
    "logistics_code": "own-self",
    "logistics_label": "自行出貨",
    "is_container": 0,
    "is_custom": 0,
    "status_code": 1,
    "status_label": "Packing已抵達倉庫"
  },
  "validator_code": "9455f62917ba803bdafa4ddd3112d90a0360729"
}
欄位 型別 說明
packing_order_id string 入倉單號,格式為 區碼 + I + 10 碼,例:TWI1601283742
name string 送貨聯絡人
phone string 送貨聯絡電話
address string 送貨地址
email string 聯絡信箱
logistics_date string 預約入倉日期
logistics_time_slot string 預約入倉時段
logistics_code string 送貨方式代碼,見 入倉送貨方式 對照表
logistics_label string 送貨方式名稱
is_container int 是否需拆櫃,1 是 / 0 否
is_custom int 是否由海關入倉,1 是 / 0 否
status_code int 入倉單狀態,見 入倉單狀態 對照表
status_label string 狀態名稱

pickup_item_update 欄位說明

pickup_item_update 回傳範例

{
  "timestamp": 1612346367,
  "region": "tw",
  "event_type": "pickup",
  "event": "item_update",
  "payload": {
    "id": 48897,
    "label": "Demo product",
    "description": null,
    "sku": "A001(132777)",
    "barcode": "4711769132777",
    "expiry_date": null,
    "status": "machining",
    "status_description": "加工中",
    "logistics_date": "2021-02-03",
    "packing_order_id": "TWI1616676633",
    "out_bound_total_count": 200,
    "receive": [
      {
        "expected_entering_type": "item_out",
        "expected_entering_type_label": "箱出",
        "expected_entering_count": 10,
        "actual_entering_type": "item_out",
        "actual_entering_type_label": "箱出",
        "actual_entering_count": 10,
        "receive_detail": [
          {
            "count": 10,
            "unit_count": 20,
            "total_count": 200,
            "is_defective": 0
          }
        ]
      }
    ]
  },
  "validator_code": "b3fe1376718eb05e1a0b21e2ec412712"
}
欄位 型別 說明
id int 入倉品項流水號
label string 商品名稱
description string 商品描述
sku string 商品 SKU
barcode string 商品條碼
expiry_date string 效期
status string 品項狀態,見 入倉品項狀態 對照表
status_description string 狀態說明
logistics_date string 所屬入倉單的預約入倉日期
packing_order_id string 所屬入倉單號
out_bound_total_count int 品項實際入倉總數量
receive array 收貨明細,依入倉模式分組
receive[].expected_entering_type string 預約入倉模式,見 出入倉模式 對照表
receive[].expected_entering_type_label string 預約入倉模式名稱
receive[].expected_entering_count int 預約數量
receive[].actual_entering_type string 實際入倉模式
receive[].actual_entering_type_label string 實際入倉模式名稱
receive[].actual_entering_count int 實際數量
receive[].receive_detail array 收貨明細
receive[].receive_detail[].count int 箱數／件數
receive[].receive_detail[].unit_count int 每單位內含數量
receive[].receive_detail[].total_count int 小計,count × unit_count
receive[].receive_detail[].is_defective int 是否為不良品,1 是 / 0 否

庫存事件 inventory

EventType
inventory
Event Description Response Format Ref.
low_warning 當商品抵達庫存水位預警時通知每日一次 inventory_low_warning

inventory_low_warning 欄位說明

inventory_low_warning 回傳範例

{
  "timestamp": 1612410721,
  "region": "tw",
  "event_type": "inventory",
  "event": "low_warning",
  "payload": {
    "label": "demo001",
    "barcode": "15893383605698102",
    "sku": "demo001",
    "safety_stock": 99999999,
    "retrieving_type": "piece_out"
  },
  "validator_code": "546a8aa577c091eb53017b46f95d8a5be5cb310c8"
}
欄位 型別 說明
label string 商品名稱
barcode string 商品條碼
sku string 商品 SKU
safety_stock int 安全庫存水位
retrieving_type string 出倉模式,見 出入倉模式 對照表

物流事件 logistics

EventType
logistics
Event Description Response Format Ref.
create 出貨物流單建立時觸發 shipment_and_logistics
update 物流商、物流狀態、發車時間、物流追蹤碼其中一項異動時觸發 shipment_and_logistics

shipment_and_logistics 欄位說明

shipment_and_logistics 回傳範例

{
  "timestamp": 1344544545,
  "region": "tw",
  "event_type": "logistics",
  "event": "update",
  "payload": {
    "logistics_date": "2019-07-29",
    "address": "台北市*****11樓",
    "name": "王*明",
    "phone": "09*****678",
    "instruction": "付單",
    "2b_schedule_id": "1496",
    "collect_amount": 0,
    "vendor_order_id": "7142",
    "wms_order_id": "15641381475151991034",
    "status": "closed",
    "logistics": [
      {
        "logistics_vendor": "Boxful跨境配",
        "logistics": "boxful_corss",
        "logistics_status": "shipment",
        "service_at": "2019-07-28 12:00:00",
        "logistics_status_label": "已出貨",
        "logistics_code": "xdJ5jc",
        "tracking_url": "https://t.boxful.tw/1TDPGE"
      }
    ]
  },
  "validator_code": "92a2124ba634da84fb343514cc78cebfc8"
}
欄位 型別 說明
logistics_date string 預計出貨日期
name string 收件人姓名
phone string 收件人電話
address string 收件地址
instruction string 出貨備註
2b_schedule_id string OMS ORDER ID
collect_amount int 代收金額,0 表示非代收
vendor_order_id string 廠商自訂訂單編號
wms_order_id string WMS 出貨單號
status string 出貨單狀態,見 出貨狀態 對照表
logistics array 包裹清單,一箱一筆
logistics[].logistics string 物流商代碼
logistics[].logistics_vendor string 物流商名稱
logistics[].logistics_status string 包裹狀態,見 出貨狀態 對照表
logistics[].logistics_status_label string 包裹狀態說明
logistics[].logistics_code string 物流追蹤碼
logistics[].service_at string 物流商發車／收件時間
logistics[].tracking_url string 貨態查詢網址

逆物流事件 reverse

EventType
reverse
Event Description Response Format Ref.
create 逆物流單建立時觸發 reverse_create
update 逆物流單資料異動時觸發 reverse_update

reverse_create / reverse_update 欄位說明

reverse_create 回傳範例

{
  "timestamp": 1784191910,
  "region": "tw",
  "event_type": "reverse",
  "event": "create",
  "payload": {
    "reverse_order_id": "TWR1795402890",
    "name": "測*1",
    "phone": "09*****234",
    "address": "嘉義市 嘉義*****站",
    "logistics_date": "2026-07-16",
    "closed_at": null,
    "instruction": "商品瑕疵",
    "back_and_forth": 0,
    "created_at": "2026-07-16 10:37:41",
    "status": {
      "id": 1,
      "label": "application",
      "description": "申請逆物流"
    },
    "shipment": {
      "wms_order_id": "DEMOO_0014976209",
      "vendor_order_id": "0014976209",
      "2b_schedule_id": "7843991",
      "order_source_id": "0014976209"
    },
    "logistics": {
      "logistics": "hct",
      "description": "新竹物流(常溫)",
      "tracking_number": "FAKE_LOGISTICS_CODE",
      "packing_number": 1
    },
    "reverse_goods": [
      {
        "id": 232580,
        "expected_count": 1,
        "real_count": 0,
        "normal_count": 0,
        "abnormal_count": 0,
        "status": 1,
        "barcode": "DEMO_BARCODE_253342",
        "sku": "DEMO_SKU_253342",
        "label": "DEMO_253342號_商品",
        "expiry_date": "",
        "retrieve_type": "piece_out"
      }
    ]
  },
  "validator_code": "595d85906823b19628519f8e2cd738467efb17cbcbd7bcf3833d4cd9cc52b6af"
}

reverse_update 回傳範例

{
  "timestamp": 1784192530,
  "region": "tw",
  "event_type": "reverse",
  "event": "update",
  "payload": {
    "reverse_order_id": "TWR1795402890",
    "name": "測*1",
    "phone": "09*****234",
    "address": "嘉義市 嘉義*****站",
    "logistics_date": "2026-07-16",
    "closed_at": "2026-07-18 15:02:11",
    "instruction": "商品瑕疵",
    "back_and_forth": 0,
    "created_at": "2026-07-16 10:37:41",
    "status": {
      "id": 5,
      "label": "closed",
      "description": "逆物流結案"
    },
    "shipment": {
      "wms_order_id": "DEMOO_0014976209",
      "vendor_order_id": "0014976209",
      "2b_schedule_id": "7843991",
      "order_source_id": "0014976209"
    },
    "logistics": {
      "logistics": "hct",
      "description": "新竹物流(常溫)",
      "tracking_number": "FAKE_LOGISTICS_CODE",
      "packing_number": 1
    },
    "reverse_goods": [
      {
        "id": 232580,
        "expected_count": 1,
        "real_count": 1,
        "normal_count": 1,
        "abnormal_count": 0,
        "status": 2,
        "barcode": "DEMO_BARCODE_253342",
        "sku": "DEMO_SKU_253342",
        "label": "DEMO_253342號_商品",
        "expiry_date": "",
        "retrieve_type": "piece_out"
      }
    ]
  },
  "validator_code": "595d85906823b19628519f8e2cd738467efb17cbcbd7bcf3833d4cd9cc52b6af"
}
欄位 型別 說明
reverse_order_id string 逆物流單號,格式為 區碼 + R + 10 碼,例:TWR1795402890
name string 取件聯絡人
phone string 取件聯絡電話
address string 取件地址
logistics_date string 預計回收日期
closed_at string 結案時間
instruction string 逆物流原因／備註
back_and_forth int 是否為來回件,1 是 / 0 否
created_at string 建立時間
status object 逆物流狀態,見 逆物流狀態 對照表
shipment.wms_order_id string 原出貨單的 WMS 出貨單號
shipment.vendor_order_id string 原出貨單的廠商自訂訂單編號
shipment.2b_schedule_id string 原出貨單的 OMS ORDER ID
shipment.order_source_id string 原出貨單的來源平台訂單編號
logistics.logistics string 逆物流商代碼
logistics.description string 逆物流商名稱
logistics.tracking_number string 逆物流追蹤碼
logistics.packing_number int 件數
reverse_goods array 逆物流品項清單
reverse_goods[].id int 逆物流品項流水號
reverse_goods[].expected_count int 預計退回數量
reverse_goods[].real_count int 實際回倉數量
reverse_goods[].normal_count int 正常品數量
reverse_goods[].abnormal_count int 異常品數量
reverse_goods[].status int 品項狀態,見 逆物流品項狀態 對照表
reverse_goods[].barcode string 商品條碼
reverse_goods[].sku string 商品 SKU
reverse_goods[].label string 商品名稱
reverse_goods[].expiry_date string 效期
reverse_goods[].retrieve_type string 原出倉模式,見 出入倉模式 對照表

Example responses

200 Response

Responses

Status Meaning Description Schema
200 OK successful operation Inline

Response Schema

Status Code 200

empty object

Name Type Required Restrictions Description
json