# KYB API — Справочник > **Статус API.** KYB Tenant API находится в стадии бета-тестирования. Эндпоинты, форматы данных и версии API могут быть изменены. Рекомендуется следить за обновлениями документации. Базовый URL: `/tenant/v1/kyb/` Аутентификация: HMAC-SHA256 с использованием KYB-ключа (`kyb_live_*` или `kyb_test_*`). Схема подписи идентична KYC — см. [Аутентификация](/ru/api/authentication). Спецификация: [Swagger UI](https://api.onekyc.io/tenant/docs/), [openapi3.json](https://api.onekyc.io/tenant/docs/openapi3.json). --- ## Компании (Businesses) [#компании-businesses] ### Получение списка компаний [#получение-списка-компаний] API operations: - `GET /v1/kyb/businesses` --- ### Получение компании по идентификатору [#получение-компании-по-идентификатору] API operations: - `GET /v1/kyb/businesses/{business_id}` --- ### Получение компании по внешнему идентификатору [#получение-компании-по-внешнему-идентификатору] Позволяет выполнить поиск по идентификатору вашей системы (`external_id`), заданному при создании ссылки верификации. API operations: - `GET /v1/kyb/businesses/external/{external_id}` --- ### Сессии верификации компании [#сессии-верификации-компании] Возвращает список KYB-сессий, связанных с компанией (история попыток верификации). API operations: - `GET /v1/kyb/businesses/{business_id}/sessions` --- ### История компании [#история-компании] Возвращает хронологический журнал событий, связанных с компанией (создание, обновление статуса, результаты верификации). Требуемый scope: **businesses:read**. API operations: - `GET /v1/kyb/businesses/{business_id}/history` --- ### Удаление данных компании (GDPR) [#удаление-данных-компании-gdpr] Отправляет запрос на удаление данных компании, включая документы и результаты верификации. Фактическое удаление требует подтверждения OneKYC; после подтверждения выполнение необратимо. Требуемый scope: **businesses:write**. API operations: - `DELETE /v1/kyb/businesses/{business_id}` --- ## Медиафайлы [#медиафайлы] ### Получение медиафайла [#получение-медиафайла] Возвращает подписанную ссылку для скачивания медиафайла по его идентификатору (UUID документа). Требуемый scope: **kyb.media:read**. API operations: - `GET /v1/kyb/media/{media_id}` ### Скачивание документа компании [#скачивание-документа-компании] Ответ `GET /v1/kyb/businesses/{business_id}` содержит поля: - `business_document_key` — ключ документа в хранилище - `business_document_url` — подписанная ссылка для скачивания (время жизни ограничено) - `business_document_url_expires_at` — срок действия ссылки - `profile` — поля анкеты компании, введённые во время KYB-флоу, включая `email`, `phone`, `trade_name`, `website`, `business_type`, данные деятельности, структуру владения и идентификаторы Для скачивания документа компании выполните HTTP GET по ссылке из поля `business_document_url`. Аутентификация для скачивания не требуется. > **Примечание.** Для обновления одной ссылки используйте `/businesses/external/{external_id}/document`, а для получения всех актуальных файлов — `/documents`. Данные компании и поле `business_document_url` не являются полным списком файлов. ### Скачивание документа компании по external_id [#скачивание-документа-компании-по-external_id] Возвращает новую подписанную ссылку для документа, загруженного во время KYB-верификации, по `external_id`, который вы передали при создании ссылки верификации. Требуемый scope: **kyb.documents:read**. API operations: - `GET /v1/kyb/businesses/external/{external_id}/document` ### Скачивание всех документов компании [#скачивание-всех-документов-компании] Используйте `GET /tenant/v1/kyb/businesses/external/{external_id}/documents` или `GET /tenant/v1/kyb/businesses/{business_id}/documents`, если известен Business ID OneKYC. Оба метода требуют KYB-ключ со scope **kyb.documents:read**. Среда production или sandbox определяется ключом; переключить её параметром запроса нельзя. Ответ: `{"success": true, "data": [...]}`. Каждый элемент содержит `key`, `url`, `session_id`, `step_id`, `expires_at` и `group`, если группа документа сохранена. Массив включает актуальные файлы всех шагов «Документ компании» текущей KYB-сессии. Документы прошлых сессий и заменённых попыток в него не добавляются. Метод поддерживает уже существующие сессии с несколькими файлами без повторной загрузки. Для существующей компании без документов возвращается пустой массив. Подписанные ссылки действуют ограниченное время и предоставляют доступ без дополнительной аутентификации: храните их конфиденциально, а после истечения срока повторите запрос. Если недоступны хранилище, проверка безопасности или аудит выдачи, возвращается 503 без частичного списка ссылок. Если компания не найдена — 404. Одиночный `/document` сохранён для совместимости и возвращает один файл. Если шаг может содержать несколько файлов, используйте `/documents`. Методы документов аппликанта относятся к связанным физлицам, например бенефициарам, а не к файлам компании. API operations: - `GET /v1/kyb/businesses/external/{external_id}/documents` API operations: - `GET /v1/kyb/businesses/{business_id}/documents` ### Скачивание документов KYB-аппликанта по external_id [#скачивание-документов-kyb-аппликанта-по-external_id] Возвращает документы, загруженные аппликантом внутри KYB-флоу, например KYC-сессии бенефициара. Используйте `external_id`/`external_user_id`, переданный при создании этой ссылки верификации, а не UUID самой ссылки. Требуемый scope: **kyb.documents:read**. API operations: - `GET /v1/kyb/applicants/external/{external_id}/documents` --- ## Ссылки верификации [#ссылки-верификации] ### Создание ссылки верификации [#создание-ссылки-верификации] API operations: - `POST /v1/kyb/verification-links` --- ### Массовое создание ссылок верификации [#массовое-создание-ссылок-верификации] API operations: - `POST /v1/kyb/verification-links/batch` --- ### Получение списка ссылок верификации [#получение-списка-ссылок-верификации] API operations: - `GET /v1/kyb/verification-links` --- ### Получение ссылки по идентификатору [#получение-ссылки-по-идентификатору] API operations: - `GET /v1/kyb/verification-links/{id}` --- ### QR-код ссылки верификации [#qr-код-ссылки-верификации] API operations: - `GET /v1/kyb/verification-links/{id}/qr` --- ### Отзыв ссылки верификации [#отзыв-ссылки-верификации] API operations: - `POST /v1/kyb/verification-links/{id}/revoke` После отзыва ссылка переходит в статус `revoked` и более не может быть активирована. --- ## Метрики [#метрики] Базовый путь: `/tenant/v1/kyb/metrics/`. Требуется разрешение `kyb.metrics:read`. ### Агрегированная статистика [#агрегированная-статистика] API operations: - `GET /v1/kyb/metrics/stats` ### График динамики [#график-динамики] API operations: - `GET /v1/kyb/metrics/chart` ### Воронка верификаций [#воронка-верификаций] API operations: - `GET /v1/kyb/metrics/funnel` ### Лента последних событий [#лента-последних-событий] API operations: - `GET /v1/kyb/metrics/activity` ### Активные сессии в реальном времени [#активные-сессии-в-реальном-времени] API operations: - `GET /v1/kyb/metrics/realtime` ### Экспорт данных в CSV [#экспорт-данных-в-csv] API operations: - `GET /v1/kyb/metrics/export` --- ## Журнал аудита [#журнал-аудита] Возвращает журнал действий по KYB. Требуется разрешение `kyb.audit:read`. API operations: - `GET /v1/kyb/audit` --- ## Задачи ревью [#задачи-ревью] Очередь manual review и решения по KYB-сессиям. Scopes: `kyb.reviews:read` / `kyb.reviews:write` (и `kyb.media:read` для URL документов). Полный гайд: [Задачи ревью (Tenant API)](/ru/api/review). ### Список / stats / reject-reasons [#список--stats--reject-reasons] API operations: - `GET /v1/kyb/review-tasks` API operations: - `GET /v1/kyb/review-tasks/stats` API operations: - `GET /v1/kyb/review-tasks/reject-reasons` ### Деталь и решения [#деталь-и-решения] API operations: - `GET /v1/kyb/review-tasks/{task_id}` API operations: - `POST /v1/kyb/review-tasks/{task_id}/assign` API operations: - `POST /v1/kyb/review-tasks/{task_id}/approve` API operations: - `POST /v1/kyb/review-tasks/{task_id}/reject` API operations: - `POST /v1/kyb/review-tasks/{task_id}/request-resubmit` --- ## Коды ошибок [#коды-ошибок] | Код | Описание | | ----- | --------------------------------------------------- | | `400` | Некорректный запрос (невалидные параметры или поля) | | `401` | Ошибка аутентификации (неверный ключ или подпись) | | `403` | Доступ запрещён (недостаточно прав) | | `404` | Запрашиваемый объект не найден | | `409` | Конфликт (например, дублирующий `external_id`) | | `429` | Превышен лимит запросов | | `500` | Внутренняя ошибка сервера | Подробная информация о формате ошибок и ограничениях приведена в разделе [Ошибки и ограничения](/ru/api/errors-and-limits). ## Полные данные верификации [#полные-данные-верификации] Ответы по отдельной компании (по ID и по внешнему ID) включают безопасные типизированные данные поиска `kyb` и `kyb_document_analysis`, если они доступны. Они сохраняют нормализованные поля компании, локализованные названия, охват поиска и провайдеров, детали получения данных и анализ документов сверх компактного `evidence_profile`. Данные ограничены клиентом, которому принадлежит компания, и её последней сессией и фильтруются по текущим попыткам. Явно более новые попытки скрывают старые результаты ещё до появления результатов-замен. Исторические результаты без метаданных выполнения используют наибольшую наблюдаемую попытку. Сбои необязательного чтения отображаются как `enrichment_errors` (`evidence_results_unavailable` или `evidence_attempts_unavailable`), а производный профиль при этом опускается.