# Миграция на новые пути

## Описание изменений [#описание-изменений]

В целях структурного разделения продуктов KYC и KYB введены канонические пути запросов с префиксом `/kyc/`. Данная мера обеспечивает единообразие адресации, изоляцию прав доступа и независимое версионирование каждого продукта.

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

| Прежний путь (deprecated)         | Канонический путь                     |
| --------------------------------- | ------------------------------------- |
| `/tenant/v1/applicants/*`         | `/tenant/v1/kyc/applicants/*`         |
| `/tenant/v1/verification-links/*` | `/tenant/v1/kyc/verification-links/*` |
| `/tenant/v1/metrics/*`            | `/tenant/v1/kyc/metrics/*`            |
| `/tenant/v1/audit`                | `/tenant/v1/kyc/audit`                |
| `/tenant/v1/documents/*`          | `/tenant/v1/kyc/documents/*`          |
| `/tenant/v1/media/*`              | `/tenant/v1/kyc/media/*`              |

***

## Порядок миграции [#порядок-миграции]

**Шаг 1.** Обновите базовый URL в конфигурации интеграции:

```diff
- const BASE_URL = 'https://api.onekyc.io/tenant/v1';
+ const BASE_URL = 'https://api.onekyc.io/tenant/v1/kyc';
```

**Шаг 2.** Убедитесь, что используется API-ключ с корректным префиксом: `kyc_live_*` (продакшен) или `kyc_test_*` (тестовая среда). Канонические пути `/kyc/*` выполняют дополнительную валидацию типа ключа.

**Шаг 3.** Замените пути во всех вызовах API:

```diff
- GET  /tenant/v1/applicants
+ GET  /tenant/v1/kyc/applicants

- GET  /tenant/v1/applicants/{id}
+ GET  /tenant/v1/kyc/applicants/{id}

- GET  /tenant/v1/applicants/external/{external_id}
+ GET  /tenant/v1/kyc/applicants/external/{external_id}

- POST /tenant/v1/verification-links
+ POST /tenant/v1/kyc/verification-links

- GET  /tenant/v1/verification-links/{id}
+ GET  /tenant/v1/kyc/verification-links/{id}

- POST /tenant/v1/verification-links/{id}/revoke
+ POST /tenant/v1/kyc/verification-links/{id}/revoke

- GET  /tenant/v1/documents/{id}
+ GET  /tenant/v1/kyc/documents/{id}

- GET  /tenant/v1/documents/supported
+ GET  /tenant/v1/kyc/documents/supported

- GET  /tenant/v1/media/{media_id}
+ GET  /tenant/v1/kyc/media/{media_id}

- GET  /tenant/v1/metrics/stats
+ GET  /tenant/v1/kyc/metrics/stats

- GET  /tenant/v1/metrics/chart
+ GET  /tenant/v1/kyc/metrics/chart

- GET  /tenant/v1/metrics/funnel
+ GET  /tenant/v1/kyc/metrics/funnel

- GET  /tenant/v1/metrics/activity
+ GET  /tenant/v1/kyc/metrics/activity

- GET  /tenant/v1/metrics/realtime
+ GET  /tenant/v1/kyc/metrics/realtime

- GET  /tenant/v1/metrics/export
+ GET  /tenant/v1/kyc/metrics/export

- GET  /tenant/v1/applicants/{id}/history
+ GET  /tenant/v1/kyc/applicants/{id}/history

- GET  /tenant/v1/applicants/{id}/aml
+ GET  /tenant/v1/kyc/applicants/{id}/aml

- POST /tenant/v1/verification-links/batch
+ POST /tenant/v1/kyc/verification-links/batch

- GET  /tenant/v1/audit
+ GET  /tenant/v1/kyc/audit
```

***

## Обратная совместимость [#обратная-совместимость]

Прежние пути (`/tenant/v1/applicants/`, `/tenant/v1/verification-links/` и др.) будут поддерживаться до отдельного уведомления. Минимальный срок предупреждения о прекращении поддержки составляет **3 (три) месяца**. Информация о конкретной дате будет направлена по электронной почте и опубликована в журнале изменений (changelog).

***

## Значение миграции для работы с KYB [#значение-миграции-для-работы-с-kyb]

API KYB функционирует **исключительно** по каноническим путям: `/tenant/v1/kyb/*`. Разделение на `/kyc/` и `/kyb/` обеспечивает:

* раздельные API-ключи для KYC и KYB с независимыми правами доступа;
* независимое версионирование двух продуктов;
* однозначную идентификацию операций в журналах аудита и системах мониторинга.

***

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

### Необходимо ли выполнить миграцию немедленно? [#необходимо-ли-выполнить-миграцию-немедленно]

Нет. Существующие интеграции продолжают функционировать без изменений. Рекомендуется выполнить миграцию при очередном плановом обновлении.

### Изменился ли формат запросов и ответов? [#изменился-ли-формат-запросов-и-ответов]

Да. Начиная с 21 апреля 2026 года все поля в телах запросов, ответов и в payload вебхуков используют `snake_case` (например, `flow_id`, `external_user_id`, `verification_link`). Прежний `camelCase`-формат (`flowId`, `externalUserId`, `verificationLink`) продолжает приниматься на входе и дублируется в ответах для совместимости; срок поддержки этого переходного режима будет объявлен отдельно. При разработке новых интеграций используйте исключительно `snake_case`.

Заголовки аутентификации, параметры query и структура URL-адресов, помимо перехода на префиксы `/kyc/` и `/kyb/`, остаются без изменений.

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

Включите логирование HTTP-запросов к API OneKYC на стороне вашего сервера и убедитесь, что все URL содержат сегмент `/kyc/` после `/tenant/v1/`.

***

По вопросам, связанным с процессом миграции, обращайтесь в службу технической поддержки: **info@onekyc.io**.