Перейти к основному содержанию
POST
Python
Отправьте один документ и список полей, которые нужно из него извлечь. Didit запускает модель извлечения данных по умолчанию для файла, возвращает все поля с типами (text, number или date в формате YYYY-MM-DD), обнаруживает и декодирует поддерживаемые QR-коды и штрихкоды, проверяет файл на наличие манипуляций и, при необходимости, сравнивает имя в документе с ожидаемым физическим лицом или компанией. Используйте его для подтверждения наличия средств, расчётных листков, банковских выписок, налоговых документов, счетов-фактур или любого документа, который не соответствует фиксированному шаблону. Это серверная версия шага Document AI из размещённого сценария. Запрос имеет тип multipart/form-data: файл передаётся в поле document, а описания полей передаются в поле fields в виде одной строки с JSON-массивом.

Определение полей для извлечения

Параметр fields представляет собой JSON-массив из 1–30 элементов, передаваемый одной строкой. Каждый элемент содержит key (строчные латинские буквы, цифры и подчёркивания, уникальные в рамках запроса), понятное человеку name, инструкцию instruction, объясняющую модели, что искать, type (text, number или date), а также два флага: required и is_full_name.
В запросе multipart весь массив передаётся как одно значение формы:
В ответе возвращаются нормализованные fields, а extracted_data содержит ключи, соответствующие вашим значениям key. Если модель не смогла найти значение, оно равно null. Поля name, instruction и type в каждом элементе необязательны (type по умолчанию равен text), а key обязателен. Если передать fields в виде ключей формы в стиле скобок (fields[0][key]=...) или в любом формате, отличном от JSON-массива, сервис вернёт 400 до запуска извлечения, поэтому оплата не списывается.

QR-коды и штрихкоды

Каждый успешный ответ содержит document_ai.detected_codes. Каждый элемент включает: Массив охватывает все обработанные страницы PDF и пуст, если поддерживаемый код не найден. Didit никогда не угадывает содержимое кода: повреждённые QR-коды могут возвращаться с расположением и parsed_payload: null, а сбои при обнаружении кодов не приводят к ошибке запроса Document AI.

Сопоставление имён

Укажите не более одного поля с is_full_name: true и передайте данные о том, кому, по вашим ожиданиям, принадлежит документ: Передайте одну из групп, но не обе. Если имя извлечено и ожидаемое имя передано, ответ включает name_match_score (от 0 до 100) и name_on_document. Если оценка ниже document_ai_name_match_score_threshold (по умолчанию 80), возникает предупреждение DOCUMENT_AI_NAME_MISMATCH и применяется действие document_ai_name_mismatch_action. Если ни одно поле не помечено как is_full_name, Didit использует первое текстовое поле, ключ которого похож на имя (name, holder, full_name, account_holder). Чтобы контролировать, какое значение сравнивается, явно пометьте нужное поле. Если значение имени не найдено в документе или ожидаемое имя не передано, проверка имени пропускается, а name_match_score равен null.

Риски и действия

Каждому риску ниже соответствует параметр действия, который вы можете задать для каждого запроса: DECLINE, REVIEW или NO_ACTION. Наиболее строгое сработавшее действие определяет document_ai.status (Declined > In Review > Approved), а каждый сработавший риск перечисляется в document_ai.warnings. Значения по умолчанию совпадают с размещённым шагом сценария. Сведения о том, как обнаруживается каждый риск, см. в разделе Правила и предупреждения Document AI.

Файлы, сохранение и тарификация

  • Принимаемые файлы: PDF (поддерживаются многостраничные документы), JPG, JPEG, PNG, TIFF, WebP или ZIP-архив с документом, размером до 30 МБ. Зашифрованные PDF возвращают 400; загрузите расшифрованный PDF или фотографию.
  • save_api_request (по умолчанию true): запрос, извлечённые поля и обнаруженные коды отображаются в Business Console в разделе Manual Checks, где ваша команда может их просмотреть. Установите false, чтобы не сохранять данные.
  • vendor_data и metadata возвращаются в ответе без изменений, чтобы вы могли связать результат со своими записями.
  • Цена: $0.20 за документ; списывается, когда документ обработан и возвращён статус. Скидка по вашему тарифу применяется. См. Цены.
Нужно, чтобы пользователь загрузил документ сам, собрать до 3 документов в одном потоке, автоматически перевести экран загрузки или сопоставить извлечённые поля с данными удостоверения личности или анкеты? Используйте вместо этого размещённый шаг сценария Document AI.

Авторизации

x-api-key
string
header
обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

multipart/form-data
document
file
обязательно

Документ для чтения. Допустимые расширения: tiff, jpg, jpeg, png, pdf, webp, zip. Максимальный размер загрузки: 30 MB (файлы большего размера отклоняются с ошибкой 400). Поддерживаются многостраничные PDF (время ожидания может быть выше); зашифрованные PDF отклоняются с ошибкой 400. Изображения автоматически сжимаются перед обработкой.

fields
string
обязательно

Одна закодированная в JSON строка массива с 1–30 определениями полей (максимум 16 КБ). Каждый элемент: key (обязательно, ^[a-z0-9_]{1,64}$, уникальный — ключ, возвращаемый в extracted_data), name (≤100 символов, отображается в сообщениях), instruction (≤500 символов, что модель должна прочитать), type (по умолчанию text | number | date), required (булево, по умолчанию false), is_full_name (булево, по умолчанию false, не более одного на запрос). Массивы форм в квадратных скобках, некорректный JSON, повторяющиеся ключи или несколько is_full_name возвращают 400 до какой-либо обработки или списания средств.

Пример:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Имя для сверки с полем имени в документе (нечёткое сравнение с учётом транслитерации). Используйте вместе с expected_last_name; нельзя комбинировать с expected_company_name.

Пример:

"Sophia"

expected_last_name
string

Фамилия для сверки с полем имени в документе, объединяемая с expected_first_name для name_match_score.

Пример:

"Martinez"

expected_company_name
string

Название компании для сверки с полем имени в документе (для корпоративных документов). Нельзя использовать вместе с expected_first_name / expected_last_name (значение в примере намеренно отсутствует — сгенерированный пример запроса использует поля физического лица; замените их на это поле при верификации корпоративного документа).

expected_company_country
string

Необязательный двухбуквенный код страны ISO 3166-1 alpha-2 (две буквы ASCII, например FR), который настраивает нормализацию названия компании для expected_company_name. Используется только вместе с expected_company_name.

document_ai_name_match_score_threshold
integer
по умолчанию:80

Минимальное значение name_match_score (0–100), при котором имя считается совпавшим. Более низкая оценка добавляет DOCUMENT_AI_NAME_MISMATCH, регулируемое параметром document_ai_name_mismatch_action.

Требуемый диапазон: 0 <= x <= 100
Пример:

80

document_ai_unreadable_document_action
enum<string>
по умолчанию:REVIEW

Действие, если из документа не удалось считать ни одного поля (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Доступные опции:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
по умолчанию:REVIEW

Действие, если не удалось прочитать хотя бы одно поле required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; список приведён в additional_data.missing_fields).

Доступные опции:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
по умолчанию:DECLINE

Действие при подозрении на манипуляции по результатам криминалистического анализа PDF/EXIF: файл изменён после цифровой подписи, использовался известный PDF-редактор, выявлены манипуляции с наложенным текстом, подозрительный повторный экспорт или аномалии изображения (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Доступные опции:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
по умолчанию:NO_ACTION

Действие, когда name_match_score ниже порогового значения (DOCUMENT_AI_NAME_MISMATCH).

Доступные опции:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
по умолчанию:REVIEW

Что делать, если загруженный файл пуст или не подлежит обработке (DOCUMENT_AI_UNSUPPORTED_FILE).

Доступные опции:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
по умолчанию:true

Если true (по умолчанию), сохраняет вызов как сессию типа API — видимую в Business Console, доступную через GET /v3/session/{sessionId}/decision/ по возвращенному request_id, с сохранением загруженного документа, извлеченных значений, определений полей и снимка сопоставления имен. Если false, ничего не сохраняется, а request_id является временным UUID только для сопоставления ответа; вызов по-прежнему тарифицируется.

Пример:

true

vendor_data
string

Необязательная непрозрачная строка (ваш внутренний идентификатор пользователя, email, UUID…), сохраняемая в сессии и возвращаемая в ответе. Используйте её для сопоставления вызовов API с вашими собственными записями и для последующей фильтрации сессий.

Пример:

"user-123"

metadata
object

Необязательный объект JSON, сохраняемый вместе с сессией (когда save_api_request=true) и возвращаемый обратно в ответе. В multipart-запросах отправляйте его как строковое поле в формате JSON (например, metadata={"flow":"onboarding"}) — он парсится в объект.

Пример:

Ответ

Документ обработан. Значение document_ai.status: Approved, Declined или In Review; каждая обнаруженная проблема детализирована в document_ai.warnings. Для проблемного документа по-прежнему возвращается 200 — проверяйте тело ответа, а не только HTTP-код. Если save_api_request=true, request_id представляет собой сохранённый id сессии.

request_id
string<uuid>

Идентификатор сохраненной сессии при save_api_request=true (доступен для использования с GET /v3/session/{sessionId}/decision/); в противном случае это временный корреляционный UUID.

document_ai
object
vendor_data
string | null

Эхо-значение переданного вами vendor_data или null.

metadata
object | null

Эхо-значение переданного вами объекта metadata или null.

created_at
string<date-time>

Время обработки запроса (UTC, ISO 8601).

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