Создайте свою логику проверки

В этом документе описывается процесс создания системы проверки адресов для обработки различных ответов от 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 . Рекомендуется запросить у клиента дополнительную информацию.

Рабочий процесс

  1. При необходимости проверьте компоненты адреса.
  2. Предложите клиенту исправить ошибки в адресе.
  3. Запросите подтверждение обновленного адреса.
  4. (Необязательно) Отправьте запрос на конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» .
  5. Продолжите, указав адрес.
Добавить подобъект

В ответе на verdict указывается, что в адресе может отсутствовать информация о подобъекте. Например, verdict.possibleNextAction — CONFIRM_ADD_SUBPREMISES . Рекомендуется предложить клиенту добавить номер помещения.

Рабочий процесс

  1. Предложите клиенту указать номер устройства.
  2. Запросите подтверждение обновленного адреса.
  3. (Необязательно) Отправьте запрос на конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» .
  4. Продолжите, указав адрес.
Подтвердите адрес

В решении verdict указано, что могут быть незначительные проблемы с адресом. Например, verdict.possibleNextAction — CONFIRM . Рекомендуется предложить клиенту проверить адрес.

Рабочий процесс

  1. Необходимы исправления:
    1. При необходимости проверьте компоненты адреса.
    2. Запросите подтверждение обновленного адреса.
    3. (Необязательно) Отправьте запрос на конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» .
    4. Продолжите, указав адрес.
  2. Исправления не требуются:
    1. (Необязательно) Отправьте запрос на конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» .
    2. Продолжите, указав адрес.
Принять адрес».

verdict решение указывает на то, что с адресом, возможно, проблем нет. Например, verdict.possibleNextAction — ACCEPT . Рассмотрите возможность дальнейшего использования адреса в соответствии с вашим уровнем риска.

Рабочий процесс

Продолжите, указав обратный адрес.

Настройте логику проверки.

Хотя вы можете использовать результаты из поля verdict.possibleNextAction для определения того, как ваша система будет обрабатывать ответ API, вы также можете рассмотреть возможность создания собственной логики, например, для обработки специфических бизнес-задач.

Цель этого раздела — показать, как можно разработать собственную логику интерпретации ответа API, чтобы определить, следует ли и как именно выводить запрос клиенту. В этом разделе рассматриваются уровни риска и дополнительные сигналы ответа API, которые следует учитывать при настройке.

Тем не менее, даже если вы полагаетесь исключительно на verdict.possibleNextAction при принятии решения о дальнейших шагах, дополнительные сигналы, описанные ниже, все равно могут помочь вам понять подробности о потенциальных проблемах с адресом.

толерантность к риску

При проектировании того, как ваша система реагирует на сигналы от API проверки адресов, следующие рекомендации помогут вам создать более эффективную модель реагирования. Однако это лишь рекомендации, поэтому имейте в виду, что ваша реализация должна соответствовать вашей бизнес-модели.

Руководство Подробности
Уровень риска

При выборе между запросом на исправление и принятием введенного адреса в том виде, в котором он был введен, учитывайте допустимый уровень ошибок в вашей ситуации.

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

Исправьте адрес, если результаты ясно указывают на то, что доставка по этому адресу может быть невозможна. В этом случае ваша система может запросить у клиента необходимую информацию, после чего вы повторно запустите рабочий процесс для получения адреса, по которому возможна доставка.

Следующие поля ответа API проверки адреса могут использоваться в дополнение к verdict.possibleNextAction для определения наличия серьезных проблем с адресом и их характера.

Детализация проверки Если в перечислении с уровнем детализации проверки для адреса указано значение OTHER , то, скорее всего, адрес указан неверно.
Отсутствующие компоненты Если поле address.missingComponentTypes не пустое, вероятно, в адресе отсутствует ключевая информация.
Подозрительные компоненты Если для компонента в перечислении уровней подтверждения указано значение UNCONFIRMED_AND_SUSPICIOUS , то, скорее всего, компонент некорректен.
Неразрешенные компоненты UnresolvedToken — это часть входных данных, которая не распознается как допустимая часть адреса.
Подтверждение USPS DPV Если значение uspsData.dpvConfirmation равно N или пустое, это может указывать на проблему с адресом. Это поле доступно только для адресов в США. Для получения более подробной информации о поле uspsData.dpvConfirmation см. раздел «Обработка адресов в США» .

Примеры исправленных адресов

Сигналы CONFIRM_ADD_SUBPREMISES (только для адресов в США)

Вы предлагаете клиенту проверить адрес и рассмотреть возможность добавления номера помещения, если ответ API проверки адреса указывает на то, что в адресе может отсутствовать информация о дочернем помещении. В таких случаях адрес здания , вероятно, верен, но вам нужна большая уверенность в том, что полученный адрес соответствует замыслу клиента.

Следующие поля ответа API проверки адреса могут использоваться в дополнение к verdict.possibleNextAction для определения вероятности отсутствия дочернего объекта в адресе.

Missing subpremise component Если поле address.missingComponentTypes содержит значение subpremise , это указывает на то, что в адресе отсутствует номер объекта.
Подтверждение USPS DPV Если значение uspsData.dpvConfirmation равно S , это означает, что основной номер адреса был сопоставлен с адресом в базе данных USPS. Однако ожидалось, что адрес будет содержать и дополнительный номер. Это поле доступно только для адресов в США. Для получения более подробной информации о поле uspsData.dpvConfirmation см. раздел «Обработка адресов в США» .

Добавить примеры адресов суб-помещений

ПОДТВЕРДИТЬ сигналы

Подтверждение адреса происходит, когда результат проверки показывает, что API проверки адресов либо предположил адрес, либо внес изменения в его компоненты для получения проверенного адреса. В таких случаях у вас есть адрес, пригодный для доставки, но вы предпочитаете быть уверенными, что полученный адрес соответствует замыслу клиента.

Следующие поля ответа API проверки адреса могут использоваться в дополнение к verdict.possibleNextAction для определения наличия незначительных проблем в адресе и их характера.

Детализация проверки Если для адреса validationGranularity имеет значение ROUTE или PREMISE_PROXIMITY , адрес может быть указан неверно.
Предполагаемые данные Если поле hasInferredComponents имеет true , это означает, что API заполнил информацию, полученную из других компонентов адреса.
Заменены данные Если поле hasReplacedComponents имеет true , API заменяет введенные данные данными, которые, по его мнению, делают адрес действительным.
Исправление орфографических ошибок Если поле hasSpellCorrectedComponents имеет true , API исправляет орфографические ошибки в некоторых компонентах.

Примеры подтверждения адреса

ПРИНИМАТЬ сигналы

Вы можете принять адрес, если ответ API проверки адреса с высокой степенью уверенности подтверждает, что адрес пригоден для доставки и может быть использован без дальнейшего взаимодействия с клиентом в последующих процессах.

Следующие поля ответа API проверки адреса могут использоваться в дополнение к verdict.possibleNextAction для определения того, соответствует ли адрес приемлемому качеству.

Детализация проверки validationGranularity равное PREMISE часто является приемлемым, хотя значение ROUTE все еще может указывать на адрес, по которому возможна доставка.
Нет косвенных данных Если поле hasInferredComponents имеет значение false , это означает, что ни один компонент в выходных данных не был выведен автоматически.
Замененные данные отсутствуют Если поле hasReplacedComponents имеет значение false , это означает, что никакие входные данные не были заменены.
Исправления орфографии не требуются Если поле hasSpellCorrectedComponents имеет значение false , это означает, что исправления заклинаний не были внесены.
Подтверждение USPS DPV Если значение uspsData.dpvConfirmation равно Y , это означает, что адрес был сопоставлен с адресом в базе данных USPS. Это поле доступно только для адресов в США. Для получения более подробной информации о поле uspsData.dpvConfirmation см. раздел «Обработка адресов в США» .

Примеры адресов для приема