Обзор
При подтверждении адреса (POA) в массивеpoa_verifications[].warnings[] формируются предупреждения для каждой проблемы с качеством, подлинностью или совпадением данных, обнаруженной во время извлечения и форензик-анализа. Каждое предупреждение представляет собой объект предупреждения, в котором поле feature имеет значение "PROOF_OF_ADDRESS". Несколько рисков всегда принудительно переводят статус в Declined; остальные следуют действию для конкретного риска (DECLINE / REVIEW / NO_ACTION), настроенному в вашем сценарии.
Каждый приведенный ниже риск проверен на рабочем пайплайне принятия решений; точные строки краткого и подробного описания приведены в таблицах дословно.
Извлечение данных POA занимает 5–15 секунд на один документ. Предупреждения записываются только после завершения шага сценария; не опрашивайте endpoint чаще, чем раз в 5 секунд.
Два пути в продакшн-среде
Предупреждения POA формируются двумя разными путями, и набор рисков для них различается:- Сессии сценариев (шаг POA внутри сессии верификации) — endpoint загрузки сначала выполняет блокирующую валидацию с циклом повторных попыток (см. Повторные попытки), затем итоговые сохраняемые предупреждения вычисляются функцией
check_poa_risksвместе с проверкой имени по нескольким документам. - Отдельный API (
POST /v3/poa/) — предупреждения формируются только с помощьюcheck_poa_risks. Здесь нет цикла повторных попыток, нет контекста верифицированного удостоверения личности и используется только один документ, поэтому рискиNAME_MISMATCH_ID_VERIFICATION,POA_NAME_MISMATCH_BETWEEN_DOCUMENTS,POA_MAX_ATTEMPTS_EXCEEDEDиFUTURE_ISSUE_DATEникогда не формируются отдельным API. Ошибки предварительной валидации на этом пути отбрасываются.
POOR_DOCUMENT_QUALITY определен в перечислении рисков и зарезервирован в сопоставлении действий, но ни одна ветка кода в пайплайне POA его не генерирует — он никогда не появляется в warnings[] ни на одном из путей. Не создавайте ветвлений логики на его основе.
Предупреждения, приводящие к автоматическому отклонению (всегда устанавливают статус Declined)
Эти риски входят в AUTO_DECLINE_RISKS; при их фиксации статус POA всегда становится Declined независимо от настроек, а log_type всегда имеет значение error.
Риск
FUTURE_ISSUE_DATE также указан в AUTO_DECLINE_RISKS, но генерируется в единственном месте при предварительной валидации перед извлечением (дата выдачи более чем на 7 дней в будущем), ошибки которой передаются только в цикл повторных попыток сценария — там он отображается как блокирующая ошибка загрузки, никогда не генерируется отдельным API и не записывается в warnings[]. См. Повторные попытки.
Настраиваемые предупреждения
Каждое из этих предупреждений зависит от параметра действия в узле POA сценария (DECLINE / REVIEW / NO_ACTION). Поле log_type предупреждения соответствует настроенному действию: error для «Отклонить», warning для проверки и information для «Без действия».
Для всех несоответствий имени и адреса есть одно общее действие:
poa_name_or_address_mismatch_action охватывает оба риска, связанных с именем, оба риска, связанных с адресом, и проверку имён между документами. Настроить поведение при несоответствии имени и адреса отдельно нельзя. В отдельном API та же группа подчиняется параметру запроса poa_address_mismatch_action (параметр poa_name_mismatch_action принимается, но никогда не читается).Отличия автономного API (POST /v3/poa/)
Автономный endpoint использует такое же сопоставление рисков и действий, но с параметрами уровня запроса, принимающими только DECLINE или NO_ACTION (по умолчанию для всех установлено значение DECLINE):
UNABLE_TO_EXTRACT_ISSUE_DATEиPOA_NAME_NOT_DETECTEDна этом endpoint жёстко заданы как Отклонить.POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATIONиUNPARSABLE_OR_INVALID_ADDRESSздесь являются информационными — для них по умолчанию установлено действие «Не выполнять» и они не настраиваются для отдельного запроса.FUTURE_ISSUE_DATE,POOR_DOCUMENT_QUALITY,NAME_MISMATCH_ID_VERIFICATION,POA_NAME_MISMATCH_BETWEEN_DOCUMENTSиPOA_MAX_ATTEMPTS_EXCEEDEDникогда не формируются — документ с будущей датой не отклоняется автоматически на этом endpoint.
Поведение повторных попыток (сессии сценария)
В сессии верификации шаг загрузки POA выполняет блокирующую валидацию перед тем, как документ будет принят. Если обнаруживается блокирующая ошибка —INVALID_DOCUMENT_TYPE, UNABLE_TO_EXTRACT_ISSUE_DATE, FUTURE_ISSUE_DATE, POA_NAME_NOT_DETECTED, MISSING_ADDRESS_INFORMATION, POA_COUNTRY_MISMATCH_WITH_PROVIDED, POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION, UNSUPPORTED_DOCUMENT_LANGUAGE или POA_DOCUMENT_EXPIRED — загрузка отклоняется с кодом 400 и кодом риска в сообщении, и пользователь может повторить попытку с более подходящим документом.
Для POA_DOCUMENT_EXPIRED тело ответа 400 также включает expiration_reason (printed_expiration или age_window), чтобы ваш UI мог отобразить точную причину; для варианта age_window оно дополнительно содержит max_age_months. Для варианта printed_expiration параметр max_age_months намеренно опущен, так как документ был отклонён из-за напечатанного на нём срока действия, а не из-за окна давности.
Как только пользователь исчерпает попытки poa_max_retry_attempts (по умолчанию 2, настраивается от 2 до 5), отправка всё равно принимается: сохранённые предупреждения пересчитываются на основе сохранённого документа, добавляется POA_MAX_ATTEMPTS_EXCEEDED, а статус определяется по полному набору рисков. Именно поэтому FUTURE_ISSUE_DATE может блокировать загрузку, но никогда не появляется в warnings[].
Настраиваемые параметры
Узел POA в сценарии предоставляет следующие параметры (соответствующие полямVerificationSettings):
Логика сопоставления имён
Сопоставление имён в POA допускает распространённые вариации:- Вторые имена и инициалы сопоставляются мягко (их наличие или отсутствие допускается).
- Имена-кандидаты — оценивается каждое имя, обнаруженное в документе (
name_on_documentплюсadditional_names), и сохраняется кандидат с наивысшей оценкой. - Порог совпадения — значение по умолчанию для
poa_name_match_score_thresholdсоставляет 86; оценка ниже этого порога вызывает соответствующее предупреждениеNAME_MISMATCH*.
name_match_score_expected_details и name_match_score_id_verification (0–100). Значения оценок полезны для детальной проверки, даже если предупреждение не было создано.
Примеры
Манипуляция с наложением (по умолчанию Decline)
Документ с истекшим сроком действия + отсутствие адреса (автоматическое отклонение)
Несовпадение имени (по умолчанию Review)
Связанные разделы
- Отчёт по подтверждению адреса — полная структура ответа, экспертиза манипуляций с наложением, семантика статусов
- Обзор подтверждения адреса — поддерживаемые типы документов
- Модели данных — Подтверждение адреса — каноническая схема и объект Warning
- Webhooks — событие
status.updatedпередаёт предупреждения POA