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

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

В целом ответ API определяет следующие способы, которыми ваша система должна обрабатывать адрес:

• Fix — адрес может содержать существенные проблемы.
  Подумайте о том, чтобы попросить клиента предоставить вам дополнительную информацию.
• Добавить подпредпосылки — в адресе может отсутствовать подпредпосылка.
  Подумайте о том, чтобы предложить клиенту добавить номер единицы товара.
• Подтвердить — адрес может содержать незначительные проблемы.
  Попросите клиента подтвердить правильность адреса.
• «Принять » — адрес может не содержать проблем.
  Рассмотрите возможность использования адреса без дополнительных указаний, на свой страх и риск.

Основная цель

Этот документ поможет вам модифицировать систему для наилучшего анализа ответа 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. См. раздел Обработка обновлённых адресов . Продолжайте с адресом.
Подтвердите адрес	The response from the verdict indicates there might be minor issues with the address. For example, verdict.possibleNextAction is CONFIRM . Consider prompting your customer to review the address. Рабочий процесс Необходимые исправления: При необходимости проверьте компоненты адреса. Запросите подтверждение обновленного адреса. (Необязательно) Отправьте запрос в конечную точку обратной связи для API. См. раздел Обработка обновлённых адресов . Продолжайте с адресом. Исправления не требуются: (Необязательно) Отправьте запрос в конечную точку обратной связи для API. См. раздел Обработка обновлённых адресов . Продолжайте с адресом.
Принять адрес	Ответ verdict указывает на то, что с адресом, возможно, проблем нет. Например, verdict.possibleNextAction — ACCEPT . Рассмотрите возможность использования адреса, как если бы вы использовали его для своего уровня риска. Рабочий процесс Продолжайте с обратным адресом.

Note: When you repeat requests to the Address Validation API for the same address, you can make a call to provideValidationFeedback to indicate your outcome. See Handle updated addresses .

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

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

Хотя вы можете использовать результаты поля 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.

ИСПРАВИТЬ сигналы

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

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

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

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

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

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

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

Missing subpremise component	Если поле address.missingComponentTypes содержит значение subpremise , это означает, что в адресе отсутствует номер объекта. Примечание : если поле содержит типы, отличные от subpremise , действие будет относиться к категории FIX. Полный список типов компонентов см. в документации по геокодированию.
Подтверждение DPV USPS	Если значение поля 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 , это означает, что исправления заклинаний не производились.
Подтверждение DPV USPS	Если значение uspsData.dpvConfirmation равно Y , это означает, что адрес сопоставлен с адресом в базе данных USPS. Это поле доступно только для адресов в США. Подробнее об uspsData.dpvConfirmation см. в разделе Обработка адресов в США .

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