API สำหรับผู้ค้า: เชื่อม SKU การแจ้งสินค้าสั่งซื้อล่วงหน้า และสต็อกคลังเซินเจิ้นเข้ากับระบบของคุณ

สิ่งที่ทำได้ในตอนนี้

• สร้างหรืออัปเดต SKU แบบกลุ่ม (อ้างอิง seller_sku ของคุณ) โดยแต่ละสีและไซซ์มีบาร์โค้ดสินค้าแยกกัน และผูกกับรหัสตัวเลือกสินค้าบน Shopee / Coupang / momo
• ตรวจสอบข้อกำหนดการนำเข้าอัตโนมัติตามพิกัดศุลกากรไต้หวัน 11 หลัก และระบุสินค้าที่ต้องผ่านการตรวจสอบ ต้องมีใบอนุญาต หรือห้ามนำเข้า
• แจ้งเลขพัสดุและรายการสินค้าในแต่ละกล่องล่วงหน้าเมื่อสั่งซื้อ เมื่อสินค้าถึงคลังเซินเจิ้น ระบบจะเปิดใบงานติดบาร์โค้ด WO-SK อัตโนมัติ และคลังจะติดบาร์โค้ดและสแกนขึ้นชั้นวางทีละชิ้น
• ค้นหาสต็อกแยกตามคลังและประวัติความเคลื่อนไหวของสต็อก และรับการแจ้งเตือนผ่าน webhook แบบเรียลไทม์เมื่อสินค้าถึงคลัง รับเข้าคลังเสร็จ มีส่วนต่างของจำนวน หรือสต็อกเปลี่ยนแปลง

ขั้นตอนการรับเข้าคลัง

1. สร้าง SKU: ส่งบาร์โค้ดสินค้า ตัวเลือกสินค้า ชื่อสินค้าที่สำแดง และพิกัดศุลกากร
2. แจ้งรับเข้าคลังล่วงหน้า: ส่งเลขพัสดุและจำนวนที่แจ้งของแต่ละ SKU
3. เข้าคลังเซินเจิ้น: เมื่อสแกนเลขพัสดุ ระบบจะเปิดใบงาน WO-SK และพิมพ์ออกมาอัตโนมัติ
4. ติดบาร์โค้ดและขึ้นชั้นวาง: คลังพิมพ์บาร์โค้ดสินค้า ติดทีละชิ้น และสแกนนับจำนวน
5. รับเข้าคลังเสร็จสิ้น: จำนวนที่รับจริงเข้าสู่สต็อกคลังเซินเจิ้น สินค้าชำรุดนับแยก และแจ้งส่วนต่างไปยังระบบของคุณ

ฟีเจอร์ที่อยู่ระหว่างวางแผน

คำสั่งจัดส่งสินค้าแบบกลุ่ม ชุดการจัดส่งที่จัดกลุ่มอัตโนมัติตามข้อกำหนดการสำแดง รวมถึงสต็อกที่เตรียมไว้ล่วงหน้า การคัดแยก และใบปะหน้าพัสดุของแพลตฟอร์มที่คลังเถาหยวน จะประกาศในหน้านี้เมื่อเปิดใช้งาน

ขั้นตอนการเปิดใช้งาน

1. ที่ศูนย์สมาชิก ให้เพิ่มผู้สำแดงประเภท “บริษัท” และกรอกเลขประจำตัวผู้เสียภาษี 8 หลัก
2. ติดต่อฝ่ายบริการลูกค้าของ HowBridge เพื่อขอเปิดใช้ API สำหรับผู้ค้า เมื่อผ่านการพิจารณาแล้วจะได้รับคีย์
3. คีย์จะแสดงเพียงครั้งเดียว โปรดเก็บไว้ใน environment variable ฝั่งเซิร์ฟเวอร์ และห้ามใส่ไว้ในเบราว์เซอร์หรือแอป
4. หากต้องการใช้ webhook ให้ตั้งค่าและยืนยัน URL ในหน้า API ของศูนย์สมาชิกก่อน จากนั้นจึงสมัครรับอีเวนต์ของผู้ค้า

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 แทนการ polling

Idempotency (Idempotency-Key)

คำขอที่เขียนข้อมูลสามารถส่ง header Idempotency-Key ได้ (8–128 ตัวอักษร ประกอบด้วยตัวอักษรภาษาอังกฤษ ตัวเลข และ _-:.) เมื่อเครือข่ายหมดเวลา ให้ส่งซ้ำด้วย key เดิมและเนื้อหาเดิม จะได้รับการตอบกลับของครั้งแรกพร้อม header Idempotent-Replayed: true หากใช้ key เดิมแต่เนื้อหาต่างไปจะตอบกลับ 422 ระบบเก็บบันทึกไว้ 24 ชั่วโมง

การตอบกลับแบบกลุ่ม

endpoint แบบกลุ่มรายงานผลทีละรายการ: สำเร็จทั้งหมดตอบกลับ 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

ตอบกลับเป็นไฟล์ PDF ฉลากขนาด 40×30mm โดย qty คือจำนวนแผ่น (1–1000) คลังเซินเจิ้นใช้ฉลากแบบเดียวกันเมื่อติดบาร์โค้ด endpoint นี้มีไว้สำหรับกรณีที่คุณต้องการติดบาร์โค้ดเองก่อนจัดส่ง

สร้างใบรับเข้าคลัง

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 ของศูนย์สมาชิกเพื่อตั้งค่า URL ของ webhook (รับเฉพาะ https) และยืนยันความเป็นเจ้าของให้เสร็จ: endpoint ของคุณต้องตอบกลับ HTTP 200 โดย body เป็น {"challenge": "ค่าที่ได้รับ"}
2. เรียก PUT /api/v1/merchant/webhook/events เพื่อสมัครรับอีเวนต์ของผู้ค้า การเปลี่ยน URL ในศูนย์สมาชิกภายหลังจะไม่ล้างการสมัครรับอีเวนต์ของผู้ค้า

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 ของคุณคำนวณ HMAC-SHA256 จาก “ประทับเวลา + . + body ดิบ” แล้วเปรียบเทียบกับ v1 และปฏิเสธประทับเวลาที่เก่ากว่า 5 นาที เมื่อส่งอีเวนต์เดิมซ้ำ delivery_id จะไม่เปลี่ยน จึงใช้ตัดรายการซ้ำได้

หากการตอบกลับไม่ใช่ 2xx ระบบจะลองส่งใหม่หลังจาก 1 นาที, 5 นาที, 30 นาที, 2 ชั่วโมง และ 6 ชั่วโมง หากล้มเหลวติดต่อกัน 20 ครั้ง webhook จะถูกปิดใช้งานอัตโนมัติ และต้องตั้งค่าใหม่ที่ศูนย์สมาชิก

// 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 ระยะที่ 1 (2026-09-17): SKU สินค้า การแจ้งรับเข้าคลังล่วงหน้า การติดบาร์โค้ดและขึ้นชั้นวางที่คลังเซินเจิ้น การค้นหาสต็อก webhook