建構驗證邏輯

本文說明如何建構地址檢查系統，處理 Address Validation API 的各種回應。本文說明如何解讀 API 回應，判斷何時及如何提示顧客提供更多資訊。

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

• 修正：地址可能含有重大問題。
  考慮要求顧客提供更多資訊。
• 新增子處所：地址可能缺少子處所。
  考慮提示顧客新增單位編號。
• 確認：地址可能含有小問題。
  考慮提示顧客確認地址是否正確。
• 接受：地址可能沒有問題。
  請自行斟酌是否要使用該地址，並自行承擔風險。

金鑰用途

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

if (verdict.possibleNextAction == FIX)
    Prompt the user to fix the address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
    Prompt the user to add a unit number.
else if (verdict.possibleNextAction == CONFIRM)
    Confirm with the user that the address is correct.
else
    Continue with the address returned by the API.

確切的邏輯取決於您的情況，詳情請參閱「自訂驗證邏輯」。

工作流程範例

下表摘要說明您可以實作的範例工作流程，根據 API 回應提示顧客。

系統行為
修正地址	verdict 的回覆指出地址可能存在重大問題。舉例來說，verdict.possibleNextAction 為 FIX。請考慮提示顧客提供更多資訊。 工作流程 視需要調查地址元件。 提示顧客修正地址問題。 要求驗證更新後的地址。 (選用) 將要求傳送至 API 的意見回饋端點。 請參閱「處理更新後的地址」。 繼續使用該地址。
新增子場所	verdict 的回應指出地址可能缺少子場所。舉例來說，verdict.possibleNextAction 為 CONFIRM_ADD_SUBPREMISES。建議提示顧客新增單元編號。 工作流程 提示顧客新增單位編號。 要求驗證更新後的地址。 (選用) 將要求傳送至 API 的意見回饋端點。 請參閱「處理更新後的地址」。 繼續使用該地址。
確認地址	verdict 的回覆指出地址可能有些小問題。舉例來說，verdict.possibleNextAction 為 CONFIRM。建議提示顧客檢查地址。 工作流程 需要修正： 視需要調查地址元件。 要求驗證更新後的地址。 (選用) 將要求傳送至 API 的意見回饋端點。 請參閱「處理更新後的地址」。 繼續使用該地址。 不需要修正： (選用) 將要求傳送至 API 的意見回饋端點。 請參閱「處理更新後的地址」。 繼續使用該地址。
接受地址	verdict 的回應指出地址可能沒有問題。舉例來說，verdict.possibleNextAction 為 ACCEPT。請根據風險等級，決定是否要繼續使用該地址。 工作流程 繼續使用退回的地址。

注意： 針對相同地址重複向 Address Validation API 發出要求時，您可以呼叫 provideValidationFeedback 來指出結果。請參閱「處理更新後的地址」。

立即試用。 本文的其餘部分會提供各種範例，協助您瞭解上述的修正、確認及接受流程。如要查看這些範例的結果，請在 Address Validation API 試用版中輸入範例。

自訂驗證邏輯

雖然您可以使用 verdict.possibleNextAction 欄位的結果，判斷系統如何處理 API 回應，但您也可以考慮建構自訂邏輯，例如處理特定業務需求。

本節旨在說明如何開發自訂邏輯來解讀 API 回應，以判斷是否要提示顧客，以及提示方式。本節將說明風險等級，以及可納入自訂作業考量的其他 API 回應信號。

也就是說，即使您只依賴 verdict.possibleNextAction 決定後續步驟，以下說明的額外信號仍可協助您瞭解地址潛在問題的詳細資料。

風險容忍度

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

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

風險規避結帳流程範例

如要降低遞送失敗的風險，可以自訂邏輯，更常提示顧客。舉例來說，您可以改用下列邏輯，而非「主要用途」一節所述的邏輯。

if (verdict.possibleNextAction == FIX or verdict.validationGranularity
== OTHER or verdict.validationGranularity == ROUTE)
  Prompt customer to fix their address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
  Prompt customer to add a unit number.
else if (verdict.possibleNextAction == CONFIRM or verdict.validationGranularity
== PREMISE_PROXIMITY or verdict.hasSpellCorrectedComponents or
verdict.hasReplacedComponents or verdict.hasInferredComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

低摩擦係數結帳流程範例

如要減少結帳流程中的阻礙，您可以自訂邏輯，降低向消費者顯示提示的頻率。舉例來說，您可以改用下列邏輯，而非「主要用途」一節所述的邏輯。

if (verdict.possibleNextAction == FIX)
  Prompt customer to fix their address.
else if (verdict.hasReplacedComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

FIX 信號

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

除了 verdict.possibleNextAction 之外，您也可以使用 Address Validation API 回應中的下列欄位，判斷地址是否有重大問題，以及問題為何。

驗證精細程度	如果地址的驗證細微程度列舉為 OTHER，則地址可能不正確。
缺少元件	如果 address.missingComponentTypes 不是空白，則地址可能缺少重要資訊。
可疑元件	如果元件的確認層級列舉為 UNCONFIRMED_AND_SUSPICIOUS，元件可能不正確。
未解決的元件	unresolvedToken 是輸入內容的一部分，但系統無法辨識為地址的有效部分。
USPS DPV 確認	如果 uspsData.dpvConfirmation 為 N 或空白，地址可能會有問題。這個欄位僅適用於美國地址。如要進一步瞭解 uspsData.dpvConfirmation，請參閱處理美國地址。

地址修正範例

CONFIRM_ADD_SUBPREMISES 信號 (僅限美國地址)

當 Address Validation API 回應指出地址可能缺少子場所時，請提示顧客檢查地址，並考慮新增單位號碼。在這種情況下，建築物的地址可能有效，但您希望更有把握結果地址是顧客想要的地址。

除了 verdict.possibleNextAction 之外，您也可以使用 Address Validation API 回應中的下列欄位，判斷地址是否可能缺少子處所。

Missing subpremise component	如果 address.missingComponentTypes 欄位包含 subpremise 值，表示地址缺少門牌號碼。 注意：如果欄位包含 subpremise 以外的型別，動作會歸類為「修正」類別。如要查看完整的元件類型清單，請參閱 Geocoding 說明文件。
USPS DPV 確認	如果 uspsData.dpvConfirmation 為 S，表示地址的主要號碼已與 USPS 資料庫中的地址相符。不過，地址應包含次要號碼。這個欄位僅適用於美國地址。如要進一步瞭解 uspsData.dpvConfirmation，請參閱「處理美國地址」。

新增子處所地址範例

確認信號

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

除了 verdict.possibleNextAction 之外，您也可以使用 Address Validation API 回應中的下列欄位，判斷地址是否有小問題，以及問題為何。

驗證精細程度	如果地址的 validationGranularity 為 ROUTE 或 PREMISE_PROXIMITY，表示地址可能不正確。
推論資料	如果 hasInferredComponents 欄位為 true，表示 API 填入的資訊是從其他地址元件擷取而來。
已取代的資料	如果 hasReplacedComponents 欄位為 true，API 會將輸入的資料替換為系統認為可讓地址有效的資料。
拼字修正	如果 hasSpellCorrectedComponents 欄位為 true，API 會修正部分拼字錯誤的元件。

確認地址範例

ACCEPT 信號

如果 Address Validation API 回應高度確信地址可送達，且可在下游程序中使用，不必與顧客進一步互動，您或許可以接受該地址。

注意： 決定是否接受地址或要求顧客提供更多資訊時，請考量風險程度。

除了 verdict.possibleNextAction 之外，您也可以使用 Address Validation API 回應中的下列欄位，判斷地址是否符合可接受的品質。

驗證精細程度	validationGranularity 的 PREMISE 通常可以接受，但 ROUTE 值仍可能表示可送達的地址。
沒有推論資料	如果 hasInferredComponents 欄位為 false，表示輸出內容中沒有推斷的元件。
沒有取代的資料	如果 hasReplacedComponents 欄位為 false，表示沒有輸入資料遭到取代。
沒有拼字修正建議	如果 hasSpellCorrectedComponents 欄位為 false，表示系統未進行任何拼字修正。
USPS DPV 確認	如果 uspsData.dpvConfirmation 為 Y，表示地址已與 USPS 資料庫中的地址相符。這個欄位僅適用於美國地址。如要進一步瞭解 uspsData.dpvConfirmation，請參閱「處理美國地址」。

可接受的地址範例