建構驗證邏輯

本文說明如何建構地址檢查系統，處理 Address Validation API 的各種回應。內容涵蓋如何建構邏輯來正確使用回應、調查 API 的其他信號，以及何時和如何提示顧客提供更多資訊。

一般來說，API 回應會決定系統應以哪些方式處理地址：

• handyman 修正：地址品質不佳。 您應該提示使用者提供更多資訊。
• edit 確認：地址品質良好，但與輸入地址不同。系統可能會提示你確認。
• check 接受：地址品質良好。你可以接受系統提供的地址。

金鑰用途

這份文件可協助您修改系統，以便妥善分析 API 回應，並判斷如何處理提供的地址。以下虛擬程式碼說明可能的流程。

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

確切的邏輯取決於您的情況；詳情請參閱導入指南。您也可以使用這項邏輯的開放原始碼實作項目，位於擴充元件程式庫中。

工作流程總覽

下表摘要說明系統的兩項動作：

1. 根據修正、確認和接受行為使用的流程。
2. 從回應中檢查第一個信號。這裡所述的信號來自 verdict 屬性，並非唯一要檢查的信號，但可初步判斷地址品質。每種行為類型都對應至本文中的一個章節，說明您可能需要調查的其他信號。

系統行為
handyman 修正地址	verdict 的回覆指出缺少重要資訊，API 傳回的地址可能無法用於配送。 工作流程 視需要調查地址元件。 提示顧客修正地址問題。 要求驗證更新後的地址。 繼續使用該地址。 判定結果信號 符合下列任一情況： validationGranularity 設為 OTHER。 addressComplete 為 false。
edit 確認地址	verdict 的回應指出可遞送的地址，但已變更原始輸入內容：推斷資料 (拼字修正或可確認的資料)。 工作流程 需要修正： 視需要調查地址元件。 要求驗證更新後的地址。 繼續使用該地址。 不需要修正： 繼續使用該地址。 判定結果信號 符合下列所有條件： validationGranularity 包含 ROUTE addressComplete 為 true。 hasInferredComponents 欄位為 true 或 hasReplacedComponents 欄位為 true。
check 接受地址	Address Validation API 回應指出地址品質優良。 工作流程 繼續使用退回的地址。 判定結果信號 符合下列所有條件： validationGranularity 包含 PREMISE 或更高版本。 addressComplete 為 true。 無推斷或取代的元件。

實作指南

設計系統如何回應地址驗證信號時，建議您參考下列做法，建立更有效的回應模型。不過，這些只是建議，請注意，您的實作方式應符合您的業務模式。

	指引	詳細資料
風險等級	在提示修正和接受輸入地址之間取得平衡時，請考量您情況的容許程度。	Address Validation API 會傳回各種信號，您可以將這些信號與風險等級結合，進一步調整驗證程序。 舉例來說，如果地址的街道號碼未經確認，您仍可接受該地址。另一方面，如果你的業務營運需要更精確的地址，可以提示使用者。如需可能屬於任一類別的示例，請參閱「接受地址 - 示例」中的「非美國未確認的街道號碼」。
接受地址	如果顧客沒有回應提示，建議系統接受原始輸入內容。	在這種情況下，客戶可能輸入了系統中沒有的地址，例如新建築的地址。

修正地址

如果結果明確指出地址無法送達，請修正地址。接著，系統會提示消費者提供必要資訊，然後您重新發出工作流程，取得可送達的地址。

修正信號

Address Validation API 提供多項信號，可判斷地址是否需要修正。

1. 驗證精細度和缺少的元件

這兩項信號最能指出地址有問題：

• 每當 validationGranularity 欄位為 OTHER 時，系統應調查地址元件信號，進一步瞭解發生錯誤的位置和修正方式。
• 每當後續處理的 address 物���傳回 missingComponentTypes 欄位時，系統應檢查該元件。 如果缺少任何元件，地址就會不完整，導致無法投遞。

2. 其他指標

Address Validation API 也提供其他信號，協助診斷特定問題：

可疑元件	如果元件的確認層級列舉為 UNCOMFIRMED_AND_SUSPICIOUS，元件可能不正確。
未解決的元件	unresolvedToken 是輸入內容的一部分，但系統無法辨識為地址的有效部分。

3. 美國地址信號

某些僅適用於美國地址的欄位會提供實用信號，指出地址無法遞送，應予以修正。如果地址需要修正，您應該會看到以下訊息：

dpvConfirmation	可以是 N、D 或空白。

如要瞭解 dpvConfirmation 的詳細資料，請參閱「處理美國地址」。

地址修正範例

確認地址

當結果顯示 Address Validation API 推斷或變更地址元件，以產生驗證地址時，您即可確認地址。在這些情況下，您有可遞送的地址，但希望結果地址是顧客預期的地址，因此需要更高的信心。

為向消費者提供正確提示，您的邏輯會識別服務標記的元件，判斷 API 對元件套用的動作或標記，例如 inferred、replaced 或 spellCorrected。請參閱參考資料中的 AddressComponent。

確認信號

Address Validation API 提供多項信號，可判斷地址是否應確認。

1. 驗證精細程度

validationGranularity ROUTE 或以上即可接受，但 PREMISE 或 SUBPREMISE 可提供更強的送達率訊號。

2. 其他指標

決定是否要請顧客確認輸入的地址時，判決結果也會提供下列資訊，協助您判斷要調查哪些元件：

推論資料	如果 hasInferredComponents 欄位為 true，表示 API 已填入從其他地址元件擷取的資訊。
已取代的資料	如果 hasReplacedComponents 欄位為 true，表示 API 已將輸入的資料替換為系統認為可讓地址有效的資料。

3. 美國地址信號

某些僅適用於美國地址的欄位表示，您的邏輯應與顧客確認詳細資料。符合下列任一條件：

dpvConfirmation	S 如要瞭解 dpvConfirmation 的詳細資料，請參閱「處理美國地址」。
地址回應	包含 missingComponentTypes 欄位，值為 subpremise。

確認地址範例

接受地址

當判決結果高度確信地址可送達，且可在下游程序中使用，不需進一步與顧客互動時，您就會接受該地址。

接受信號

Address Validation API 提供多項信號，可判斷地址是否應確認。

1. 驗證精細程度

validationGranularity 為 PREMISE 以上即可接受，但在某些情況下，ROUTE 仍表示可送達的地址。

2. 其他指標

高品質地址的判決結果也應提供下列資訊：

• 沒有取代的資料。在這種情況下，hasReplacedComponents: FALSE。
• 沒有推斷的元件。在這種情況下，hasInferredComponents: FALSE。

3. 美國地址信號

僅適用於美國地址的特定欄位，表示可送達的高品質地址。如果美國地址符合規定，您應該會看到以下內容：

dpvConfirmation	Y 如要瞭解 dpvConfirmation 的詳細資料，請參閱「處理美國地址」。

可接受的地址範例