# Ссылки верификации

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

## Создание ссылки верификации [#создание-ссылки-верификации]

API operations:

- `POST /v1/kyc/verification-links`

### Внешний ID и незавершённая ручная проверка [#внешний-id-и-незавершённая-ручная-проверка]

`external_user_id` идентифицирует заявителя внутри тенанта и не является ID сессии. У одного заявителя может быть несколько исторических сессий. Продолжение проверки определяется сочетанием тенанта, окружения, внешнего ID, воронки и типа KYC/KYB.

Если по этому сочетанию остаётся незавершённая ручная проверка, создание новой ссылки возвращает HTTP `409`, `error.code = "session_review_pending"` и `error.existing_session_id`. Завершите текущее ревью или запросите пересдачу в нём. Истечение срока ссылки не завершает ревью. Дублирование ссылки и активация заранее созданной новой ссылки не обходят эту проверку.

Для сессии в процессе обычное создание ссылки продолжает использовать текущую сессию. После итогового одобрения или отклонения можно начать независимую проверку. `external_reference` повторно использует подходящую активную ссылку только если `external_user_id` не указан или совпадает с ID ссылки; для другого внешнего ID создаётся отдельная ссылка. Параметр не задаёт пожизненную уникальность сессии. При пакетном создании конфликт указывается для соответствующего элемента.

Сопоставляйте webhook-события по `session_id` вместе с `external_id`: позднее решение по исторической сессии относится к ней и не должно автоматически заменять результат другой сессии с тем же внешним ID.

### Легаси-совместимость [#легаси-совместимость]

Канонический KYC-путь — `/tenant/v1/kyc/verification-links`. Для существующих интеграций тенантов OneKYC также намеренно поддерживает `/tenant/v1/verification-links` и `/tenant/v1/verificationLinks` как KYC-алиасы. Тела запросов create и batch-create для verification links также принимают легаси-алиасы полей с разным регистром или разделителями, например `flowId`, `FlowID`, `externalUserId`, `redirectUrl` и `prefilledData`.

Эти алиасы нельзя считать мертвым кодом. Это поддерживаемый compatibility contract, который можно удалять только после отдельного versioned deprecation и migration window для Tenant API.

## Пакетное создание ссылок [#пакетное-создание-ссылок]

Позволяет создать несколько ссылок верификации в рамках одного запроса.

API operations:

- `POST /v1/kyc/verification-links/batch`

## Получение списка ссылок [#получение-списка-ссылок]

API operations:

- `GET /v1/kyc/verification-links`

## Получение ссылки по идентификатору [#получение-ссылки-по-идентификатору]

API operations:

- `GET /v1/kyc/verification-links/{id}`

## Отзыв ссылки [#отзыв-ссылки]

Отозванная ссылка становится недействительной и не может быть использована для инициации верификации.

API operations:

- `POST /v1/kyc/verification-links/{id}/revoke`

## Получение QR-кода [#получение-qr-кода]

Возвращает QR-код для ссылки верификации. Используется для реализации cross-device flow: пользователь сканирует QR-код на мобильном устройстве и продолжает верификацию.

API operations:

- `GET /v1/kyc/verification-links/{id}/qr`

---

## Жизненный цикл ссылки [#жизненный-цикл-ссылки]

```
[Created] → [Activated] → [Consumed]
    ↓            ↓            ↓
[Expired]   [Expired]   [Completed]
    ↓            ↓
[Revoked]   [Revoked]
```

**Статусы ссылки:**

| Статус      | Описание                                                               |
| ----------- | ---------------------------------------------------------------------- |
| `active`    | Ссылка создана; пользователь ещё не переходил по ней                   |
| `activated` | Пользователь перешёл по ссылке; создана сессия, верификация в процессе |
| `consumed`  | Верификация завершена (одобрена, отклонена или направлена на ревью)    |
| `expired`   | Истёк срок действия ссылки (`ttl_seconds`); ссылка более недоступна    |
| `revoked`   | Ссылка отозвана вручную через API или административную панель          |

> **Примечание.** После создания ссылки передайте её пользователю (по электронной почте, SMS, QR-коду). При переходе по ссылке автоматически создаётся сессия верификации. Для реализации cross-device flow используйте QR-код (`GET /v1/kyc/verification-links/{id}/qr`).

---

## Редирект после завершения верификации [#редирект-после-завершения-верификации]

При создании ссылки допускается указание параметра **redirect_url** — URL-адреса, на который пользователь будет перенаправлен после завершения процедуры верификации (например, личный кабинет или форма заявки).

### Порядок работы [#порядок-работы]

1. **При создании ссылки** в теле запроса передаётся параметр `redirect_url` (`POST /v1/kyc/verification-links` или batch).
2. **При активации** ссылки `redirect_url` сохраняется в сессию и возвращается в ответе активации (поле `redirect_url`).
3. **На экране завершения** (после одобрения, отклонения или направления на ревью) пользователю отображается:
   - **кнопка возврата** — пользователь нажимает и переходит по redirect_url;
   - либо **автоматический редирект** через заданный интервал времени.

### Настройка поведения [#настройка-поведения]

Поведение редиректа настраивается в **параметрах флоу** в административной панели:

- **Redirect behavior on completion** — режим перенаправления: «Show button» (отображение кнопки) или «Auto redirect» (автоматическое перенаправление).
- **Redirect delay (seconds)** — задержка в секундах перед автоматическим перенаправлением (применяется в режиме «Auto redirect»).

Значения по умолчанию: отображение кнопки; при автоматическом режиме задержка составляет 3 секунды. Подробнее — в разделе [Флоу (админка)](/ru/admin/flows#настройки-редиректа).