# OneKYC — документация

Настоящая документация предназначена для разработчиков, осуществляющих интеграцию с платформой OneKYC, а также для пользователей административной панели. Документация содержит описание продукта, руководство по интеграции и справочник API. Подробное описание возможностей платформы приведено в разделе [О продукте](/ru/introduction/product-overview).

**Содержание документации:**

- **Введение** — описание функциональных возможностей продукта и целевых сценариев использования.
- **Быстрый старт** — пошаговое руководство по созданию ссылки верификации и запуску первой KYC-сессии.
- **Tenant API** — описание программного интерфейса для серверной интеграции: [Аутентификация](/ru/api/authentication), [Сессии](/ru/api/sessions), [Аппликанты](/ru/api/applicants), [Документы и медиа](/ru/api/documents-and-media), [Ссылки верификации](/ru/api/verification-links), [Вебхуки](/ru/api/webhooks), [Метрики](/ru/api/metrics), [Аудит](/ru/api/audit), [Справочник API (OpenAPI)](/ru/api/api-reference).
- **KYB API** — верификация юридических лиц: [Обзор KYB](/ru/kyb), [Быстрый старт](/ru/kyb/quick-start), [Справочник KYB API](/ru/kyb/api-reference), [KYB Вебхуки](/ru/kyb/webhooks).
- **Административная панель** — управление дашбордом, сессиями, аппликантами, сценариями верификации (флоу), ревью, API-ключами, вебхуками, ссылками верификации, командой, аудитом и настройками.

> **Обратите внимание.** Tenant API OneKYC находится в стадии бета-тестирования. Эндпоинты, форматы данных и версии API могут быть изменены. Рекомендуется отслеживать обновления документации.

## Часто задаваемые вопросы [#часто-задаваемые-вопросы]

### Где выполняется верификация — на стороне клиента или на стороне OneKYC? [#где-выполняется-верификация--на-стороне-клиента-или-на-стороне-name]

Верификация выполняется **на стороне OneKYC**. Интеграция сводится к созданию ссылки верификации через API и её передаче конечному пользователю (по электронной почте, SMS, QR-коду и пр.). Пользователь переходит по ссылке на страницу верификации OneKYC, где проходит все предусмотренные сценарием проверки. Результаты передаются на сторону клиента посредством вебхуков или запросов к API.

### Возможно ли встроить верификацию в собственный интерфейс? [#возможно-ли-встроить-верификацию-в-собственный-интерфейс]

Да. Страницу верификации OneKYC можно открыть через **редирект**, в **новом окне браузера** или встроить через **iframe**. Пользовательский интерфейс OneKYC адаптивен и корректно работает как на настольных, так и на мобильных устройствах.

Чтобы встроить страницу верификации, передайте фрейму доступ к камере. Без атрибута `allow` браузеры блокируют камеру внутри iframe. В `src` укажите поле `url` из ответа на создание ссылки верификации:

```html
<iframe
  src="<verification link url>"
  title="Проверка личности"
  allow="camera; microphone; fullscreen; clipboard-write"
  style="width: 100%; height: 100%; min-height: 680px; border: 0"
></iframe>
```

- Если ваша страница отдаёт заголовок `Permissions-Policy`, он должен разрешать камеру для домена верификации, например `camera=(self "https://<verification domain>")`.
- Если на странице настроена Content Security Policy, добавьте домен верификации в `frame-src`.
- Рекомендуемый размер фрейма на десктопе — не меньше 600×680 px. На мобильных устройствах показывайте фрейм на весь экран или используйте редирект.
- После завершения проверки редирект заменяет всю страницу, а не только содержимое фрейма.
- Если доступ к камере во фрейме недоступен, пользователь может продолжить в новой вкладке или на телефоне по QR-коду.
- Встроенные браузеры приложений (Instagram, Facebook, TikTok) и нативные WebView могут ограничивать камеру; в нативных приложениях открывайте ссылку в системном браузере или выдайте WebView разрешение на камеру.

### Как реализован cross-device flow? [#как-реализован-cross-device-flow]

Пользователь может начать верификацию на настольном компьютере (для заполнения форм) и продолжить на мобильном устройстве (для съёмки документов и селфи). При создании ссылки генерируется QR-код; после сканирования пользователь продолжает ту же сессию на мобильном устройстве.

**QR-код действителен в течение 5 минут** и является одноразовым: после сканирования токен аннулируется. В случае истечения срока действия QR-кода необходимо обновить страницу для генерации нового кода.

### Какие типы документов поддерживаются? [#какие-типы-документов-поддерживаются]

Поддерживаются паспорта, идентификационные карты и водительские удостоверения большинства стран. Актуальный перечень доступен через Tenant API: `GET /tenant/v1/kyc/documents/supported`. В настройках флоу определяется, какие типы документов допустимы для конкретного сценария верификации.

### Возможно ли настроить сценарий верификации? [#возможно-ли-настроить-сценарий-верификации]

Да. Настройка сценариев осуществляется через **Flow Editor** в административной панели. Доступны следующие операции: добавление и удаление шагов (загрузка документа, селфи, liveness-проверка, OTP-подтверждение, AML-скрининг, ручное ревью), изменение порядка шагов и их параметров. Изменения применяются к новым сессиям после публикации обновлённой версии флоу.

### Каким образом получать результаты верификации? [#каким-образом-получать-результаты-верификации]

Предусмотрены два способа:

1. **Вебхуки** (рекомендуемый способ) — OneKYC направляет уведомления о событиях на указанный URL в режиме реального времени (например, `verification.approved`, `verification.declined`).
2. **Polling через API** — периодический запрос статуса верификации через эндпоинт `/tenant/v1/kyc/applicants/{applicant_id}/verification`.

### Какова длительность процедуры верификации? [#какова-длительность-процедуры-верификации]

- **Автоматическая верификация** (без ручного ревью) — 30--60 секунд (загрузка документа, селфи, выполнение проверок).
- **С ручным ревью** — зависит от загрузки очереди операторов (от нескольких минут до нескольких часов).
- **С AML-скринингом** — дополнительно 5--15 секунд.

### Какие действия предпринять, если пользователь не прошёл верификацию? [#какие-действия-предпринять-если-пользователь-не-прошёл-верификацию]

Рекомендуемые действия зависят от причины отклонения (поле `rejection_reason` в ответе API):

- **Низкое качество изображения** — рекомендуется предложить пользователю повторить процедуру (создать новую ссылку верификации).
- **Истёкший срок действия документа** — рекомендуется уведомить пользователя о необходимости предоставить действующий документ.
- **Несовпадение лица** — возможный индикатор мошенничества; рекомендуется ручная проверка или отклонение.
- **AML-совпадение** — решение принимается на стороне клиента в соответствии с внутренними процедурами управления рисками.

### Как тестировать интеграцию? [#как-тестировать-интеграцию]

1. Создайте API-ключ с префиксом `kyc_test_` в административной панели.
2. Используйте тестовые ключи в среде разработки/staging.
3. Для тестирования вебхуков рекомендуется использовать ngrok или аналогичные инструменты для локальной разработки.
4. Сессии, созданные с тестовыми ключами, не учитываются в биллинге.

### Возможно ли удаление данных пользователя (GDPR)? [#возможно-ли-удаление-данных-пользователя-gdpr]

Да. Эндпоинт `DELETE /tenant/v1/kyc/applicants/{applicant_id}` создаёт запрос на удаление данных. Запрос проходит проверку перед исполнением; после подтверждения и выполнения удаление необратимо.

### Как осуществляется тарификация? [#как-осуществляется-тарификация]

Тарификация производится на основании количества успешно завершённых верификаций. Тестовые ключи (`kyc_test_*`) не тарифицируются. Информация о тарифных планах доступна в административной панели или у персонального менеджера.

---

Для начала работы перейдите к разделу [О продукте](/ru/introduction/product-overview) или [Быстрый старт](/ru/introduction/quick-start).