Tài liệu phát triển API truy vấn trạng thái lô hàng

hành trình trọn gói

API sẽ tự động xác định gói hàng đang ở giai đoạn nào dựa trên số đơn đặt hàng và trả về trạng thái hiện tại, dòng thời gian hoàn chỉnh và (nếu gói hàng đã được nhập vào Hải quan Đài Loan) tiến trình thông quan năm giai đoạn GC329.

Base URL

Tiêu đề xác thực (chọn một)

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

Vui lòng gọi nó từ phía máy chủ và không đặt khóa vào JavaScript ở giao diện người dùng. Giới hạn tốc độ được tính theo đơn vị chính và tiêu đề phản hồi X-RateLimit-Remaining sẽ báo cáo giới hạn còn lại; nếu vượt quá giới hạn, HTTP 429 sẽ được trả về.

GETPOST /api/v1/shipment/track

Kiểm tra trạng thái lô hàng của một gói hàng dựa trên số theo dõi. Cả GET (chuỗi truy vấn) và POST (JSON/form) đều được chấp nhận.

Thông số yêu cầu

tham số	Kiểu	Yêu cầu	minh họa
tracking_number	string	Yêu cầu	Số theo dõi gói hàng (4–64 ký tự, chữ và số và - _). Số theo dõi chuyển phát nhanh của Trung Quốc / Số theo dõi khách hàng / Số theo dõi vận chuyển đều được chấp nhận.

Ví dụ yêu cầu (GET)

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

Phản hồi 200 (Ví dụ đã có trong kho/đang vận chuyển)

{
  "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
  }
}

Phản hồi 404 (không tìm thấy số đơn hàng)

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

cánh đồng	Kiểu	minh họa
status	string	Trạng thái hiện tại (người có thể đọc được) , chẳng hạn như dự báo / lưu kho / đang vận chuyển / gửi đến Đài Loan / đã ký nhận. Nên hiển thị trực tiếp chuỗi này.
status_code	number	Mã trạng thái (tùy theo nguồn, xem phần tiếp theo). Bạn nên sử dụng status, is_delivered, is_final để điều khiển giao diện người dùng.
is_delivered	bool	Nó đã được ký kết chưa?
is_final	bool	Liệu nó có phải là bản cuối cùng hay không (đã ký/trả lại/hủy/không thể gửi được). Đúng là dừng bỏ phiếu.
logistics	string	Nhà cung cấp dịch vụ hậu cần (giao hàng tận nơi tại China Express hoặc Đài Loan).
description	string	Mô tả sự kiện mới nhất.
last_event_time	datetime	Thời điểm diễn ra sự kiện hậu cần mới nhất.
timeline	array	Dòng thời gian của giai đoạn, mỗi mục chứa name / completed / time / description.
customs_stages	object|null	Tiến độ thông quan GC329 của Hải quan Đài Loan (không có giá trị nếu chưa hoàn thành thủ tục hải quan). Xem phần tiếp theo.
events	array|null	Lịch sử sự kiện hậu cần ban đầu (được cung cấp trong quá trình theo dõi giao hàng tại thiết bị đầu cuối).

Giai đoạn hợp nhất chính (dòng thời gian)

sân khấu	ý nghĩa
Dự kiến ​​(chưa nhập kho)	Khách hàng đã dự đoán số đơn hàng nhưng gói hàng vẫn chưa đến Kho gom hàng Thâm Quyến.
Đã lưu kho (Kho container Thâm Quyến)	Kho hàng hợp nhất Thâm Quyến đã nhận được gói hàng.
Gom hàng và đóng gói/Giao hàng tại Đài Loan	Đóng gói và vận chuyển, vận chuyển bằng đường biển/đường hàng không đi Đài Loan.
Quá cảnh/giao hàng đi Đài Loan	Thông quan và giao hàng lần cuối sau khi đến Đài Loan.
Đã ký cho	Người nhận đã ký nhận hàng (is_delivered = true).

Các khâu thông quan (customs_stages,GC329)

Sau khi gói hàng đi vào Hải quan Đài Loan, customs_stages sẽ đưa ra tiến trình gồm 5 giai đoạn và tỷ lệ phần trăm tổng thể:

{
  "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"
}

HTTP	error	minh họa
401	missing_api_key / invalid_api_key	Không có/Khóa API không hợp lệ.
403	insufficient_scope	Khóa chưa được cấp quyền shipment:read.
404	not_found	Không tìm thấy số theo dõi này hoặc gói hàng chưa được đưa vào hệ thống hợp nhất.
422	validation_failed	số theo dõi bị thiếu hoặc không khớp với định dạng.
429	rate_limit_exceeded	Vượt quá giới hạn yêu cầu mỗi phút, hãy xem Thử lại sau.

• Tần suất bỏ phiếu : Nên kiểm tra cùng một số thứ tự sau mỗi 15-30 phút; kết quả được lưu vào bộ nhớ đệm trên máy chủ này trong 5 phút (cached: true có nghĩa là lần truy cập).
• dừng bỏ phiếu : Dừng bỏ phiếu khi is_final = true (đã ký/trả lại/hủy).
• Trình điều khiển trạng thái : Hiển thị với chuỗi status, sử dụng is_delivered / is_final để đánh giá quá trình nhằm tránh mã hóa cứng status_code (các định nghĩa mã nguồn khác nhau là khác nhau).
• Không có số đơn hàng :404 Rất có thể có nghĩa là gói hàng chưa vào hệ thống hợp nhất (khách hàng vừa đặt hàng nhưng chưa gửi) và bạn có thể thử lại sau.

hỗ trợ kỹ thuật: howyunqisoftware@gmail.com

Phiên bản API: v1 (ổn định).

Lịch sử thay đổi: 01/06/2026 — API truy vấn trạng thái lô hàng v1 đang trực tuyến.