商家 API：把 SKU、採購預報與深圳倉庫存接進你的系統

目前可以做的事

• 批量建立或更新 SKU（以你的 seller_sku 為準），每個顏色、尺碼各自一組商品條碼，並綁定蝦皮／酷澎／momo 的商品規格編號。
• 依 11 碼稅則號列自動比對輸入規定，標出需要商品檢驗、許可或不能進口的商品。
• 採購時預報快遞單號與每箱內容物；貨到深圳倉自動開 WO-SK 貼碼工單，倉庫逐件貼碼、掃描上架。
• 查詢分倉庫存與庫存流水，並用 webhook 即時收到到倉、入庫完成、數量差異與庫存變動。

入庫流程

1. 建立 SKU：傳入商品條碼、規格、申報品名、稅則號列。
2. 預報入庫：傳入快遞單號與每個 SKU 的預報數量。
3. 深圳倉入倉：掃快遞單號後自動開 WO-SK 工單並列印。
4. 貼碼上架：倉庫列印商品條碼、逐件貼上並掃描計數。
5. 完成入庫：實收進入深圳倉庫存，破損另計，差異通知你的系統。

規劃中的功能

批量出貨訂單、依申報規定自動歸組的出貨批次，以及桃園倉前置庫存、分揀與平台面單。上線時會在本頁公布。

開通步驟

1. 在會員中心新增「公司」申報人，填寫 8 碼統一編號。
2. 聯繫好運器客服申請開通商家 API，審核通過後會核發金鑰。
3. 金鑰只會顯示一次，請保存在伺服器端的環境變數，不要放進瀏覽器或 App。
4. 需要 webhook 時，先到會員中心的 API 頁面設定並驗證網址，再訂閱商家事件。

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Base URL

格式與語言

請求與回應都是 JSON。錯誤訊息預設為繁體中文，帶 Accept-Language: en 回英文；程式判斷請一律使用固定英文的 error.code。

回應結構

成功回 {"success": true, "data": …, "meta": …}；失敗回 {"success": false, "error": {"code", "message", "errors", "context"}}，errors 是逐欄明細。唯一例外是沒帶或帶了無效金鑰：HTTP 401，body 為 {"message": "Unauthenticated."}。

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

限流

每把金鑰每分鐘 60 次、每日 5,000 次（高用量方案每分鐘 300 次、每日 50,000 次），批量端點一次算一次。需要即時資料請訂閱 webhook，不要輪詢。

冪等（Idempotency-Key）

寫入請求可帶 Idempotency-Key 標頭（8–128 字元，英數與 _-:.）。網路逾時後用同一把 key、同一份內容重送，會拿到第一次的回應，標頭 Idempotent-Replayed: true；同一把 key 換了內容回 422。紀錄保留 24 小時。

批量回應

批量端點逐筆回報結果：全部成功回 200、部分失敗回 207、全部失敗回 422。每一筆都有 index、status（created／updated／failed）與失敗原因。

識別碼字元

seller_sku 只能用英數與 ._-（1–64 字元）；商品條碼另可用 / 與 +（3–64 字元）。大小寫視為相同。

批量建立或更新 SKU

POST/api/v1/merchant/skus/batch

一次最多 200 筆，每一筆獨立處理，一筆失敗不影響其他筆。

請求範例 (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

回應 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

輸入規定判定（regulation.status）

查詢 SKU

GET/api/v1/merchant/skus

可用 seller_sku、barcode、regulation_status、updated_since（ISO 8601）篩選，page／per_page（最多 100）分頁。

單一 SKU

GET/api/v1/merchant/skus/{seller_sku}

更新平台商品對應

PUT/api/v1/merchant/skus/{seller_sku}/channels

以傳入的清單整批取代原本的對應；同一組平台規格不能同時綁兩個 SKU。

下載商品條碼標籤

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

回傳 40×30mm 標籤 PDF，qty 為張數（1–1000）。深圳倉貼碼時印的是同一種標籤；這支供你想在出貨前自行貼碼時使用。

建立入庫單

POST/api/v1/merchant/inbound-orders

整張驗證：任一錯誤都不會建立。同一個快遞單號同時只能屬於一張進行中的入庫單；同一個包裹內重複的 SKU 會合併數量。

請求範例 (POST JSON)

curl -X POST https://0523.tw/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

入庫單狀態

包裹狀態

查詢入庫單

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

可用 status、reference_no、updated_since 篩選。每個包裹會回傳預報、實收、破損數量與差異。

取消入庫單

POST/api/v1/merchant/inbound-orders/{id}/cancel

只有包裹都還沒到倉時可以取消；取消後快遞單號可以重新預報。

查詢庫存

GET/api/v1/merchant/inventory?warehouse_code=SZ

可用 warehouse_code 與 seller_sku[]（最多 200 個）篩選。

回應 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

庫存流水

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

只增不改的異動紀錄，用 after_id 游標往後翻頁（每次最多 500 筆），記住回應的 meta.next_after_id 即可續抓對帳。

設定方式

1. 到會員中心 API 頁面設定 webhook 網址（僅接受 https），完成擁有權驗證：你的端點要回 HTTP 200，body 為 {"challenge": "收到的值"}。
2. 呼叫 PUT /api/v1/merchant/webhook/events 訂閱商家事件。之後在會員中心改網址不會清掉商家事件的訂閱。

curl -X PUT https://0523.tw/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

事件清單

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

驗證簽章

每次推送都帶 X-Lucky-Event、X-Lucky-Delivery-Id 與 X-Lucky-Signature: t=時間戳,v1=簽章。以你的 webhook secret 對「時間戳 + . + 原始 body」做 HMAC-SHA256，比對 v1，並拒絕超過 5 分鐘的時間戳。同一事件重試時 delivery_id 不變，可用來去重。

回應非 2xx 會在 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時後重試；連續失敗 20 次會自動停用，需到會員中心重新設定。

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

LINE 官方帳號 @0523tw

技術信箱 howyunqisoftware@gmail.com

版本 v1 第一期（2026-09-17）：商品 SKU、入庫預報、深圳倉貼碼上架、庫存查詢、webhook。