# Документы и медиа

Tenant API предоставляет эндпоинты для получения информации о поддерживаемых типах документов и доступа к загруженным медиафайлам (фотографии документов, селфи). Загрузка файлов осуществляется автоматически в процессе прохождения верификации на стороне OneKYC.

## Поддерживаемые типы документов [#поддерживаемые-типы-документов]

Возвращает перечень типов документов, поддерживаемых платформой, с указанием стран и допустимых форматов. Требуемый scope: **documents:read**.

API operations:

- `GET /v1/kyc/documents/supported`

## Получение медиафайла [#получение-медиафайла]

Возвращает подписанную ссылку для скачивания медиафайла по его идентификатору. Требуемый scope: **media:read**.

API operations:

- `GET /v1/kyc/media/{media_id}`

> **Примечание.** Идентификаторы медиафайлов содержатся в данных аппликанта и в списке документов аппликанта. Подписанная ссылка на медиафайл имеет ограниченный срок действия.

## Как скачать файлы после получения вебхука [#как-скачать-файлы-после-получения-вебхука]

При получении вебхука (например, `session.completed` или `verification.approved`) в payload присутствуют:
- `applicant_id` — идентификатор аппликанта
- `media` — объект со storage keys (информационные, не являются идентификаторами для API)

**Рекомендуемый порядок:**

1. **Получить данные аппликанта** — `GET /v1/kyc/applicants/{applicant_id}`. Ответ содержит готовые подписанные ссылки:
   - `document_photo_url`, `document_front_url`, `document_back_url` — фотографии документа
   - `portrait_photo_url` — портрет из документа
   - `selfie_photo_url` — селфи
   - `avatar_photo_url` — аватар
   - `photo_url_expires_at` — срок действия ссылок

2. **Или получить список документов** — `GET /v1/kyc/applicants/{applicant_id}/documents`. Если у вас есть только ваш внешний идентификатор, используйте `GET /v1/kyc/applicants/external/{external_id}/documents`. Ответ содержит `id` каждого документа (UUID), который можно использовать для `GET /v1/kyc/media/{media_id}`.

3. **Скачать файл** по подписанной ссылке (HTTP GET, без аутентификации). Ссылка действительна ограниченное время.

> **Важно.** Поле `media` в вебхуке содержит внутренние storage keys, а не идентификаторы для API. Для скачивания используйте подписанные ссылки из ответа `GET /v1/kyc/applicants/{applicant_id}`.

## Документы аппликанта [#документы-аппликанта]

Возвращает список документов, загруженных конкретным аппликантом в рамках верификации. Требуемый scope: **documents:read**.

API operations:

- `GET /v1/kyc/applicants/{applicant_id}/documents`

## Документы аппликанта по external_id [#документы-аппликанта-по-external_id]

Возвращает тот же список документов по `external_id`, который вы передали при создании ссылки верификации. Требуемый scope: **documents:read**.

API operations:

- `GET /v1/kyc/applicants/external/{external_id}/documents`

## Коллекции документов и стороны документов [#коллекции-документов-и-стороны-документов]

Шаг документа остаётся в совместимом режиме одного документа, пока `collection` не задан. Параметры `collection.min_documents`, `max_documents` (`0` означает без ограничений), допустимые страны и типы, а также правила проверки настраиваются в Flow Builder. Пустые списки допустимых значений разрешают все значения, поддерживаемые провайдером; рекомендуемые значения не ограничивают распознавание.

У каждого логического документа есть неизменяемый ID и возрастающая ревизия. Две стороны ID-карты или вида на жительство считаются одним документом. Загрузите оба файла с `file_type: document` и необязательным `file_side: front` / `back`, затем отправьте `collection_submit` с `document_storage_key` / `file_id` и необязательными `back_document_storage_key` / `back_file_id`. Старые клиенты коллекций, использующие `document_back_storage_key` / `document_back_file_id`, остаются совместимыми; конфликтующие псевдонимы отклоняются. Устаревший `execute_step` по-прежнему принимает `document_back_storage_key` / `document_back_file_id`. Запросы с одним файлом не изменились. Текущий многостраничный эндпоинт KBY AI принимает первое изображение и одно необязательное второе; произвольное число страниц он не принимает.

Результаты сохраняют отдельные утверждения о гражданстве и праве проживания, каждое со ссылкой на ID и ревизию исходного документа. Одна лишь страна выдачи никогда не подтверждает гражданство. Вид на жительство подтверждает указанное право проживания, но не проверенный текущий адрес. Неизвестная личность владельца и противоречивые данные остаются явно отмеченными и обрабатываются согласно настроенному поведению ревью. Документы с ошибками остаются видимыми для ревью и не дают подтверждённых утверждений.

Автоматические запросы документов поддерживают глобальные условия, условия по стране выдачи и гражданству, а также целевые локальные переопределения. Условия внутри одного правила применяются к одному и тому же исходному документу. Источником страны может быть фиксированная страна, страна выдачи исходного документа или гражданство по исходному документу. Требования правила должны быть выполнены до завершения коллекции.

Представления документов в админке показывают для каждого документа страну выдачи, явно указанное гражданство, распознанные поля, исходные стороны и отдельные результаты проверки подлинности. `document_order` сохраняет стабильную нумерацию, даже когда для совместимых устаревших полей выбран основной документ. `doc_liveness_sides` хранит оценки лицевой и оборотной сторон отдельно.

Анализ документов KYB архивирует все данные и точные байты HTTP-ответа AI, включая неизвестные поля, с приватной привязкой к клиенту, сессии и выполнению. Кэшированный анализ сохраняет эти байты. Зафиксированная попытка не публикует повторное завершение при повторной доставке сообщения. Авторизованные операторы скачивают архивы через эндпоинт необработанных ответов KYB с повышением уровня доступа для регулируемых медиа и событием аудита. Исторические ответы, которые не архивировались, восстановить нельзя, они отображаются как недоступные.

Ответ админки по документам сессии включает `steps[].document_collection`, пока коллекция активна, в том числе документы в обработке и с ошибками. Последние ревизии объединяются с текущей попыткой без дублирования исходных файлов. Просроченные документы требуют ревью, если только `expiry_check.reject_expired` явно не включает отклонение; сбой строгой валидации никогда не понижается другой причиной ревью.

Конечные лимиты коллекции должны оставлять место для исходного документа каждого активного условного правила и запрашиваемых им документов. Правило «вид на жительство — паспорт», требующее один дополнительный документ, требует максимума не менее двух; безусловные требования не резервируют слот под исходный документ. Отключённые правила не занимают ёмкость. Билдер показывает эту ошибку до сохранения, а бэкенд проверяет то же ограничение.