Перейти к основному содержанию

Обзор

При подтверждении адреса (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.
Параметры запроса приведены в справочнике API POST /v3/poa/.

Поведение повторных попыток (сессии сценария)

В сессии верификации шаг загрузки 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)

Связанные разделы

Типы предупреждений

Последнее изменение 7 ноября 2026 г.