> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Предупреждения и коды ошибок подтверждения адреса > Коды предупреждений Didit при подтверждении адреса: несовпадение имени, истёкший документ и ошибки метаданных. Настройка автоотклонения. ## Обзор При подтверждении адреса (POA) в массиве `poa_verifications[].warnings[]` формируются предупреждения для каждой проблемы с качеством, подлинностью или совпадением данных, обнаруженной во время извлечения и форензик-анализа. Каждое предупреждение представляет собой [объект предупреждения](https://docs.didit.me/ru/reference/data-models.md#объект-предупреждения), в котором поле `feature` имеет значение `"PROOF_OF_ADDRESS"`. Несколько рисков всегда принудительно переводят статус в `Declined`; остальные следуют действию для конкретного риска (`DECLINE` / `REVIEW` / `NO_ACTION`), настроенному в вашем сценарии. Каждый приведенный ниже риск проверен на рабочем пайплайне принятия решений; точные строки краткого и подробного описания приведены в таблицах дословно. > [!NOTE] > > Извлечение данных 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`. | Риск | Причина | Рекомендуемое решение | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Из документа не удалось извлечь адрес. | Попросите пользователя повторно отправить документ, в котором четко виден его адрес. | | `POA_DOCUMENT_EXPIRED` | Срок действия документа истек по одному из двух путей: истёк его **напечатанный срок действия** или он **старше настроенного максимального возраста** для этого типа документа. Значения по умолчанию: **3 месяца** для `UTILITY_BILL` и `BANK_STATEMENT`, **12 месяцев** для `GOVERNMENT_ISSUED_DOCUMENT` и `OTHER_POA_DOCUMENT` (месяц считается как 30 дней; `-1` отключает проверку). Объект `additional_data` всегда содержит `expiration_reason` (`printed_expiration` или `age_window`), `document_type`, `document_subtype` и `issue_date`; путь `printed_expiration` добавляет `expiration_date`, а путь `age_window` добавляет `max_age_months`. | Попросите пользователя предоставить действующий или более свежий документ либо увеличьте `age_months` для этого типа. | | `INVALID_DOCUMENT_TYPE` | Документ не удалось классифицировать ни под один поддерживаемый тип POA (`document_type` возвращается как `UNKNOWN`). | Попросите пользователя отправить документ повторно; убедитесь, что файл не поврежден. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | Сбой самой проверки возраста документа (ошибка при вычислении срока действия на основе даты выдачи). | Попросите пользователя предоставить документ с четко читаемой датой выдачи. | Риск `FUTURE_ISSUE_DATE` также указан в `AUTO_DECLINE_RISKS`, но генерируется в единственном месте при предварительной валидации перед извлечением (дата выдачи более чем на 7 дней в будущем), ошибки которой передаются только в **цикл повторных попыток сценария** — там он отображается как блокирующая ошибка загрузки, никогда не генерируется отдельным API и не записывается в `warnings[]`. См. [Повторные попытки](#поведение-повторных-попыток-сессии-сценария). ## Настраиваемые предупреждения Каждое из этих предупреждений зависит от параметра действия в узле POA сценария (`DECLINE` / `REVIEW` / `NO_ACTION`). Поле `log_type` предупреждения соответствует настроенному действию: `error` для «Отклонить», `warning` для проверки и `information` для «Без действия». | Риск | Причина | Параметр действия | По умолчанию | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | Имя в документе получает оценку ниже `poa_name_match_score_threshold` (по умолчанию 86) относительно имени, указанного при создании сессии (`expected_details`). | `poa_name_or_address_mismatch_action` | Проверка | | `NAME_MISMATCH_ID_VERIFICATION` | Имя в документе получает оценку ниже порога относительно подтверждённого документа, удостоверяющего личность. `additional_data`: `{ poa_name, kyc_name, match_score }`. Только для сессий сценария. | `poa_name_or_address_mismatch_action` | Проверка | | `ADDRESS_MISMATCH_WITH_PROVIDED` | Извлечённый адрес отличается от адреса, переданного через API, либо один из адресов не удалось подтвердить как жилой адрес. | `poa_name_or_address_mismatch_action` | Проверка | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | Страна документа не совпадает со страной, переданной через API (приведённой к формату ISO-3). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Проверка | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Два или более документов POA в одной сессии содержат разные имена. `additional_data` включает идентификаторы обоих узлов, оба имени и оценку совпадения. Только для сессий сценария. | `poa_name_or_address_mismatch_action` | Проверка | | `DOCUMENT_METADATA_MISMATCH` | Файл пустой (`file_size` равен 0) или даты EXIF некорректны. | `poa_document_issues_action` | Проверка | | `SUSPECTED_DOCUMENT_MANIPULATION` | Криминалистический анализ нашёл признаки подделки: изменение после цифровой подписи (`is_tampered`), подмену наложенного текста (с прямоугольниками `additional_data.manipulated_regions`), известный PDF-редактор, противоречивые даты EXIF или подозрительный повторный экспорт. `additional_data.detection_method` указывает, какая проверка сработала. | `poa_document_authenticity_action` | **Отклонить** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Текстовое поле было очищено и набрано заново другим шрифтом, но в файле нет доказательств того, изменилось ли его содержимое: онлайн-редакторы перенабирают и неизменённый текст. Это предупреждение никогда не вызывает `SUSPECTED_DOCUMENT_MANIPULATION` само по себе. Если другой признак вызывает его для того же документа, решает более строгое из двух действий. `additional_data.detection_method` равен `unproven_text_replacement`, с полями `replaced_text` и `manipulated_regions`. Файл, который не удалось проверить полностью, тоже вызывает это предупреждение, поскольку непроверенная часть может содержать такое поле: тогда `detection_method` равен `analysis_incomplete`, а `replaced_text` и `manipulated_regions` пусты, если поле не найдено в проверенной части. | `poa_document_unproven_text_replacement_action` | Проверка | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Язык документа не входит в `poa_languages_allowed`. | `poa_unsupported_language_action` | **Отклонить** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Определённый тип документа не включён в `poa_documents_allowed` для страны документа либо его подтип явно отключён. | `poa_unsupported_document_type_action` | **Отклонить** | | `ISSUER_NOT_IDENTIFIED` | Выдавшую организацию не удалось определить по документу. | `poa_issuer_not_identified_action` | Проверка | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | На документе не найдена корректная дата выдачи. | `poa_issue_date_not_detected_action` | Проверка | | `POA_NAME_NOT_DETECTED` | На документе не обнаружено имя. | `poa_issue_date_not_detected_action` (общий параметр) | Проверка | | `UNPARSABLE_OR_INVALID_ADDRESS` | Адрес извлечён, но его не удалось разобрать и геокодировать в корректный жилой адрес. | `poa_unparsable_or_invalid_address_action` | Проверка | | `POA_MAX_ATTEMPTS_EXCEEDED` | Пользователь исчерпал `poa_max_retry_attempts` (по умолчанию 2) в цикле повторных попыток сценария. `additional_data`: `{ attempts }`. Только для сессий сценария. | `poa_max_attempts_exceeded_action` | **Отклонить** | > [!NOTE] > > Для всех несоответствий имени и адреса есть **одно общее действие**: `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/](https://docs.didit.me/ru/standalone-apis/proof-of-address.md). ## Поведение повторных попыток (сессии сценария) В сессии верификации шаг загрузки 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_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Review | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Review | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Decline | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Review (сценарий, в котором никогда не используется ручная проверка, применяет собственное действие `poa_document_authenticity_action`, если это Decline, в противном случае No action; отдельный API следует значению `poa_document_authenticity_action` из запроса) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Decline | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Decline | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Review | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Review | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Review | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Decline | | `poa_documents_allowed` | Разрешённые типы документов по странам, каждый с параметрами `enabled` и `age_months` (`-1` = без ограничений); переопределения для подтипов через `document_subtypes_config`. | Счёт за коммунальные услуги и банковская выписка: 3 месяца; выданные государством и прочие: 12 месяцев | | `poa_languages_allowed` | Принимаемые языки документов. | Все поддерживаемые языки | | `poa_name_match_score_threshold` | Минимальная оценка совпадения имён (0–100), ниже которой срабатывают риски `NAME_MISMATCH*`. | 86 | | `poa_max_retry_attempts` | Попытки загрузки до завершения цикла повторов (2–5). | 2 | ## Логика сопоставления имён Сопоставление имён в 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) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### Документ с истекшим сроком действия + отсутствие адреса (автоматическое отклонение) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### Несовпадение имени (по умолчанию Review) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## Связанные разделы * [Отчёт по подтверждению адреса](https://docs.didit.me/ru/core-technology/proof-of-address/report-proof-of-address.md) — полная структура ответа, экспертиза манипуляций с наложением, семантика статусов * [Обзор подтверждения адреса](https://docs.didit.me/ru/core-technology/proof-of-address/overview.md) — поддерживаемые типы документов * [Модели данных — Подтверждение адреса](https://docs.didit.me/ru/reference/data-models.md#подтверждение-адреса) — каноническая схема и объект Warning * [Webhooks](https://docs.didit.me/ru/integration/webhooks.md) — событие `status.updated` передаёт предупреждения POA ### Типы предупреждений This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.