В этом документе описывается процесс создания системы проверки адресов, которая может обрабатывать различные ответы от Address Validation API. Вы узнаете, как правильно использовать ответ, изучать другие сигналы от API, а также когда и как запрашивать у клиентов дополнительную информацию.
В целом ответ API определяет, как ваша система должна обрабатывать адрес:
- Исправить – адрес низкого качества. Запросите дополнительную информацию.
- Подтвердить – адрес высокого качества, но отличается от введенного. Вы можете запросить подтверждение.
- Принять – адрес высокого качества. Вы можете принять предложенный адрес.
Основная цель
В этом документе рассказывается, как изменить систему, чтобы лучше анализировать ответы API и определять, что делать с предоставленными адресами. Ниже приведен пример псевдокода.
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
Точная логика зависит от вашей ситуации. Подробную информацию вы найдете в руководстве по реализации. Вы также можете использовать нашу реализацию этой логики с открытым исходным кодом, которая находится в расширенной библиотеке компонентов.
Обзор рабочего процесса
В таблице ниже приведены два действия для вашей системы:
- Рабочий процесс, основанный на исправлении, подтверждении и принятии.
- Первые сигналы, которые нужно проверить в ответе. Описанные здесь сигналы поступают из свойства
verdict. Это не единственные сигналы, которые нужно проверять, но они дают первоначальное представление о качестве адреса. Каждому типу поведения соответствует раздел в этом документе, в котором описываются дополнительные сигналы, которые вам также может потребоваться исследовать.
| Поведение системы | |||
|---|---|---|---|
| Исправить адрес |
Ответ от
|
||
| Подтвердить адрес |
Ответ от
|
||
| Принять адрес |
Ответ Address Validation API указывает на отличное качество адреса.
|
||
Советы по размещению рекламы
При разработке системы реагирования на сигналы Address Validation следующие рекомендации помогут вам создать более эффективную модель реагирования. Однако это лишь рекомендации, и вы можете выбрать другой вариант, который лучше подходит для вашей бизнес-модели.
| Рекомендации | Подробнее… | |
|---|---|---|
| Уровень риска |
Принимая решение о том, стоит ли предлагать исправления или принять адрес в том виде, в котором он был введен, учитывайте уровень допустимости для вашей ситуации. |
Address Validation API возвращает различные сигналы, которые вы можете использовать вместе с уровнем риска, чтобы оптимизировать процесс проверки. Например, если в адресе не подтвержден номер дома, вы все равно можете принять его. Если же для вашей коммерческой деятельности требуется более точный адрес, вы можете запросить его у пользователя. Пример, который может относиться к любой из этих категорий, приведен в разделе Неподтвержденный номер дома за пределами США статьи Примеры принятия адресов. |
| Принять адреса |
Рекомендуется настроить систему так, чтобы она принимала исходный вариант, если клиент не отвечает на подсказки. |
В таких случаях клиент мог ввести адрес, которого нет в системе, например адрес нового здания. |
Исправить адрес
Исправьте адрес, если результаты явно указывают на то, что он недействителен. В этом случае ваша система может предложить клиенту предоставить необходимую информацию, после чего вы повторно запустите рабочий процесс, чтобы получить адрес доставки.
Исправить сигналы
Address Validation API предоставляет ряд сигналов, позволяющих узнать, нужно ли исправить адрес.
1. Детализация проверки и отсутствующие компоненты
О проблемах с адресом свидетельствуют два основных сигнала:
- Если поле
validationGranularityимеет значениеOTHER, ваша система должна проанализировать сигналы компонентов адреса, чтобы узнать больше о том, где произошла ошибка и как ее исправить. - Если обработанный объект
addressвозвращает полеmissingComponentTypes, ваша система должна проверить этот компонент. Если в адресе отсутствуют какие-либо компоненты, он считается неполным и доставка по нему невозможна.
2. Другие сигналы
Address Validation API также предоставляет другие сигналы, помогающие диагностировать конкретные проблемы:
| Подозрительные компоненты | Если для компонента возвращается значение перечисления уровня подтверждения UNCOMFIRMED_AND_SUSPICIOUS, скорее всего, он указан неверно.
|
|---|---|
| Неразрешенный компонент | unresolvedToken – часть входных данных, которая не распознана как действительная часть адреса. |
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, содержат полезный сигнал о том, что адрес не может быть доставлен и должен быть исправлен. Для адреса, который требует исправления, вы должны увидеть следующее:
dpvConfirmation
|
N, D или пустое значение.
|
|---|
Подробнее о dpvConfirmation читайте в статье Как обрабатывать адреса в США.
Как подтвердить адрес
Подтверждение адреса требуется, если в заключении указано, что Address Validation API вывел или изменил компоненты адреса, чтобы получить подтвержденный адрес. В таких случаях у вас есть адрес, на который можно доставить посылку, но вы хотите быть уверены, что он совпадает с тем, который указал клиент.
Чтобы предоставить клиенту правильную подсказку, ваша логика должна идентифицировать компоненты, помеченные сервисом, и определить, какое действие или пометку API применил к компоненту, например inferred, replaced или spellCorrected.
Подробную информацию вы найдете в разделе AddressComponent справочника.
Подтвердить сигналы
Address Validation API предоставляет ряд сигналов, позволяющих определить, нужно ли подтверждать адрес.
1. Детализация проверки
Допустимо значение validationGranularity, равное ROUTE или выше, но PREMISE или SUBPREMISE обеспечивают более надежную доставку.
2. Другие сигналы
Если вы решите подтвердить адрес у клиента, вердикт также предоставит следующие данные, чтобы определить, какие компоненты следует проверить:
| Предполагаемые данные | Если поле
hasInferredComponents имеет значение true, это означает, что API заполнил информацию, полученную из других компонентов адреса.
|
|---|---|
| Замененные данные | Если поле
hasReplacedComponents имеет значение true, API заменяет введенные данные на те, которые считает правильными.
|
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, указывают на то, что ваша логика должна подтверждать данные у клиента. Выполняется одно из следующих условий:
dpvConfirmation
|
S
Подробные сведения о |
|---|---|
| Ответ на адрес | Содержит поле missingComponentTypes со значением subpremise.
|
Как принять адрес
Вы принимаете адрес, если вердикт дает высокую степень уверенности в том, что адрес является доставляемым и может использоваться без дальнейшего взаимодействия с клиентом в последующем процессе.
Принимать сигналы
Address Validation API предоставляет ряд сигналов, позволяющих определить, нужно ли подтверждать адрес.
1. Детализация проверки
Значение validationGranularity, равное PREMISE или выше, считается приемлемым, но в некоторых случаях значение ROUTE также указывает на то, что адрес существует.
2. Другие сигналы
Для адреса высокого качества также должны быть указаны следующие данные:
- Данные не заменяются. В этом случае
hasReplacedComponents: FALSE. - Нет предполагаемых компонентов. В этом случае
hasInferredComponents: FALSE.
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, указывают на высокое качество адреса, по которому можно доставить посылку. Для допустимого адреса в США вы должны увидеть следующее:
dpvConfirmation
|
Y
Подробнее о
|
|---|