Skip to main content
首頁博客指南投入生產前向追蹤 API 供應商提出的 15 個問題

投入生產前向追蹤 API 供應商提出的 15 個問題

17TRACK

在將追蹤 API 投入生產環境前,請先了解它如何處理你們實際使用的承運商和貨件類型、其事件代表甚麼、更新如何送達,以及當資料或整合失敗時會發生甚麼。以下 15 個問題,讓工程及營運團隊能在客戶、支援人員或自動化工作流程依賴這些資料前,以實際方式驗證相關答案。

使用追蹤 API 供應商前應提出的 15 個問題

成功的示範並不等於生產環境測試。請使用具代表性的貨件樣本,包括延誤、退回及難以識別的包裹。對於每個答案,要求提供文件、範例 payload 或測試結果。對於任何尚未解決的項目,請記錄負責人及決策日期,而不要假設會在上線後才處理。

先從貨件適用性及資料含義開始

1. 我們實際的哪些貨件可以追蹤,而覆蓋範圍代表甚麼?

向供應商提供你們使用的承運商、服務、起點及目的地組合,以及追蹤號碼格式樣本。要求供應商識別哪些貨件可以接受、哪些承運商可以自動識別,以及哪些情況必須由你們提供承運商代碼。承運商出現在清單上,並不代表每項服務、交接或貨件類型都會產生應用程式所需的事件。

測試來自高貨量路線及營運邊界情況的真實例子。如果你們的業務會出現貨件在運送途中更換承運商,也請加入相關貨件。記錄 API 是拒絕貨件、接受貨件但找不到事件,還是返回詳細程度有限的事件。這些結果在訂單管理系統中需要不同的處理方式。

2. 登記貨件需要甚麼資料,以及你們如何防止重複登記?

釐清所需識別資料、承運商選擇規則、登記時機,以及對無效或尚未啟用追蹤號碼的回應。詢問在你們的使用情境中,是否只需追蹤號碼,還是需要其他資料。確認同一貨件由同一系統或不同服務提交兩次時會發生甚麼。

建立一個責任清晰的登記流程:哪個系統提交貨件、哪個系統儲存供應商的識別碼,以及哪個系統會重試不確定的提交。如果供應商已處理請求,但請求在其後逾時,盲目重試不可悄悄建立第二筆記錄或重複發送下游通知。

3. 你們的狀態代表甚麼,以及我們能否查看底層承運商事件?

要求提供狀態字典及具代表性的原始事件。途中、派送中、異常、已送達及已退回等術語是有用的摘要,但你們的業務規則可能需要更多細節。確認供應商是否會在標準化狀態旁提供原始承運商描述,以及如何處理無法清晰對應的事件。

在上線前先就你們自己的內部狀態模型達成共識。特別要決定哪些事件可以結束貨件、觸發送達訊息或啟動異常工作流程。除非底層資料支持該解讀,否則不要將概括的狀態標籤視為特定實體事件的證明。

4. 會提供哪些時間戳及地點資料,而我們應如何解讀?

對於每個事件,區分承運商表示事件發生的時間,與供應商接收或發佈事件的時間。詢問時區、缺失的偏移量、地點精確度,以及在較後事件之後才到達的更新。最近收到的事件可能描述較早的掃描;只按資料接收時間排序可能會產生誤導性的時間線。

使用你們的資料庫結構及面向客戶的顯示方式測試 payload。決定在事件的本地時區不確定時如何顯示,並在來源沒有提供精確送達時間或地點時,避免顯示相關資料。

5. 異常、退貨及送達證明如何表示?

要求提供派送失敗、海關扣留、地址問題、退回寄件人流程及已送達貨件的例子。詢問哪些詳細資料已標準化、哪些仍是承運商特有,以及在你們關注的情況下,送達確認是否包括任何支援證據。不要假設已送達狀態包括收件人姓名、簽名、相片或其他證明。

將每項異常對應至負責行動的人員。有些事件需要支援人員審查;其他事件則要等更多資訊到達後才需要向客戶發送訊息。如果爭議處理流程需要送達證明,請將其可用性及格式列為獨立的驗收標準,而不要視為追蹤覆蓋範圍中理所當然的一部分。

測試更新如何送達你們的系統

6. 你們會透過 webhook、輪詢,還是兩者提供更新?我們應在何時使用各種方式?

要求提供已記錄的傳送模式、payload 範例、訂閱設定及恢復遺漏更新的指引。如果提供 webhook,請確定它們是通知貨件已變更、提供完整快照,還是承載單一事件。如果必須使用輪詢或將其作為後備方案,請釐清適當的請求模式,以及如何識別已變更的記錄。

根據工作流程選擇模式。面向客戶的時間線可接受的更新延遲,可能與異常佇列不同。你的架構不應僅因整合使用 webhook 就承諾即時警示:承運商必須先提供事件,而其後每個系統也必須處理該事件。

7. 當通知重複、延遲或以錯誤順序到達時會發生甚麼?

詢問供應商是否會重試未成功的傳送、會持續多久,以及它期望你的端點返回甚麼回應。如果有可用的穩定事件或貨件識別碼,請要求提供。然後測試同一通知兩次、在較新的事件之後傳送較舊的事件,並暫時讓你的端點返回錯誤。

你的接收器應設計為只確認已安全接受的內容,在重試時不重複發送客戶訊息,並在事件以錯誤順序到達時重建正確的時間線。如果所提出的設計依賴每個通知必定只傳送一次,請在發佈前質疑這項假設。

8. 我們如何衡量資料新鮮度,而哪些因素會影響它?

詢問供應商在每個階段可以衡量甚麼:承運商事件時間、供應商接收時間,以及傳送至你們系統的時間。將這些衡量結果與供應商作出的任何承諾分開。一段實體移動與應用程式更新之間的長時間差距,可能源於上游、供應商處理流程,或你們自己的佇列。

在試行期間,針對具代表性的貨件衡量這些差距,並調查異常值。根據工作流程的實際要求設定警示門檻。如果延遲掃描可能導致有害的客戶訊息或錯過升級處理,請定義後備方案,例如標示資料過時或進行人工審查。

9. API 憑證及 webhook 請求如何受到保護?

要求提供驗證及憑證管理文件。確認憑證如何簽發、設定範圍、輪換及撤銷;測試及生產憑證是否分開;以及 webhook 接收器如何驗證請求的真實性。同時詢問可採取哪些措施防止重播 webhook 請求。

讓安全團隊審查所提出的實作,而不只是供應商的功能清單。將密鑰排除在客戶端程式碼及日誌之外,限制生產憑證的存取,並演練憑證輪換。如果你的應用程式無法使用文件所述機制驗證傳入通知,對於基於 webhook 的工作流程而言,這就是阻止發佈的問題。

10. 你們保留哪些貨件及客戶資料,而資料會傳送至哪裏?

列出整合會傳送的每個欄位,包括追蹤號碼、訂單參考資料、地址、聯絡資料及任何自訂中繼資料。詢問哪些欄位是必需的、資料及日誌會保留多久、刪除請求如何處理,以及哪些地區或次級處理商與你們組織的要求有關。在審查需要時,取得合約或安全文件。

盡量減少傳送的資料。追蹤整合不應僅因為方便,就接收客戶資料或整個訂單物件。你們的私隱、法律及安全團隊應決定供應商記錄的處理方式是否適合你們營運所在的市場。

為故障及營運變更作好規劃

11. 速率限制是甚麼,而客戶端應如何回應錯誤?

要求提供按端點、憑證及環境劃分的限制,以及任何並行規則和建議的重試行為。區分無效請求、暫時性服務問題,以及受到速率限制的請求。對於 HTTP API,狀態碼含義十分重要:RFC 6585 定義 429 代表請求過多,而 RFC 9110 說明 HTTP 語義,包括伺服器錯誤。

計算普通日子及高峰時段的預期流量,然後測試一個會退避、將工作排入佇列,並在持續失敗時發出警示的客戶端。確認不確定的寫入是否可以安全重試。在故障期間增加流量的重試政策,可能令恢復更加困難。

12. 結構、狀態及承運商整合變更如何傳達?

詢問 API 版本控制、棄用通知、變更日誌,以及事件欄位是否可以在不變更版本的情況下新增。承運商提供的描述及追蹤行為也可能變更。確定當變更只影響某一承運商或路線,而非整個 API 時,供應商會如何通知。

為可選欄位及未知狀態值編寫具容錯能力的解析器,但不要悄悄將不熟悉的值轉換為已送達或失敗。儲存足夠的來源詳細資料,以診斷變更的映射。指定人員審查供應商通知,並在變更影響客戶前更新整合測試。

13. 生產前可以測試甚麼,而測試環境與實際行為有多接近?

要求取得文件、如有提供的測試環境、範例回應,以及測試錯誤路徑的方法。詢問哪些情境是模擬的,哪些需要真實貨件。沙盒可以證明你的程式碼能處理某個 payload,但未必能反映承運商事件的完整性、更新時機或地區適用性。

進行兩類測試:針對解析、重試及安全性的確定性整合測試;以及針對營運行為的有限真實貨件試行。加入重複提交、供應商逾時、延遲掃描、退貨及未知狀態。要求工程團隊及將處理異常的團隊均確認結果。

14. 當追蹤停止更新時,適用哪些支援及事故承諾?

詢問帳戶可使用哪些支援渠道、如何報告事故,以及哪些合約服務承諾(如有)適用於 API 或通知傳送。釐清可用性承諾涵蓋 API 端點、追蹤更新傳送,還是兩者。它們並非相同的營運結果。

建立你們自己的應變手冊:誰負責偵測故障、誰聯絡供應商、何時使用輪詢或其他後備方案,以及更新延遲時客戶會看到甚麼。要求提供解決特定貨件資料問題及整個平台故障的流程。在需要之前先測試升級處理路徑。

15. 使用量及成本如何計算,而如果我們離開會發生甚麼?

詢問哪些操作會計入計費或使用量限制:提交、追蹤貨件、請求、通知,還是其他單位。確認重複登記、重試、不活躍貨件、超額使用及測試流量在擬議協議下如何處理。取得適用條款的書面文件,而不要根據 API 示範估算成本。

同時為終止合作作好規劃。確定如何匯出貨件歷史記錄、存取權限會保留多久,以及活躍追蹤記錄會如何處理。可行的退出計劃並不代表你預計轉換供應商;它是避免失去對已在運送中的貨件可見性的方式。

將答案轉化為生產環境決策

實用的上線審查應產生三項結果:

  • 貨件適用性結果:經測試的樣本,顯示哪些追蹤記錄已被接受,以及其事件是否支持預期的客戶及營運工作流程。
  • 整合結果:已示範如何處理驗證、重複、重試、延遲事件、結構變化及遺漏更新的恢復。
  • 營運協議:記錄限制、資料處理條款、支援聯絡人、成本假設,以及未解決風險的負責人。

如果多承運商追蹤 API 符合你的使用情境,17TRACK 是其中一家可供評估的供應商;其 Tracking API 頁面 及 API 文件 可作為根據這些問題檢查整合的起點。同一標準也應適用於任何供應商:文件說明介面預期如何運作,而你們自己的代表性貨件測試則確認它是否適合生產工作流程。在觸發客戶通知或異常自動化的事件獲得驗證前,不要發佈相關功能。

常見問題

沙盒測試足以批准追蹤 API 投入生產環境嗎?

不。沙盒可以驗證請求格式及部分故障處理,但需要使用真實貨件,才能評估實際路線上的承運商特定事件、時效及異常資料的實用性。兩者都應使用,並設定獨立的驗收標準。

我們應使用 webhook,還是輪詢追蹤更新?

根據供應商記錄的傳送選項及工作流程對延遲的容忍度作出決定。在支援 webhook 的情況下,它可以減少重複檢查的需要,但接收器仍需處理重試及重複通知。輪詢可以作為主要方式或恢復路徑,但須遵守記錄的限制。

映射追蹤狀態時最常見的錯誤是甚麼?

使用一個概括狀態,作為更具體業務聲明的觸發條件。例如,單憑已送達標籤可能不足以提供解決爭議所需的證明。應使用供應商實際提供的底層事件詳細資料來定義觸發條件。

誰應在上線前批准整合?

工程團隊應批准可靠性及安全性;營運或支援團隊應批准事件及異常工作流程的實用性;適當的私隱、法律及採購負責人應審查資料處理及商業條款。為任何仍未解決的問題指定一名具名負責人。

來源