本文档介绍了构建地址检查系统以处理 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.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，则表示地址缺少单元号。
|
|---|---|
| USPS DPV 确认 | 如果 uspsData.dpvConfirmation 为 S，则表示地址的主要号码已与 USPS 数据库中的地址匹配。不过，地址还应包含辅助号码。此字段仅适用于美国地址。如需详细了解 uspsData.dpvConfirmation，请参阅处理美国地址。
|
CONFIRM 信号
如果判定结果表明 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 API 响应非常确信地址可送达且可以在下游流程中使用，您可以接受该地址。
除了 verdict.possibleNextAction 之外，您还可以使用 Address Validation API 响应的以下字段来确定地址的质量是否可接受。
| 验证粒度 | validationGranularity 值为 PREMISE 通常是可接受的，但值为 ROUTE 可能仍表示可投放的地址。
|
|---|---|
| 未推断出任何数据 | 当 hasInferredComponents 字段为 false 时，您就知道输出中没有推断出任何组件。
|
| 没有替换的数据 | 当 hasReplacedComponents 字段为 false 时，您就知道没有任何输入数据被替换。
|
| 不进行拼写更正 | 当 hasSpellCorrectedComponents 字段为 false 时，您就知道系统未进行任何拼写更正。
|
| USPS DPV 确认 | 如果 uspsData.dpvConfirmation 为 Y，则表示该地址与 USPS 数据库中的地址匹配。此字段仅适用于美国地址。如需详细了解 uspsData.dpvConfirmation，请参阅处理美国地址。
|