शिपमेंट स्थिति क्वेरी एपीआई विकास दस्तावेज़

पैकेज यात्रा

एपीआई स्वचालित रूप से ऑर्डर संख्या के आधार पर यह निर्धारित करेगा कि पैकेज किस चरण में है, और वर्तमान स्थिति, पूर्ण समयरेखा, और (यदि यह ताइवान सीमा शुल्क में प्रवेश कर चुका है) जीसी329 पांच-चरण सीमा शुल्क निकासी प्रगति लौटाएगा।

Base URL

प्रमाणीकरण शीर्षलेख (एक चुनें)

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

कृपया इसे सर्वर साइड से कॉल करें और कुंजी को फ्रंट-एंड जावास्क्रिप्ट में न रखें। दर सीमा प्रमुख इकाइयों में है, और प्रतिक्रिया शीर्षलेख X-RateLimit-Remaining शेष सीमा की रिपोर्ट करेगा; यदि सीमा पार हो जाती है, तो HTTP 429 वापस कर दिया जाएगा।

GETPOST /api/v1/shipment/track

ट्रैकिंग नंबर के आधार पर एकल पैकेज की शिपमेंट स्थिति की जाँच करें। GET (क्वेरी स्ट्रिंग) और POST (JSON/फॉर्म) दोनों स्वीकार्य हैं।

पैरामीटर का अनुरोध करें

पैरामीटर	प्रकार	आवश्यक	उदाहरण देकर स्पष्ट करना
tracking_number	string	आवश्यक	पैकेज ट्रैकिंग नंबर (4-64 अक्षर, अक्षरांकीय और - _)। चाइना एक्सप्रेस ट्रैकिंग नंबर/ग्राहक ट्रैकिंग नंबर/शिपिंग ट्रैकिंग नंबर सभी स्वीकार्य हैं।

उदाहरण का अनुरोध करें (प्राप्त करें)

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

मैदान	प्रकार	उदाहरण देकर स्पष्ट करना
status	string	वर्तमान स्थिति (मानव पठनीय) , जैसे पूर्वानुमानित / गोदाम में / पारगमन में / ताइवान को भेजा गया / रसीद के लिए हस्ताक्षरित। इस स्ट्रिंग को सीधे प्रदर्शित करने की अनुशंसा की जाती है।
status_code	number	स्थिति कोड (स्रोत पर निर्भर करता है, अगला भाग देखें)। यूआई को चलाने के लिए status, is_delivered, is_final का उपयोग करने की अनुशंसा की जाती है।
is_delivered	bool	क्या इस पर हस्ताक्षर किये गये हैं?
is_final	bool	क्या यह अंतिम है (हस्ताक्षरित/लौटाया गया/रद्द किया गया/सुपुर्दगी योग्य नहीं)। मतदान रोकने की बात सही है.
logistics	string	रसद प्रदाता (चाइना एक्सप्रेस या ताइवान टर्मिनल डिलीवरी)।
description	string	नवीनतम घटना विवरण.
last_event_time	datetime	नवीनतम लॉजिस्टिक इवेंट का समय.
timeline	array	स्टेज टाइमलाइन, प्रत्येक आइटम में name / completed / time / description शामिल है।
customs_stages	object|null	ताइवान सीमा शुल्क GC329 सीमा शुल्क निकासी प्रगति (यदि सीमा शुल्क निकासी अभी तक पूरी नहीं हुई है तो शून्य)। अगला भाग देखें.
events	array|null	मूल लॉजिस्टिक्स घटना इतिहास (टर्मिनल डिलीवरी ट्रैकिंग के दौरान प्रदान किया गया)।

समेकन का मुख्य चरण (समयरेखा)

अवस्था	महत्व
पूर्वानुमानित (गोदाम में प्रवेश नहीं किया गया)	ग्राहक ने ऑर्डर संख्या की भविष्यवाणी की है, लेकिन पैकेज अभी तक शेन्ज़ेन कंसोलिडेशन वेयरहाउस में नहीं पहुंचा है।
पहले से ही गोदाम (शेन्ज़ेन कंटेनर गोदाम)	शेन्ज़ेन कंसोलिडेशन वेयरहाउस को पैकेज प्राप्त हुआ है।
समेकन और पैकेजिंग/ताइवान डिलीवरी	पैक किया गया और भेजा गया, समुद्र/हवाई मार्ग से ताइवान भेजा गया।
ताइवान में पारगमन/वितरण में	ताइवान पहुंचने के बाद सीमा शुल्क निकासी और अंतिम डिलीवरी।
के लिए हस्ताक्षर किये गये	प्राप्तकर्ता ने डिलीवरी के लिए हस्ताक्षर किए हैं (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"
}

HTTP	error	उदाहरण देकर स्पष्ट करना
401	missing_api_key / invalid_api_key	नहीं/अमान्य एपीआई कुंजी।
403	insufficient_scope	कुंजी को shipment:read अनुमति नहीं दी गई है।
404	not_found	यह ट्रैकिंग नंबर नहीं मिला है, या पैकेज ने अभी तक समेकन प्रणाली में प्रवेश नहीं किया है।
422	validation_failed	ट्रैकिंग_नंबर गुम है या प्रारूप से मेल नहीं खाता है।
429	rate_limit_exceeded	प्रति मिनट अनुरोध सीमा से अधिक होने पर पुनः प्रयास करें देखें।

• मतदान आवृत्ति : हर 15-30 मिनट में एक ही ऑर्डर नंबर की जांच करने की सिफारिश की जाती है; परिणाम इस सर्वर पर 5 मिनट के लिए कैश किया जाता है (cached: true का अर्थ है हिट)।
• मतदान बंद कर देता है : is_final = true (हस्ताक्षरित/लौटा/रद्द) होने पर मतदान रोकें।
• स्टेटस ड्राइवर : status स्ट्रिंग के साथ डिस्प्ले, हार्ड कोडिंग से बचने के लिए प्रक्रिया का मूल्यांकन करने के लिए is_delivered / is_final का उपयोग करें status_code (अलग-अलग स्रोत कोड परिभाषाएं अलग-अलग हैं)।
• कोई ऑर्डर संख्या नहीं :404 सबसे अधिक संभावना यह है कि पैकेज ने अभी तक समेकन प्रणाली में प्रवेश नहीं किया है (ग्राहक ने अभी ऑर्डर दिया है लेकिन इसे भेजा नहीं है), और आप बाद में फिर से प्रयास कर सकते हैं।

तकनीकी समर्थन: howyunqisoftware@gmail.com

एपीआई संस्करण: v1 (स्थिर).

इतिहास बदलें: 2026-06-01 — शिपमेंट स्थिति क्वेरी एपीआई v1 ऑनलाइन है।