构建验证逻辑

本文档介绍了一种构建地址检查系统的流程，该系统可处理 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 来决定后续步骤，下文所述的其他信号仍可帮助您了解地址可能存在的问题的详细信息。

风险容忍度

在设计系统如何响应地址验证 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 之外，地址验证 API 响应的以下字段也可用于确定地址是否存在重大问题以及具体存在哪些问题。

验证粒度	如果地址的验证粒度枚举为 OTHER，则该地址很可能不正确。
缺少组件	如果 address.missingComponentTypes 不为空，则表示地址可能缺少关键信息。
可疑组件	如果某个组件的确认级别枚举为 UNCONFIRMED_AND_SUSPICIOUS，则该组件很可能不正确。
未解析的组件	unresolvedToken 是输入中未被识别为有效地址组成部分的部分。
USPS DPV 确认	当 uspsData.dpvConfirmation 为 N 或空时，地址可能存在问题。此字段仅适用于美国地址。如需详细了解 uspsData.dpvConfirmation，请参阅处理美国地址。

地址修正示例

CONFIRM_ADD_SUBPREMISES 信号（仅限美国地址）

当地址验证 API 响应表明地址可能缺少子场所时，您会提示客户检查地址，并考虑添加单元号。在这些情况下，建筑物的地址可能有效，但您希望更有把握地确定生成的地址是客户想要的地址。

除了 verdict.possibleNextAction 之外，还可以使用地址验证 API 响应的以下字段来确定地址是否可能缺少子地址。

Missing subpremise component	如果 address.missingComponentTypes 字段包含值 subpremise，则表示地址中缺少单元号。 注意：如果该字段包含除 subpremise 以外的类型，相应操作将归入 FIX 类别。如需查看组件类型的完整列表，请参阅地理编码文档。
USPS DPV 确认	当 uspsData.dpvConfirmation 为 S 时，表示地址的主要编号已与 USPS 数据库中的某个地址相匹配。不过，该地址还应包含一个辅助号码。此字段仅适用于美国地址。如需详细了解 uspsData.dpvConfirmation，请参阅处理美国地址。

添加子场所地址示例

CONFIRM 信号

当判决结果表明 Address Validation API 推断或更改了地址组成部分以生成经过验证的地址时，您需要确认地址。在这些情况下，您拥有可送达的地址，但希望更有把握地确定生成的地址是客户想要的地址。

除了 verdict.possibleNextAction 之外，您还可以使用地址验证 API 响应的以下字段来确定地址是否存在次要问题以及这些问题是什么。

验证粒度	如果地址的 validationGranularity 为 ROUTE 或 PREMISE_PROXIMITY，则该地址可能不正确。
推断数据	当 hasInferredComponents 字段为 true 时，表示 API 填充了从其他地址组件中提取的信息。
替换数据	当 hasReplacedComponents 字段为 true 时，API 会将输入的数据替换为它认为可使地址有效的数据。
拼写更正	当 hasSpellCorrectedComponents 字段为 true 时，API 会更正某些拼写错误的组件的拼写。

确认地址示例

ACCEPT 信号

如果地址验证 API 响应高度确信地址可送达，并且可以在下游流程中直接使用，无需进一步的客户互动，您就可以接受该地址。

注意： 在决定是否接受地址或提示客户提供更多信息时，请考虑您的风险承受能力。

除了 verdict.possibleNextAction 之外，还可以使用地址验证 API 响应的以下字段来确定地址质量是否可接受。

验证粒度	validationGranularity 为 PREMISE 通常是可以接受的，但值为 ROUTE 可能仍表示可送达的地址。
无推断数据	当 hasInferredComponents 字段为 false 时，表示输出中没有推断出的组件。
无替换数据	当 hasReplacedComponents 字段为 false 时，表示没有输入数据被替换。
不进行拼写更正	当 hasSpellCorrectedComponents 字段为 false 时，表示未进行任何拼写更正。
USPS DPV 确认	当 uspsData.dpvConfirmation 为 Y 时，表示该地址已与 USPS 数据库中的地址匹配。此字段仅适用于美国地址。如需详细了解 uspsData.dpvConfirmation，请参阅处理美国地址。

可接受的地址示例