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

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

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

Попробуйте демо. В остальной части этого документа используются различные примеры, которые помогут вам понять процесс исправления, подтверждения, принятия, описанный выше. Вы можете изучить результаты этих примеров, введя их в демонстрационную версию 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 см. Обработка адресов в США .

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