你的第一個追蹤 API 請求:使用 Postman 和 Curl 的 REST 用戶端操作指南
要發出您的第一個追蹤 API 請求,請在 REST 用戶端中設定端點、驗證標頭和 JSON 主體,發送請求,並檢查 HTTP 狀態及回應主體。本教學使用 17TRACK 的 Tracking API,在 Postman 和 curl 中示範相同的工作流程:註冊貨件、請求其追蹤資訊,並檢查結果是否已準備好供您的應用程式使用。

目標是一項小型、可重現的整合測試,而不是正式環境部署。您需要 API 憑證,以及獲授權處理的追蹤號碼。以下指令使用 v2.2 端點模式;執行前,請在 17TRACK API 文件中確認端點版本及帳戶特定要求。
了解您的第一個請求應完成的工作
貨件追蹤整合涉及兩項獨立工作:告知服務要追蹤哪件貨件,以及取得與該貨件相關的追蹤資訊。在此示範的工作流程中,這是兩個獨立的請求。註冊並不表示包裹已經運送,註冊成功也不保證承運商事件會立即提供。
首次測試時,請使用一件貨件,而不是批次。這樣更容易分離驗證錯誤、無效追蹤號碼及回應解讀問題。您的第一個有用里程碑並不只是「我收到 HTTP 200」。而是「API 接受了我預期的操作,而我能夠解釋貨件層級的結果」。
Postman 提供視覺化介面,讓您編輯請求及檢查回應。curl 可讓您從終端機重現相同的 HTTP 交換。兩者都不會改變 API 的驗證規則、貨件資料或處理行為。請使用有助於您更清楚調查請求的工具,然後在另一個工具中重現可運作的設定。
準備您的憑證、貨件及請求詳情
開啟任一用戶端前,請準備以下資料:
- 已授權的 API 憑證:透過您的 17TRACK API 帳戶設定取得。消費者追蹤工作階段不能取代 API 憑證。
- 真實追蹤號碼:使用您擁有或獲准存取的貨件。測試實際追蹤資料時,最近活躍的貨件通常比虛構號碼更有用。
- 承運商(如已知):保留承運商名稱以便診斷。如果您的情況需要承運商識別碼,請使用 API 文件所定義的值和欄位,不要猜測。
- 目前的請求契約:確認 API 版本、驗證標頭、請求結構描述及任何帳戶限制。
- 安全的工作區:避免將憑證、客戶資料或完整追蹤回應放入公開儲存庫、截圖或共享的支援訊息中。
最簡請求範例使用以下設定:
| 設定 | 範例配置 |
|---|---|
| Base URL | https://api.17track.net/track/v2.2 |
| 註冊操作 | POST /register |
| 追蹤資訊操作 | POST /gettrackinfo |
| 驗證標頭 | 17token: YOUR_API_TOKEN |
| 主體格式 | Content-Type: application/json,並包含貨件物件的 JSON 陣列 |
請將追蹤號碼保留為字串。將其轉換為數值類型可能會移除開頭的零,或以其他方式改變其值。以下的佔位符 YOUR_TRACKING_NUMBER 必須替換為您的實際測試貨件;它不是可運作的範例號碼。
在 Postman 中發出註冊請求
1. 建立小型測試環境
在 Postman 中建立包含三個變數的環境:base_url、tracking_token 和 tracking_number。將 base_url 設定為上述 Base URL,並在另外兩個變數中輸入您的憑證和貨件號碼。發送請求前,選取該環境。
使用 Postman 可用的機密處理控制項處理 token,並檢查您的工作區會共享或同步哪些內容。在介面中隱藏值並不能取代控制誰可以存取它。不要將已填入憑證的集合匯出給同事或用於公開文件。
2. 設定方法、URL 和標頭
建立 HTTP 請求,選取 POST,並將 {{base_url}}/register 輸入為 URL。在 Headers 分頁中加入:
17token: {{tracking_token}}
Content-Type: application/json在此範例中,憑證應放在自訂的 17token 標頭中。不要因為其他 API 使用 Bearer token 模式,就將其替換為 Bearer token 設定。同時檢查繼承的集合設定是否意外加入 Authorization 標頭。
3. 加入 JSON 主體
開啟 Body,選擇 raw,再選取 JSON。輸入:
[
{
"number": "{{tracking_number}}"
}
]外層方括號十分重要:此請求使用陣列,即使其中只有一件貨件。使用雙引號、移除結尾逗號,並不要在 JSON 中加入註解。如果文件要求您的承運商或貨件提供其他資料,請在發送前加入已記載的欄位。
4. 發送並檢查結果
按一下 Send。首先,檢查是否完全收到 HTTP 回應。DNS 失敗、TLS 錯誤、代理伺服器問題或逾時,與收到解釋請求無效的回應不同。接着,檢查回應主體中的操作結果,以及任何貨件層級的接受或拒絕資訊。
將請求儲存為「Register test shipment」。記錄 HTTP 狀態、API 結果及任何錯誤訊息,但不要複製 token。如果註冊失敗,請先解決該問題再繼續。重複提交未變更的請求會令診斷更困難,並可能消耗帳戶資源。
使用 curl 重現請求
以下指令使用 POSIX 風格的 shell,例如 Bash 或 Zsh。PowerShell 和 Windows Command Prompt 使用不同的引號及變數規則。在 PowerShell 中,如有需要請使用 curl.exe 呼叫 curl 可執行檔,而不是 shell 特定的命令別名。
設定 Base URL,並透過您平常的機密處理流程將憑證載入環境變數:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.環境變數可避免憑證出現在可重用範例中,但它不是完整的機密管理系統。在本機測試時,避免將真實 token 輸入 shell 歷程會保留的指令中。進行自動化時,使用平台的機密儲存區並限制日誌輸出。
建立名為 shipment.json 的檔案,並將佔位符替換為您的測試追蹤號碼:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]發送註冊請求:
curl --request POST \
--url "$TRACKING_BASE_URL/register" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output register-response.json \
--write-out 'HTTP status: %{http_code}\n'這會將回應主體儲存到 register-response.json,並單獨列印 HTTP 狀態。連線及總逾時是本機測試選擇,並非 17TRACK 服務保證。開啟已儲存的檔案檢查 API 結果;單獨查看狀態列並不足夠。
即使伺服器返回 HTTP 錯誤回應,curl 仍可能成功完成傳輸。相反,傳輸失敗可能導致任何可用的 API 回應都無法到達。編寫腳本時,請將 curl 結束狀態、HTTP 狀態及應用程式層級結果視為不同訊號。
請求貨件的追蹤資訊
確認註冊後,複製 Postman 請求,並將 URL 更改為 {{base_url}}/gettrackinfo。保留 POST 方法、驗證標頭、內容類型及貨件主體。將其另行儲存,避免在您想取得資料時意外重新註冊貨件。
對應的 curl 請求如下:
curl --request POST \
--url "$TRACKING_BASE_URL/gettrackinfo" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output tracking-response.json \
--write-out 'HTTP status: %{http_code}\n'不要假設新註冊的貨件會立即返回完整事件歷程。資料可用性取決於貨件及服務的處理進度。如果資訊尚未提供,請遵循已記載的取得及更新指引,不要反覆註冊相同號碼或執行過於密集的輪詢迴圈。
分三個層級閱讀回應
- 傳輸:用戶端是否已連線並收到 HTTP 回應?
- 操作:API 是否接受請求,而個別貨件是否成功?
- 貨件資訊:返回的資料是否識別出預期包裹?其狀態或事件歷程實際證明了甚麼?
使用官方回應結構描述尋找狀態、承運商及事件欄位。保留標準化貨件狀態與承運商原始事件描述之間的區別。查詢成功並不代表已送達,而缺少事件也不代表包裹遺失。
儲存時間戳時,保留所提供的時區或偏移資訊。避免將不同格式的原始日期字串排序,並假設它們代表正確的時間順序。同時區分您的應用程式取得記錄的時間與貨件事件發生的時間。
不要一次更改所有內容來進行疑難排解
- 沒有回應:檢查主機名稱、網絡存取、代理伺服器設定、TLS 配置及本機逾時。不要把停用憑證驗證作為例行修復方法。
- 驗證失敗:確認 token 有效、
17token標頭存在,且所選的 Postman 環境能正確解析變數。檢查是否有意外空白。 - 請求無效:根據文件驗證 API 版本、操作路徑、POST 方法、內容類型及 JSON 陣列結構。
- 貨件被拒絕:閱讀貨件特定錯誤。檢查號碼及任何必要的承運商資料,不要將每次拒絕都視為驗證問題。
- 沒有追蹤事件:確認註冊及預期貨件身分。檢查是否需要承運商資料,以及是否有更新可用,再進行重試。
- Postman 可運作但 curl 失敗:比較解析後的 URL、實際標頭及主體位元組。Shell 引號及未設定的環境變數是請求產生差異的常見原因。
每次測試只更改一項變數,並簡短記錄結果。如果您檢查 Postman 主控台或使用 curl 的詳細輸出,請將輸出視為敏感資料:請求標頭可能暴露憑證。分享診斷資料前,請遮蓋機密及客戶資訊。
了解何時完成本教學
當兩個用戶端都發送預期請求、您理解註冊結果、取得操作返回可解讀的結果,並能區分 API 失敗與貨件沒有新資訊時,您便完成了一項有意義的首次整合測試。單靠相同的 HTTP 狀態碼,並不能證明兩個用戶端的行為完全相同。
在將工作流程移入應用程式前,請將憑證保留在伺服器上、驗證輸入,並使用結構化錯誤處理。查閱帳戶適用的速率限制、批次限制、重試指引及更新傳送選項。不要假設註冊在逾時後可以盲目重試:伺服器可能已處理請求,即使您的用戶端沒有收到回應。
為無效憑證、格式錯誤的 JSON、無效貨件號碼、已註冊貨件、追蹤資料不可用及網絡逾時加入測試。每種情況都應導向明確的應用程式結果,而不是未處理的例外或誤導客戶的狀態。
常見問題
我可以不使用真實追蹤號碼進行測試嗎?
您可以使用無效值測試部分請求驗證行為,但這不能驗證貨件追蹤。若要測試真實事件,請使用已授權貨件,或在服務提供時使用有文件記載的測試裝置。不要假設任意範例號碼屬於沙盒環境。
為甚麼 HTTP 200 回應仍然包含失敗?
HTTP 狀態和應用程式結果描述不同層級。伺服器可以成功接收及處理請求,同時報告個別貨件被拒絕。請閱讀回應主體及已記載的貨件層級結果,而不只是 HTTP 狀態。
為甚麼使用 POST 取得追蹤資訊?
請使用端點契約指定的方法。此取得範例透過 POST 接受 JSON 請求主體中的貨件識別碼。因為操作讀取資料就將其改為 GET,並不能保留文件所記載的請求。
我應否將 API token 放在瀏覽器 JavaScript 中?
不要將私人 API 憑證嵌入公開傳送的前端程式碼。請透過受授權的後端路由請求,以保護憑證、驗證輸入,並控制每位使用者可存取的貨件資訊。
正式環境需要同時使用 Postman 和 curl 嗎?
不需要。它們是實用的測試及診斷工具。您的正式環境應用程式可以使用合適的 HTTP 用戶端。保留經過清理的 Postman 請求或 curl 指令作為可重現參考,但不要包含有效 token 或不必要的客戶資料。
來源
- 17TRACK API documentation — 驗證、端點契約、請求欄位、回應解讀及整合要求的參考。
- Postman documentation: Send API requests — 請求設定及回應檢查。
- Postman documentation: Variables — 基於變數的請求設定。
- curl manual — 標頭、請求主體、逾時、已儲存回應及 HTTP 狀態輸出的指令選項。


