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

Описание измененийCopy Anchor Link

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

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

Порядок миграцииCopy Anchor Link

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

- 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:

- 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

Обратная совместимостьCopy Anchor Link

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

Значение миграции для работы с KYBCopy Anchor Link

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

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

Часто задаваемые вопросыCopy Anchor Link

Необходимо ли выполнить миграцию немедленно?Copy Anchor Link

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

Изменился ли формат запросов и ответов?Copy Anchor Link

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

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

Как проверить корректность миграции?Copy Anchor Link

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

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