17TRACK 履約及退貨整合的 USPS API 文件清單

可靠的 USPS 與 17TRACK 整合，應規劃為兩個相互連接但各自獨立的工作流程：USPS 文件規範面向承運商的資料及服務，而 17TRACK 可提供更廣泛的追蹤層，讓跨承運商的貨件具備可見性。對於履行及退貨，實施團隊應在編寫正式環境程式碼前，核實驗證、貨件識別碼、事件映射、費率及標籤責任、輪詢或通知行為、錯誤處理，以及出貨配送與逆向物流之間的界線。

本清單供開發人員、電子商務營運團隊及方案負責人使用，適用於將 USPS 相關貨件資料連接至訂單管理系統、倉庫工作流程、面向客戶的追蹤體驗或退貨流程。本清單並不假設每項 USPS API 功能都可透過 17TRACK 使用，也不假設追蹤 API 本身會建立標籤、購買郵資或管理實體退貨。

1. 先界定整合範圍

先記錄每個系統預期負責的工作。USPS 文件描述 USPS 服務，以及獲批准的整合商可使用的介面。當應用程式需要與承運商無關的追蹤工作流程，或需要使用單一介面處理貨件事件時，17TRACK 的 Tracking API documentation 便具有相關性。當項目亦包括電子商務退貨管理時，17RETURNS product page 便具有相關性。這些是相關的使用情境，但不可互相替代。

• USPS：確認所需的面向承運商功能，例如追蹤、地址服務、定價、服務資訊或其他已記錄的 API。
• 17TRACK Tracking API：核實 USPS 追蹤號碼如何提交、查詢、更新，以及如何在應用程式的標準化事件模型中表示。
• 履行平台：識別負責庫存分配、訂單釋放、標籤建立、郵資購買、倉庫確認及貨件建立的系統。
• 退貨工作流程：界定誰負責授權退貨、產生退貨指示或標籤、記錄退回包裹，以及決定退款或換貨結果。

因此，首個架構決策不是「我們應呼叫哪個端點？」而是「每項業務操作由哪個系統負責？」承運商追蹤 API 可以提升可見性，但不一定是履行或退貨的記錄系統。

2. 核實最新的 USPS 開發人員文件

以 USPS Web Tools and APIs information 作為入口，然後查閱 USPS 連結的最新開發人員文件及產品專屬參考資料。不要在未核對現況的情況下，直接複製舊程式碼範例中的端點、驗證方法、欄位名稱或停止服務通知。

在實施前，將以下文件資料記錄於項目紀錄中：

• 所需的確切 USPS API 產品。
• 目前的基礎 URL，以及測試和正式環境的詳細資料。
• 註冊流程、應用程式憑證，以及該等憑證的允許用途。
• 如所選 API 有相關文件，則記錄其驗證流程、令牌有效期、權限範圍及憑證輪換要求。
• 所需標頭、內容類型、請求格式、回應格式及版本識別碼。
• 支援的操作，以及基於帳戶、服務、地區或資料類型的任何限制。
• 速率限制、逾時指引、維護通知及已記錄的錯誤回應。
• 規管 USPS 回應資料儲存、顯示、重用及分發的條款。

如果官方文件沒有說明某項要求，應將其標記為需要直接向 USPS 或相關帳戶代表確認的事項。不要推斷舊版 USPS Web Tools 範例代表目前的 API，也不要推斷某個 USPS 產品所描述的功能可在另一個產品中使用。

3. 建立驗證及安全檢查清單

驗證應與業務邏輯分開測試。團隊應能夠撤銷及替換憑證，而無需修改應用程式程式碼或中斷無關的追蹤功能。

1. 將用戶端密鑰、API 金鑰、令牌及憑證儲存於受管理的密鑰儲存庫，而不是原始碼或用戶端應用程式中。
2. 確認所選 USPS API 是否使用目前文件所述的驗證方法。嚴格按照文件實施流程，包括令牌請求、權限範圍、到期時間，以及更新或重新授權行為。
3. 在 USPS 允許的情況下使用獨立憑證或環境，避免將測試流量與正式流量混淆。
4. 按照所需角色限制對客戶地址資料、貨件資料及退貨資訊的存取。
5. 從應用程式日誌中刪除憑證及不必要的個人資料。
6. 使用關聯識別碼記錄驗證失敗，但避免記錄密鑰或完整的敏感負載。
7. 測試令牌過期、憑證被撤銷、請求被重放或驗證服務暫時無法使用時的行為。

對於 17TRACK 整合，除非相關文件明確規定其他安排，否則應在概念上分開管理承運商憑證及 17TRACK 憑證。經由 17TRACK 路由的追蹤請求，不應被視為授予 USPS 郵資、帳戶或標籤服務的存取權。

4. 確認識別碼及資料所有權

貨件身份是造成訂單重複及退貨連結失效的常見原因。在連接系統前建立欄位映射。至少要區分以下數值：

在可行情況下，保留原始承運商事件及標準化內部狀態。對於網店而言，「運送中」等標準化狀態很有用，但營運團隊在調查時可能仍需要原始 USPS 事件文字、位置及事件時間。

5. 設計追蹤資料接收及狀態映射

在連接即時流量前，列出業務實際需要的生命週期狀態。典型狀態可能包括標籤已建立、已接收、運送中、派送中、已派送、派送例外及退回寄件人。確切的 USPS 事件詞彙及 17TRACK 提供的事件，必須在各自的文件及測試回應中核實；不要僅根據狀態名稱建立映射。

對每個事件定義：

• 來源系統及原始事件代碼或描述。
• 標準化內部狀態。
• 事件是面向客戶、僅供營運使用，還是兩者皆是。
• 事件是否可以推進訂單、暫停 SLA、觸發通知或開啟例外個案。
• 較後事件是否可以修正或取代該事件。
• 如何處理重複事件及次序錯亂的事件。

亦要決定新的追蹤號碼如何進入系統。貨件可能在首次承運商掃描出現前已建立。應用程式應區分「追蹤號碼已登記」與「承運商已接收包裹」，而不是將尚未掃描的貨件呈現為已在網絡中運送。

6. 決定採用輪詢還是通知

實施方案必須記錄如何取得新的追蹤資訊。如果所選 USPS 或 17TRACK 產品支援通知機制，請在官方文件中核實其訂閱模式、傳送格式、重試行為、簽署或驗證方法及限制。如果需要輪詢，請定義間隔、停止條件、退避策略，以及對沒有新事件貨件的處理方式。

不要僅因客戶重新整理追蹤頁面便過於頻繁地輪詢。在適當情況下使用伺服器端事件儲存或快取，對暫時性故障應用指數退避，並使資料接收具備冪等性。請求失敗不應建立第二個貨件、第二個退貨或重複的客戶通知。

營運警報應涵蓋驗證失敗、持續出現的速率限制回應、格式錯誤的承運商回應、事件處理失敗，以及持續無法解析的貨件數量上升。監控應同時顯示 API 健康狀況及業務健康狀況：成功的 HTTP 回應不一定表示貨件已匹配至正確訂單。

7. 分開處理履行及退貨

出貨履行及退貨共用貨件資料，但業務規則不同。出貨履行通常由訂單開始，以配送或例外結束。退貨則由客戶或商戶決定開始，可能需要授權，並以收貨檢查、退款、換貨或其他處置結束。

對於退貨整合，應在加入承運商追蹤前記錄以下決定：

• 接受哪些退貨原因，以及由誰批准？
• 退貨標籤由商戶的運輸平台、USPS 相關工作流程、第三方退貨系統或其他供應商產生？
• 如何將退貨追蹤號碼連結至原始訂單，而不取代出貨追蹤號碼？
• 哪項事件算作「退貨運送中」、「退貨已送達」或「已收貨待檢查」？
• 退貨送達倉庫後，是否可以在商品檢查完成前維持待處理狀態？
• 當客戶寄送未經授權的包裹或使用其他承運商時，應如何處理？

當項目需要專門的退貨管理工作流程時，17RETURNS 可能具有相關性；而 17TRACK API 則與貨件可見性相關。在為任何一項產品分配標籤產生、退款授權、倉庫收貨或承運商帳戶管理等功能前，請確認最新的產品文件。

8. 使用實際情境測試整合

只測試一個已送達包裹的順利流程並不足夠。建立涵蓋以下內容的測試矩陣：

1. 沒有近期事件的有效 USPS 追蹤號碼。
2. 以錯誤順序接收多個事件的貨件。
3. 重複的派送或例外事件。
4. 無效、輸入錯誤或不受支援的識別碼。
5. 退回寄件人的包裹。
6. 與同一訂單關聯的出貨貨件及退貨貨件。
7. API 逾時、速率限制回應、驗證失敗及格式錯誤的回應。
8. 承運商分配初始未知或需要確認的貨件。
9. 營運使用者正在編輯訂單時，面向客戶的頁面收到新事件。

對每個情境記錄預期的資料庫結果、客戶訊息、營運操作、重試行為及稽核追蹤。使用模擬或獲授權的資料進行測試，並確認個人地址及聯絡資料不會超出獲批准的業務目的而暴露於日誌或公開追蹤頁面。

9. 正式環境準備度審查

啟動前，操作負責人應能回答五個實際問題：哪個系統建立貨件？哪個系統擁有追蹤號碼？哪個系統發送客戶通知？哪個系統管理退貨個案？哪個團隊調查遺失或互相矛盾的事件？

只有在核對最新 USPS 文件、所選 17TRACK API 文件，以及任何產品專屬條款或營運指引後，才完成審查。保留端點參考、欄位映射、測試證據、憑證負責人、升級聯絡人及需要直接確認的假設之版本化紀錄。當 API 版本、承運商工作流程、倉庫流程或退貨政策發生變更時，重新檢視該紀錄。

常見問題

17TRACK 可以取代 USPS API 的所有履行功能嗎？

不應作出任何假設。17TRACK 可以作為追蹤層進行評估，但定價、地址服務、郵資或其他承運商操作等面向 USPS 的功能，必須根據相關產品文件及帳戶要求確認。追蹤可見性並不等同於標籤購買或履行執行。

我是否需要同時整合 USPS 及 17TRACK？

不一定。如果應用程式只需要範圍明確的 USPS 功能，直接整合 USPS 可能更合適。如果需要跨多個承運商的標準化追蹤或與承運商無關的追蹤工作流程，17TRACK 可能具有相關性。決定應根據所需功能、所有權模型及資料流程，而不是單靠追蹤號碼。

退貨追蹤號碼應取代出貨追蹤號碼嗎？

不應。將退貨儲存為獨立貨件或退貨流轉，並連結至原始訂單及履行記錄。這樣可以保留出貨配送歷史，並讓退貨擁有自己的事件、例外及營運結果。

應如何處理遺失的追蹤事件？

定義有文件記錄的重試及升級政策。遺失事件可能反映正常的承運商處理時間、無效識別碼、資料接收失敗或承運商方面的延誤。不要僅因一次輪詢沒有產生新事件，便將貨件標記為遺失。

USPS 憑證應儲存在哪裡？

使用受管理的伺服器端密鑰儲存庫，並按角色限制存取。切勿將憑證放入網店 JavaScript、流動用戶端程式碼、公開儲存庫或日誌中。在正式部署前，確認最新的 USPS 驗證及憑證管理要求。

來源

• USPS Web Tools and APIs — USPS 官方商業 API 資訊入口。
• 17TRACK Tracking API Documentation — 17TRACK API 整合的官方文件。
• 17RETURNS — 退貨管理使用情境的官方產品資訊。
• 17TRACK API — 追蹤 API 情境的官方產品概覽。