iTrack.ing 物流查詢系統 API

服務流程

1. 註冊物流單號 呼叫 regLogisticsID，系統會驗證 API Key 並將單號加入待追蹤清單。

2. 背景更新貨態 排程程式會定期查詢物流商網站，更新 tracking_data、done 與 refund。

3. 查詢或接收通知 可主動呼叫 queryLogistics 查詢，也可在註冊時提供 notifyURL 接收狀態通知。

認證方式

所有 API 都需要提供 API Key。建議使用 Authorization: Bearer YOUR_API_KEY header；為了相容舊版串接，也仍支援 APIKEY query string。API Key 由系統管理者建立使用者時產生，系統會依使用者狀態與使用量限制判斷是否允許呼叫。

參數	位置	必填	說明
`Authorization`	HTTP Header	建議	格式為 `Bearer YOUR_API_KEY`。
`APIKEY`	Query String	相容舊版	用戶 API 金鑰。無效、停用或超過使用量會回傳錯誤。

支援物流方式

method	物流商	單號格式參考	說明
`7-11`	7-11 交貨便	常見為英文字母開頭加數字，例如 `T01434848391`	背景查詢會處理驗證碼並解析貨態歷程。
`hct`	新竹物流	常見為 10 碼數字，例如 `7160691856`	背景查詢會處理驗證碼與二階段查詢頁。

目前公開 API 文件列出正式排程會處理的物流方式。若未來開放其他物流商，只要擴充 method 與背景掃描排程即可沿用相同回應格式。

API 1: 註冊物流單號

GET /?sub=regLogisticsID

將物流單號加入追蹤清單。若同一使用者已註冊同一筆單號，會回傳成功並提示已註冊；若該單號已被其他使用者註冊，會回傳錯誤。

Request Parameters

參數	必填	型別	說明
`sub`	是	string	固定為 `regLogisticsID`。
`logisticsID`	是	string	物流單號。
`method`	是	string	物流方式，目前公開支援 `7-11`、`hct`。
`notifyURL`	否	string	狀態變更時接收 callback 的 HTTPS URL。只允許標準 443 port，且不可指向內網、localhost 或保留 IP。
`APIKEY`	是	string	用戶 API 金鑰。

Example Request

https://itrack.ing/?sub=regLogisticsID&logisticsID=T01434848391&method=7-11&notifyURL=https%3A%2F%2Fexample.com%2Fcallback&APIKEY=YOUR_API_KEY

Success Response

{
    "success": true,
    "message": "成功註冊物流單號",
    "data": {
        "logisticsID": "T01434848391",
        "method": "7-11",
        "create_time": "2026-05-11 15:20:00"
    }
}

Already Registered Response

{
    "success": true,
    "message": "該物流單號已註冊",
    "data": {
        "logisticsID": "T01434848391",
        "method": "7-11",
        "create_time": "2026-05-11 15:20:00"
    }
}

API 2: 查詢物流狀態

GET /?sub=queryLogistics

查詢已註冊物流單號的最新追蹤資料。只能查詢同一 API Key 所屬使用者註冊的單號。

Request Parameters

參數	必填	型別	說明
`sub`	是	string	固定為 `queryLogistics`。
`logisticsID`	是	string	物流單號。
`APIKEY`	是	string	用戶 API 金鑰。

Example Request

https://itrack.ing/?sub=queryLogistics&logisticsID=T01434848391&APIKEY=YOUR_API_KEY

Success Response

{
    "success": true,
    "logisticsID": "T01434848391",
    "method": "7-11",
    "data": [
        {
            "time": "2026/05/11 14:10",
            "status": "包裹配達取件門市"
        },
        {
            "time": "2026/05/10 18:42",
            "status": "配送中"
        }
    ],
    "last_update_time": "2026/05/11 14:10",
    "done": false,
    "refund": false,
    "create_time": "2026-05-11 12:00:00",
    "update_time": "2026-05-11 15:00:00"
}

Response Fields

欄位	型別	說明
`success`	boolean	是否成功。
`logisticsID`	string	物流單號。
`method`	string	物流方式。
`data`	array	物流歷程，通常最新狀態在第一筆。
`last_update_time`	string\|null	最新物流狀態時間；尚未完成背景查詢時可能為 `null`。
`done`	boolean	是否已完成取貨或配送。
`refund`	boolean	是否判定為退貨或退件。
`create_time`	string	註冊時間。
`update_time`	string	最後一次資料更新時間。

Callback 通知

註冊物流單號時若提供 notifyURL，當背景掃描發現最新貨態、完成狀態或退貨狀態改變時，系統會以 HTTP POST 傳送 JSON 到該 URL。

Request Headers

Content-Type: application/json
X-Logistics-Notification: true

Callback Payload

{
    "Status": "SUCCESS",
    "Message": "貨態狀態處理成功(32)",
    "MerID": "",
    "ShipTradeNo": "T01434848391",
    "LgsType": "C2C",
    "GoodsType": 1,
    "ShipStatus": 32,
    "ShipStatusDesc": "包裹配達取件門市",
    "ShipStatusTime": "2026-05-11 14:10:00",
    "ApiType": "ShipStatus",
    "Partnerid": "",
    "ShipType": 1
}

Callback 成功條件

接收端需要回傳 HTTP 200，且 response body 內容為 OK。若失敗，系統會記錄失敗狀態，最多重試 5 次；重試通知會帶上 retry: 1。

常見 ShipStatus

代碼	說明
`91`	未處理或尚未判定。
`21`	待出貨或物流商已收件。
`22`	物流驗收或送達物流中心。
`31`	配送中。
`32`	待取貨。
`11`	已取貨或已送達。
`51`	一般退貨。
`53`	廠退或退件。

錯誤回應

API 錯誤會以 JSON 回傳 error 欄位。

{
    "error": "無效的 API Key"
}

錯誤訊息	可能原因
`缺少必要參數`	未帶入必要 query string。
`資料庫連線失敗`	MongoDB 無法連線或認證失敗。
`無效的 API Key`	API Key 不存在。
`用戶帳號已被停用`	使用者狀態不是 `active`。
`API 使用次數已達上限`	用戶 API 使用量已達限制。
`該物流單號已被其他用戶註冊`	相同物流單號與物流方式已被其他使用者建立。
`找不到該物流單號或無權限查詢`	單號不存在，或不屬於該 API Key 的使用者。

串接範例

PHP

$url = 'https://itrack.ing/?' . http_build_query([
    'sub' => 'queryLogistics',
    'logisticsID' => 'T01434848391',
]);

$context = stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer YOUR_API_KEY\r\n"
    ]
]);

$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);

curl

curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://itrack.ing/?sub=queryLogistics&logisticsID=T01434848391'