> ## 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. # API подтверждения адреса: верификация POA и OCR > Didit: POST /v3/poa/ для проверки коммунальных счетов, выписок и договоров аренды. OCR адреса, проверка подлинности, оплата по факту. ## OpenAPI ````yaml ru/openapi-25.json POST /v3/poa/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: >- API верификации личности. Аутентификация выполняется с помощью заголовка x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/poa/: post: tags: - Standalone APIs summary: Подтверждение адреса (OCR документа + проверки адреса) description: >- Извлекайте данные и проверяйте документ Подтверждения адреса — счета за коммунальные услуги, банковские выписки и документы, выданные государственными органами — за один вызов. Возвращает эмитента, даты выдачи и срока действия, имя владельца, исходный и разобранный/геокодированный адрес, `status` (`Approved`/`Declined`) и список `warnings` с пояснением каждой обнаруженной проблемы. **Задержка.** Извлечение выполняется на базе LLM: стандартные вызовы занимают **5–15 секунд**, многостраничные PDF занимают до **~30 секунд**. Настройте клиентский таймаут **минимум на 45 секунд** и не повторяйте запрос до завершения текущего вызова. **Как это работает.** Документ (изображение или PDF размером до 15 МБ; для зашифрованных PDF требуется `document_password`) классифицируется по типу и подтипу (например, `UTILITY_BILL` / `WATER_BILL`), а эмитент, даты, имя владельца и адрес извлекаются с помощью LLM. Адрес парсится и геокодируется в `poa_parsed_address`. Криминалистический анализ PDF/EXIF проверяет наличие признаков фальсификации (изменений после цифровой подписи, использования известных PDF-редакторов, манипуляций с наложенным текстом, подозрительного повторного экспорта), фиксируя `SUSPECTED_DOCUMENT_MANIPULATION` или `DOCUMENT_METADATA_MISMATCH`. Текстовое поле, которое было очищено и набрано заново другим шрифтом, если сам файл не содержит подтверждения изменения содержимого, вызывает `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. Возраст документа проверяется по параметру `poa_document_age_months`, а язык — по `poa_languages_allowed`. Если вы передаете `expected_address`, `expected_country` или `expected_first_name`/`expected_last_name`, извлеченные значения перекрестно проверяются, а несоответствия отмечаются. **Логика принятия решений.** `status` имеет значение `Approved`, если ни одно предупреждение не приводит к отклонению. Критические ошибки всегда приводят к отклонению: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, а также `UNABLE_TO_EXTRACT_ISSUE_DATE` и `POA_NAME_NOT_DETECTED` (не настраиваются на этом endpoint). Пять групп риска можно настраивать для каждого запроса с помощью параметров `poa_*_action` (`DECLINE` или `NO_ACTION`, по умолчанию везде `DECLINE`). Предупреждения `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` и `UNPARSABLE_OR_INVALID_ADDRESS` на этом endpoint носят исключительно информационный характер и никогда не приводят к отклонению. Документ, который вообще невозможно обработать, возвращает `400`; читаемый, но проблемный документ возвращает `200` со значением `status: "Declined"` — всегда проверяйте `poa.status` и `poa.warnings`, а не только HTTP-код. **Биллинг.** Каждый ответ `200` расходует один API-кредит функции «Подтверждение адреса» (списывается из кредитов тарифа или баланса пополнения). Если баланс организации не покрывает стоимость вызова, endpoint возвращает `403` с ошибкой нехватки кредитов до начала обработки документа. **Сохранение сессии (`save_api_request`, по умолчанию `true`).** При значении `true` вызов сохраняется как сессия с типом API: она отображается в Business Console, загруженный документ сохраняется, возвращенный `request_id` является реальным id сессии, который можно передать в `GET /v3/session/{sessionId}/decision/` (в решении дополнительно возвращаются `document_file` и криминалистические данные `document_metadata`, которые опущены в данном ответе), и отправляется webhook `status.updated`. При значении `false` ничего не сохраняется, а `request_id` представляет собой одноразовый UUID для корреляции, который нельзя запросить позже. **Песочница.** API-ключи песочницы не запускают обработку и биллинг: после валидации запроса (некорректный ввод по-прежнему возвращает `400`) endpoint возвращает статический тестовый payload со статусом `Approved` (вымышленный счет за электричество от «Sandbox Power Co.»), сессия не сохраняется, а кредиты не списываются. **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке `x-api-key`. При отсутствии или недействительности учетных данных возвращается `403` (`{"detail": "You do not have permission to perform this action."}`) — этот API никогда не возвращает `401`. **Лимит запросов.** Общий лимит на запись составляет 300 запросов в минуту на один API-ключ для всех endpoint POST/PATCH/DELETE; при его превышении возвращается `429`. Примечание: `FUTURE_ISSUE_DATE` и `POOR_DOCUMENT_QUALITY` существуют в сессиях сценариев, но никогда не генерируются этим отдельным endpoint; документ с будущей датой здесь не отклоняется автоматически. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- Документ «Подтверждение адреса». Допустимые расширения: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Максимальный размер загружаемого файла: **15 MB** (файлы большего размера отклоняются с ошибкой `400`). Поддерживаются многостраничные PDF (ожидается более высокая задержка); для зашифрованных PDF требуется `document_password`. Изображения автоматически сжимаются перед обработкой. document_password: type: string description: >- Пароль для расшифровки `document`, если это зашифрованный PDF-файл. Передача зашифрованного PDF без пароля (или с неверным паролем) возвращает `400`. writeOnly: true expected_address: type: string description: >- Адрес для сверки с документом. Он геокодируется и сравнивается с извлечённым адресом; несоответствие (или ожидаемый адрес, который не удаётся геокодировать/проверить) добавляет `ADDRESS_MISMATCH_WITH_PROVIDED`, управляемое `poa_address_mismatch_action`. Геокодированная форма возвращается в `expected_details_formatted_address` / `expected_details_parsed_address`. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- Страна для сверки с документом (код ISO 3166-1, например `ARG` или `AR`). Несовпадение со страной документа добавляет `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, регулируемое `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- Имя для сверки с `name_on_document` (нечёткое сравнение с учётом транслитерации). Оценка ниже порога совпадения добавляет `NAME_MISMATCH_WITH_PROVIDED`, регулируемый параметром `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- Фамилия для сверки с `name_on_document`, объединяемая с `expected_first_name` для расчёта оценки совпадения. example: Martinez poa_languages_allowed: type: string description: >- Разделённый запятыми список принимаемых языков документов в виде кодов ISO 639-1 (например, `en,es,fr`). Если параметр опущен или пуст, принимаются **все 51 поддерживаемый язык**. Документ на языке вне этого списка добавляет `UNSUPPORTED_DOCUMENT_LANGUAGE` (регулируется параметром `poa_unsupported_language_action`); неизвестный код в списке возвращает `400` с полным набором поддерживаемых кодов. example: en,es poa_document_age_months: type: string description: >- Разделённые запятыми пары `key:value`, задающие максимальный возраст документа в месяцах для каждого типа документа — ключи: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; значения: `1`–`120` или `-1` для неограниченного срока (без проверки возраста). Значения по умолчанию, если параметр опущен: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Документ старше установленного лимита отклоняется с `POA_DOCUMENT_EXPIRED`. **Внимание:** если вы передаёте это поле, укажите *каждый* принимаемый вами тип — пропущенные типы считаются неприемлемыми (информационный статус `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`), а проверка их возраста пропускается. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Принимается, но **в настоящее время не применяется** — предупреждения о несоответствии имени (`NAME_MISMATCH_WITH_PROVIDED`) вместо этого регулируются параметром `poa_address_mismatch_action`. Задайте `poa_address_mismatch_action`, чтобы управлять поведением при несоответствии как имени, так и адреса. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Действие при проблемах с целостностью файла — на практике этот endpoint генерирует только `DOCUMENT_METADATA_MISMATCH`. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Действие при подозрении на манипуляцию с документом (`SUSPECTED_DOCUMENT_MANIPULATION`) — например, PDF был изменён после цифровой подписи, обработан известным PDF-редактором, имеет признаки манипуляций с наложением текста или содержит несогласованные даты EXIF. Также управляет `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (повторно набранное текстовое поле, изменение которого невозможно подтвердить или опровергнуть): при `DECLINE` оно также отклоняется, при `NO_ACTION` остаётся предупреждением. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Что делать, если язык документа не входит в `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Что делать, если извлеченные данные не совпадают с полями `expected_*`: предупреждения `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` и `POA_COUNTRY_MISMATCH_WITH_PROVIDED` следуют этому действию. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Действие, если в документе не удаётся определить выдавшую компанию/организацию (`ISSUER_NOT_IDENTIFIED`). save_api_request: type: boolean default: true description: >- Если `true` (по умолчанию), сохраняет вызов как сессию типа API — видимую в Business Console, доступную через `GET /v3/session/{sessionId}/decision/` по возвращенному `request_id`, анонсируемую через webhook `status.updated`, с сохранением загруженного документа. Если `false`, ничего не сохраняется, а `request_id` является временным UUID только для сопоставления ответа. example: true vendor_data: type: string description: >- Необязательная непрозрачная строка (ваш внутренний идентификатор пользователя, email, UUID…), сохраняемая в сессии и возвращаемая в ответе. Используйте её для сопоставления вызовов API с вашими собственными записями и для последующей фильтрации сессий. example: user-123 metadata: type: object additionalProperties: true description: >- Необязательный объект JSON, сохраняемый вместе с сессией (когда `save_api_request=true`) и возвращаемый обратно в ответе. В multipart-запросах отправляйте его как строковое поле в формате JSON (например, `metadata={"flow":"onboarding"}`) — он парсится в объект. example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- Документ обработан. Значение `poa.status`: `Approved` или `Declined`; каждая обнаруженная проблема детализирована в `poa.warnings`. Для истёкшего, несовпадающего или подозрительного документа по-прежнему возвращается `200` со статусом `status: "Declined"` — проверяйте тело ответа, а не только HTTP-код. Если `save_api_request=true`, `request_id` представляет собой сохранённый id сессии. content: application/json: examples: Approved: summary: >- Квитанция за коммунальные услуги успешно распознана, без проверок ожидаемых реквизитов value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: >- Дата выдачи старше допустимого значения `poa_document_age_months` value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` не совпадают с `name_on_document` value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Идентификатор сохраненной сессии при `save_api_request=true` (доступен для использования с `GET /v3/session/{sessionId}/decision/`); в противном случае это временный корреляционный UUID. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved`, если ни одно предупреждение не приводит к отклонению; в противном случае `Declined` — список `warnings` поясняет причину. issuing_state: type: string nullable: true description: >- Страна выдачи документа, извлечённая из него, — обычно ISO 3166-1 alpha-3 (например, `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- Обнаруженная категория документа. Значение `UNKNOWN` означает, что документ не удалось классифицировать как допустимое Подтверждение адреса, и он автоматически отклоняется со статусом `INVALID_DOCUMENT_TYPE`. Никогда не бывает null — при ошибках классификации возвращается `UNKNOWN`. document_subtype: type: string description: >- Более детальная классификация внутри `document_type` — например, `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (коммунальные счета); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (банковские выписки); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (государственные документы). `UNKNOWN`, если подтип определить не удалось. Никогда не бывает null — при ошибках классификации возвращается `UNKNOWN`. example: WATER_BILL document_language: type: string nullable: true description: Обнаруженный язык документа (ISO 639-1). example: es issuer: type: string nullable: true description: >- Компания или организация, выдавшая документ. `null` добавляет `ISSUER_NOT_IDENTIFIED`. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- Дата выдачи документа (`YYYY-MM-DD`). `null`, если её не удалось извлечь — на этом endpoint возвращается отклонение с `UNABLE_TO_EXTRACT_ISSUE_DATE`. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- Явный срок действия / дата окончания действия, напечатанные на документе, при наличии. Не зависит от проверки давности `poa_document_age_months`. poa_address: type: string nullable: true description: >- Адрес в точности так, как напечатан на документе. При `null` автоматически отклоняется с `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: Геокодированная нормализованная версия `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- Структурированная геокодированная детализация адреса из документа. `null`, если адрес не удалось распознать. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: Двухбуквенный код страны ISO 3166-1 alpha-2. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: Геокодированные координаты адреса из документа. expected_details_address: type: string nullable: true description: >- Эхо-значение переданного вами `expected_address` или `null`. expected_details_formatted_address: type: string nullable: true description: >- Геокодированная нормализованная версия `expected_address`; `null`, если не указан или не поддаётся геокодированию. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- Полный результат геокодирования для `expected_address` (улица/город/регион/страна/почтовый индекс плюс исходные данные геокодера и флаг `is_verified`). `null`, если `expected_address` не был указан. name_on_document: type: string nullable: true description: >- Основное имя владельца, извлечённое из документа; сравнивается с `expected_first_name`/`expected_last_name`, если они указаны. При `null` данный endpoint отклоняет запрос с `POA_NAME_NOT_DETECTED`. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- Специфичные для документа дополнительные поля. Поля банков заполняются для банковских выписок, если они напечатаны на документе; в противном случае `null`. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: >- Контактный номер телефона, напечатанный на документе. additional_names: type: array items: type: string description: >- Другие имена владельцев, найденные в документе (например, совладельцы счета, предыдущие названия счета). warnings: type: array description: >- Пусто при чистом одобрении. Каждая запись описывает один обнаруженный риск; записи с `log_type: "error"` устанавливают для `status` значение `Declined`. items: type: object properties: risk: type: string description: >- Машиночитаемый код риска. Всегда приводят к отклонению: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, а также `UNABLE_TO_EXTRACT_ISSUE_DATE` и `POA_NAME_NOT_DETECTED` (фиксированно отклоняются на этом endpoint). Регулируются параметрами запроса: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (никогда не возвращается этим endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` и `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Информационные на этом endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- Функция, вызвавшая предупреждение. На этом endpoint всегда `PROOF_OF_ADDRESS`. additional_data: type: object nullable: true additionalProperties: true description: >- Дополнительный контекст для некоторых рисков — например, `POA_DOCUMENT_EXPIRED` включает `expiration_reason` (`printed_expiration` или `age_window`), `document_type`, `document_subtype` и `issue_date`, а также `expiration_date` для пути `printed_expiration` или `max_age_months` для пути `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` включает `reason` и `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` включает `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` и `manipulated_blocks`. `null` для большинства рисков. log_type: type: string enum: - error - information description: >- Серьёзность. Предупреждения `error` переводят `status` в `Declined`; записи `information` носят информационный характер и сами по себе никогда не приводят к отклонению. (`warning` не формируется этим endpoint — его параметры принимают только `DECLINE` или `NO_ACTION`.) short_description: type: string description: >- Краткая сводка риска в одну строку в понятном человеку формате. long_description: type: string description: Понятное объяснение риска. detected_codes: type: array description: >- QR-коды и штрихкоды, обнаруженные на всех обработанных страницах документа. Пусто, если ничего не найдено. Для обнаруженного, но не поддающегося декодированию QR-кода возвращается `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: Эхо-значение переданного вами `vendor_data` или `null`. metadata: type: object nullable: true additionalProperties: true description: >- Эхо-значение переданного вами объекта `metadata` или `null`. created_at: type: string format: date-time description: Временная метка ISO 8601 (UTC) момента генерации ответа. '400': description: >- Ошибка валидации или обработки. Проблемы на уровне полей возвращают стандартную структуру DRF (один массив сообщений на каждое проблемное поле). Проблемы с зашифрованными PDF возвращают `{"detail": ...}`. Документ, который пайплайн извлечения данных не может обработать, возвращает `{"error": ["Error extracting POA information"]}`. content: application/json: examples: Missing document: summary: '`document` не включён в данные формы' value: document: - No file was submitted. Unsupported file extension: summary: Расширение файла отличается от tiff/jpg/jpeg/png/pdf/webp value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: Размер загружаемого файла превышает лимит в 15 МБ value: document: - File size should not exceed 15 MB Encrypted PDF: summary: PDF загружен без обязательного пароля value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` не расшифровывает PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` содержит неподдерживаемый код' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: Значение `poa_document_age_months` вне диапазона 1–120 / -1 value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: Не удалось обработать документ в пайплайне извлечения данных value: error: - Error extracting POA information '403': description: >- В доступе отказано. Возвращается, если заголовок `x-api-key` отсутствует, а также если баланс вызывающей организации не покрывает вызов; неверный, отозванный или истекший ключ возвращает `401`. Отсутствующий ключ возвращает `403` с `{"detail": ...}`; неверный, отозванный или истекший ключ возвращает `401`. При нехватке кредитов возвращается `403` с `{"error": ...}` до начала любой обработки документа. content: application/json: examples: Missing or invalid API key: summary: >- Отсутствует заголовок `x-api-key`, либо ключ недействителен/отозван value: detail: You do not have permission to perform this action. Not enough credits: summary: Баланс организации недостаточен для совершения вызова value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Превышен лимит запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600). Ответ содержит заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` и `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Более 300 запросов на запись в текущую минуту value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- Обнаруженная символика, например `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` или `PDF_417`. page_number: type: integer minimum: 1 description: Номер страницы (начиная с 1). position: type: array nullable: true description: >- Обнаруженный многоугольник в пиксельных координатах отрисованной страницы. `null`, если надежные координаты недоступны. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: Левый край ограничивающей рамки в пикселях отрендеренной страницы. 'y': type: integer nullable: true description: Верхний край ограничивающей рамки в пикселях отрендеренной страницы. width: type: integer nullable: true description: >- Ширина ограничивающего прямоугольника в пикселях отображаемой страницы. height: type: integer nullable: true description: >- Высота ограничивающего прямоугольника в пикселях отображаемой страницы. page_width: type: integer description: Ширина отрисованной страницы в пикселях. page_height: type: integer description: Высота отрисованной страницы в пикселях. raw_payload: type: string description: >- Необработанный payload декодера в виде строки base64 при наличии; в противном случае пустая строка. parsed_payload: nullable: true description: >- Декодированная строка или структурированное значение. `null`, если код был обнаружен, но не смог быть декодирован. responses: DocumentProcessingBusy: description: >- В данный момент обрабатывается слишком много документов, поэтому эта загрузка не была обработана: ничего не сохранено, и попытка не была использована. Отправьте тот же файл повторно через количество секунд, указанное в `Retry-After`. Выполняйте ветвление по `code`, а не по тексту сообщения. headers: Retry-After: description: >- Количество секунд ожидания перед повторной отправкой того же запроса. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.