ตลาดบริการ / เอกสารการพัฒนา API การสืบค้นสถานะการจัดส่ง

API การติดตามพัสดุแบบรวม · v1

เอกสารการพัฒนา API การสืบค้นสถานะการจัดส่ง

ตรวจสอบสถานะการจัดส่งที่สมบูรณ์ของพัสดุรวมได้ทันทีตามหมายเลขติดตาม: จาก China Express Collection, คลังสินค้าเซินเจิ้น Consolidation Warehouse, การจัดส่งในไต้หวัน, ไปจนถึงขั้นตอนการผ่านพิธีการศุลกากรของไต้หวัน (GC329) และลายเซ็นการส่งมอบที่สถานีปลายทาง ข้อมูลเดียวกันกับเว็บไซต์อย่างเป็นทางการของ HowBridge ซึ่งออกแบบมาเป็นพิเศษสำหรับเชื่อมต่อกับแพลตฟอร์มอีคอมเมิร์ซข้ามพรมแดน เช่น 0337.tw

สอบถามหมายเลขคำสั่งซื้อ

หมายเลขติดตาม China Express/ลูกค้า/ผู้ให้บริการ

ไทม์ไลน์แบบเต็ม

รวบรวม → คลังสินค้า → จัดส่ง → ลงชื่อเพื่อรับ

GC329

ขั้นตอนการดำเนินพิธีการศุลกากรไต้หวัน

ไม่มีข้อมูลส่วนบุคคล

ส่งคืนเฉพาะสถานะโดยไม่มีข้อมูลผู้รับ

1 ภาพรวม

ให้แพลตฟอร์มของคุณใช้หมายเลขติดตามเพื่อค้นหา "ตอนนี้อยู่ที่ไหน" ของแพ็คเกจรวม

การเดินทางแบบแพ็คเกจ

จีนเข้ายึดครอง→ คลังสินค้าคลังสินค้าคอนเทนเนอร์เซินเจิ้น→ การขนส่งรวมและบรรจุภัณฑ์/การจัดส่งในไต้หวัน→ พิธีการศุลกากรไต้หวัน (GC329)→ การส่งมอบเทอร์มินัล / ลงนามสำหรับ

API จะกำหนดโดยอัตโนมัติว่าพัสดุอยู่ในขั้นตอนใดตามหมายเลขคำสั่งซื้อ และส่งคืนสถานะปัจจุบัน ลำดับเวลาที่สมบูรณ์ และ (หากเข้าสู่ศุลกากรไต้หวันแล้ว) ความคืบหน้าในการดำเนินพิธีการศุลกากรห้าขั้นตอน GC329

สามารถใช้หมายเลขติดตาม : ได้ หมายเลขติดตามพัสดุด่วนของจีน (หมายเลขติดตามที่ลูกค้าใช้เพื่อส่งไปยังคลังสินค้าคอนเทนเนอร์ที่เซินเจิ้น) หมายเลขคำสั่งซื้อของลูกค้า หรือหมายเลขติดตามของผู้ให้บริการขนส่ง ระบบจะเปรียบเทียบระหว่างแหล่งที่มาต่างๆ โดยอัตโนมัติ

การคุ้มครองความเป็นส่วนตัว: API นี้ค้นหาเฉพาะ "หมายเลขติดตามพัสดุเดียว" และข้อมูลที่ส่งคืน ไม่มีชื่อผู้รับ ที่อยู่ หมายเลขโทรศัพท์ และข้อมูลส่วนบุคคลอื่นๆ ของ นอกจากนี้ยังไม่อนุญาตให้แสดงรายการพัสดุของผู้อื่นเป็นชุดพร้อมหมายเลขใบตราส่งหลัก (B######)

2 การรับรองและข้อมูลพื้นฐาน

คำขอทั้งหมดจะต้องนำคีย์ API มาด้วย (คีย์เดียวกับ API ค่าธรรมเนียมการจัดส่งก็เพียงพอแล้ว และจำเป็นต้องเปิดใช้งานสิทธิ์ shipment:read)

Base URL

https://0523.tw/api/v1/shipment

ส่วนหัวการตรวจสอบสิทธิ์ (เลือกอย่างใดอย่างหนึ่ง)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

กรุณาเรียกจากฝั่งเซิร์ฟเวอร์และอย่าใส่รหัสใน JavaScript ส่วนหน้า ขีดจำกัดอัตราอยู่ในหน่วยคีย์ และส่วนหัวการตอบสนอง X-RateLimit-Remaining จะรายงานขีดจำกัดที่เหลือ หากเกินขีดจำกัด HTTP 429 จะถูกส่งกลับ

3 จุดสิ้นสุด: สอบถามสถานะสินค้า

GETPOST /api/v1/shipment/track

ตรวจสอบสถานะการจัดส่งของพัสดุชิ้นเดียวตามหมายเลขติดตาม ยอมรับทั้ง GET (สตริงการสืบค้น) และ POST (JSON / แบบฟอร์ม)

ขอพารามิเตอร์

พารามิเตอร์	พิมพ์	ที่จำเป็น	แสดงให้เห็น
`tracking_number`	string	ที่จำเป็น	หมายเลขติดตามพัสดุ (4–64 ตัวอักษร ตัวอักษรและตัวเลข และ `-` `_`) หมายเลขติดตาม China Express / หมายเลขติดตามลูกค้า / หมายเลขติดตามการจัดส่ง ล้วนเป็นที่ยอมรับ

ตัวอย่างคำขอ (GET)

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

ตอบกลับ 200 (ตัวอย่างอยู่ในคลังสินค้าแล้ว/อยู่ระหว่างการขนส่ง)

{
  "success": true,
  "cached": false,
  "tracking_number": "SF1234567890123",
  "data": {
    "tracking_number": "SF1234567890123",
    "customer_order_no": "LK260601001",
    "carrier_tracking_no": "SF1234567890123",
    "logistics": "順豐速運",
    "status_code": 2,
    "status": "已入倉",
    "description": "包裹已進入深圳集運倉,等待集運打包",
    "is_delivered": false,
    "is_final": false,
    "last_event_time": "2026-06-01 12:30:00",
    "updated_at": "2026-06-01 12:31:05",
    "timeline": [
      { "name": "已攬收", "completed": true,  "time": "2026-05-30 09:00:00" },
      { "name": "已入倉 (深圳集運倉)", "completed": true,  "time": "2026-06-01 12:30:00" },
      { "name": "集運打包/台灣運送", "completed": false, "time": null },
      { "name": "已簽收", "completed": false, "time": null }
    ],
    "customs_stages": null,
    "events": null
  }
}

การตอบสนอง 404 (ไม่พบหมายเลขคำสั่งซื้อ)

{
  "success": false,
  "error": "not_found",
  "message": "查無此單號。請確認單號正確,或包裹尚未進入集運系統。",
  "tracking_number": "SF1234567890123"
}

4 คำอธิบายฟิลด์การตอบกลับ (data)

สนาม	พิมพ์	แสดงให้เห็น
`status`	string	สถานะปัจจุบัน (มนุษย์สามารถอ่านได้) เช่น คาดการณ์ไว้ / เก็บในโกดัง / ระหว่างทาง / ส่งไปไต้หวัน / ลงนามรับแล้ว ขอแนะนำให้แสดงสตริงนี้โดยตรง
`status_code`	number	รหัสสถานะ (ขึ้นอยู่กับแหล่งที่มา ดูหัวข้อถัดไป) ขอแนะนำให้ใช้ `status`, `is_delivered`, `is_final` เพื่อขับเคลื่อน UI
`is_delivered`	bool	มีการลงนามเพื่อ?
`is_final`	bool	ไม่ว่าจะเป็นที่สิ้นสุด (ลงนาม / คืน / ยกเลิก / ไม่สามารถส่งมอบได้) จริงที่จะหยุดการเลือกตั้ง
`logistics`	string	ผู้ให้บริการโลจิสติกส์ (การจัดส่งเทอร์มินัลของ China Express หรือ Taiwan)
`description`	string	คำอธิบายเหตุการณ์ล่าสุด
`last_event_time`	datetime	ช่วงเวลาของงานโลจิสติกส์ล่าสุด
`timeline`	array	ไทม์ไลน์ของสเตจ แต่ละรายการประกอบด้วย `name` / `completed` / `time` / `description`
`customs_stages`	object\|null	ความคืบหน้าพิธีการศุลกากรของไต้หวัน GC329 (เป็นโมฆะหากพิธีการศุลกากรยังไม่เสร็จสิ้น) ดูหัวข้อถัดไป
`events`	array\|null	ประวัติเหตุการณ์ลอจิสติกส์ดั้งเดิม (ให้ไว้ระหว่างการติดตามการจัดส่งเทอร์มินัล)

5 สถานะและไทม์ไลน์

ขั้นตอนหลักของการขนส่งรวม (ไทม์ไลน์)

เวที	ความสำคัญ
คาดการณ์ (ไม่ได้เข้าคลังสินค้า)	ลูกค้าได้คาดการณ์หมายเลขคำสั่งซื้อแล้ว แต่พัสดุยังมาไม่ถึงที่คลังสินค้ารวมเซินเจิ้น
โกดังแล้ว (Shenzhen Container Warehouse)	คลังสินค้ารวมเซินเจิ้นได้รับพัสดุแล้ว
การขนส่งรวมและบรรจุภัณฑ์/การจัดส่งในไต้หวัน	บรรจุและจัดส่ง จัดส่งทางทะเล/ทางอากาศไปยังไต้หวัน
ระหว่างทาง/จัดส่งไปยังไต้หวัน	พิธีการศุลกากรและการส่งมอบขั้นสุดท้ายหลังจากมาถึงไต้หวัน
ลงนามเพื่อ	ผู้รับลงนามในการจัดส่งแล้ว (`is_delivered = true`)

ขั้นตอนการผ่านพิธีการศุลกากร (`customs_stages`,GC329)

หลังจากที่พัสดุเข้าสู่ศุลกากรไต้หวันแล้ว customs_stages จะนำความคืบหน้าห้าขั้นตอนและเปอร์เซ็นต์โดยรวมออกมา:

{
  "hbl": "691MK539819",
  "trans_type_name": "海運",
  "current_stage_name": "海關放行",
  "progress_percent": 80,
  "is_completed": false,
  "stages": [
    { "code": "XX", "name": "船(機)抵達",   "done": true },
    { "code": "E1", "name": "連線收單建檔", "done": true },
    { "code": "D1", "name": "計稅",        "done": true },
    { "code": "RL", "name": "海關放行",     "done": true },
    { "code": "OW", "name": "出倉",        "done": false }
  ],
  "source": "關港貿單一窗口 GC329"
}

6 รหัสข้อผิดพลาด

HTTP	`error`	แสดงให้เห็น
401	`missing_api_key` / `invalid_api_key`	ไม่มี/คีย์ API ไม่ถูกต้อง
403	`insufficient_scope`	คีย์ไม่ได้รับการอนุญาต `shipment:read`
404	`not_found`	ไม่พบหมายเลขติดตามนี้ หรือพัสดุยังไม่เข้าสู่ระบบการขนส่งรวม
422	`validation_failed`	Tracking_number หายไปหรือไม่ตรงกับรูปแบบ
429	`rate_limit_exceeded`	เกินขีดจำกัดคำขอต่อนาที โปรดดูที่ ลองใหม่หลังจาก

7 ตัวอย่างโปรแกรม

$client = new GuzzleHttp\Client(['base_uri' => 'https://0523.tw']);

$res = $client->get('/api/v1/shipment/track', [
    'headers' => ['Authorization' => 'Bearer ' . env('LUCKY_FREIGHT_KEY')],
    'query'   => ['tracking_number' => 'SF1234567890123'],
]);

$d = json_decode($res->getBody(), true)['data'];
echo $d['status'];  // 已入倉

const r = await fetch('https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123', {
  headers: { 'Authorization': `Bearer ${process.env.LUCKY_FREIGHT_KEY}` },
});
const { data } = await r.json();
console.log(data.status, data.is_delivered);

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY"

8 แนวทางปฏิบัติที่ดีที่สุด

ความถี่ในการโพล : ขอแนะนำให้ตรวจสอบหมายเลขคำสั่งซื้อเดียวกันทุกๆ 15-30 นาที ผลลัพธ์จะถูกแคชไว้บนเซิร์ฟเวอร์นี้เป็นเวลา 5 นาที (cached: true หมายถึง Hit)
หยุดการโพล : หยุดโพลเมื่อ is_final = true (ลงนาม/ส่งคืน/ยกเลิก)
ไดรเวอร์สถานะ : แสดงผลด้วยสตริง status ใช้ is_delivered / is_final เพื่อตัดสินกระบวนการเพื่อหลีกเลี่ยงการเข้ารหัสยาก status_code (คำจำกัดความของซอร์สโค้ดที่แตกต่างกันจะแตกต่างกัน)
ไม่มีหมายเลขคำสั่งซื้อ :404 เป็นไปได้มากว่าพัสดุยังไม่ได้เข้าสู่ระบบการขนส่งรวม (ลูกค้าเพิ่งสั่งซื้อแต่ยังไม่ได้ส่ง) และคุณสามารถลองอีกครั้งได้ในภายหลัง

9 การสนับสนุนและเวอร์ชัน

การสนับสนุนทางเทคนิค: howyunqisoftware@gmail.com

เวอร์ชันเอพีไอ: v1 (เสถียร)

ประวัติการเปลี่ยนแปลง: 01-06-2026 — การสืบค้นสถานะการจัดส่ง API v1 ออนไลน์อยู่

เอกสาร API การจัดส่ง สมัครคีย์ API