Интеграция с Web SDK

1. Что такое RS-ID Web SDK

RS-ID Web SDK позволяет вашему веб-продукту подтвердить, что перед ним реальный, живой человек и что он действительно тот, за кого себя выдаёт, — по лицу и по данным государственного реестра Республики Узбекистан.

Вам не нужно разрабатывать работу с камерой, проверку «живости» (liveness) или сравнение лиц. Ваш бэкенд создаёт сессию, пользователь открывает страницу RS-ID (размещена на стороне RS-ID), делает селфи, а RS-ID:

проверяет, что на селфи живой человек, а не фото, экран или маска (анти-спуфинг);

получает официальное фото из паспорта и данные гражданина из государственного реестра;

сравнивает селфи с фото из паспорта;

возвращает пользователя на ваш сайт и передаёт вашему бэкенду подтверждённый профиль гражданина.

Сценарии использования

Сценарий	Пример
Удалённая идентификация клиента (KYC)	Банк, микрофинансовая или страховая компания открывает счёт онлайн, без визита в офис.
Подтверждение личности перед важным действием	Подтверждение владельца аккаунта перед крупным переводом, сбросом пароля или сменой номера телефона.
Онлайн-подписание договоров	Проверка того, что договор займа или аренды подписывает именно этот гражданин.
Проверка возраста / личности	Маркетплейсы, телеком, игровые сервисы или службы доставки, которым нужно подтвердить возраст или реальную личность.
Автозаполнение регистрации	Пользователь только делает селфи, а ваша форма заполняется подтверждёнными ФИО, документом и датой рождения.

2. Терминология

Термин	Кто это
Клиент	Компания, которая интегрирует RS-ID (вы). Зарегистрирована в RS-ID и получила `client_id` / `client_secret`. Включает бэкенд клиента (вызывает API RS-ID) и фронтенд клиента (ваш сайт, который направляет пользователя на страницу RS-ID).
Пользователь	Конечный человек, которого идентифицируют, — ваш клиент, гражданин Узбекистана.
Сервер	Сервер RS-ID: API Web SDK и страница RS-ID (`<rsid_base_url>`), на которой пользователь делает селфи.
Сессия	Одна попытка идентификации, созданная бэкендом клиента. Определяется `session_id` (UUID). Имеет ограниченный срок жизни и ограниченное число попыток.
ПИНФЛ	Персональный идентификационный номер физического лица — 14 цифр.
Номер документа (`id_number`)	Серия и номер паспорта или ID-карты, например `AA1234567`.

3. Типы интеграции

Страницу RS-ID можно показать пользователю двумя способами. Вызовы API одинаковые; отличается только способ открытия страницы.

3.1 Redirect flow (переход по ссылке)

Фронтенд клиента перенаправляет браузер пользователя на страницу RS-ID. После успешной идентификации страница RS-ID возвращает пользователя на ваш redirect_url.

Самая простая интеграция, работает в браузерах на компьютере и на мобильных устройствах.

На время проверки пользователь уходит с вашего сайта.

или

3.2 iFrame flow (встраивание)

Фронтенд клиента встраивает страницу RS-ID в <iframe> на своей странице, и пользователь не покидает ваш сайт.

Требования:

allow="camera" обязателен — без него браузер заблокирует камеру внутри iframe.

Ваша страница должна открываться по HTTPS.

После успешной идентификации iframe переходит на ваш redirect_url. Укажите в redirect_url небольшую страницу на своём домене, которая уведомит родительское окно, например:

4. Схема интеграции

5. Окружения

Окружение	Базовый URL API	Страница RS-ID
Stage (тестовое)	`https://sdk.stage.rsid.uz/web/api`	`https://sdk.stage.rsid.uz/?session_id={session_id}`
Production	`https://sdk.rsid.uz/web/api`	`https://sdk.rsid.uz/?session_id={session_id}`

Для stage и production используются разные client_id / client_secret. Сессия, созданная на stage, открывается только на stage-странице, и наоборот.

6. Общие правила

Формат ответа

Все ответы API имеют одинаковую структуру:

{ "data": { }, "code": 0, "message": "Success" }

Поле	Тип	Описание
`code`	integer	`0` — успех. Любое другое значение — ошибка (см. таблицы ошибок). Всегда проверяйте `code`, а не только HTTP-статус.
`message`	string	Текст на языке запроса (uz / ru / en). Не разбирайте его программно.
`data`	any	Данные ответа. Отсутствует при ошибке.

Заголовки

Заголовок	Значение	Где используется
`Content-Type`	`application/json`	Все POST-запросы
`Authorization`	`Bearer {access_token}`	Все запросы, кроме `sign-in`
`Accept-Language`	`uz` / `ru` / `en`	Необязательно — язык поля `message`

Безопасность. client_secret и access_token должны храниться только на бэкенде клиента. Никогда не передавайте их в браузер. Фронтенду клиента нужен только session_id.

7. Описание API

Обменивает учётные данные клиента на токен доступа.

Метод - POST
Endpoint - {base_url}/v1/auth/sign-in — без заголовка Authorization
Content-Type (заголовок) - application/json

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`client_id`	string	Да	Не пустое; не может начинаться с цифры	Идентификатор клиента, выданный RS-ID.
`client_secret`	string	Да	Не пустое	Секрет клиента, выданный RS-ID.

{
  "client_id": "web-sdk-client",
  "client_secret": "s3cr3t-value"
}

Ответ

Поле	Тип	Описание
`data.access_token`	string (JWT)	Токен для заголовка `Authorization: Bearer`.
`data.token_type`	string	Всегда `Bearer`.
`data.expires_in`	integer	Срок жизни токена в секундах.
`data.scope`	string	Выданные права, через пробел.
`data.refresh_token`	string (JWT)	Токен для получения нового `access_token` без повторной отправки учётных данных.
`code`	integer	`0` при успехе.
`message`	string	Текст результата.

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "code": 0,
  "message": "Success"
}

Обновление токена — POST {base_url}/v1/auth/refresh?token={refresh_token} с обязательными параметрами. Используйте токен повторно до истечения срока, а не авторизуйтесь заново для каждой сессии.

7.2 Обновление токена (Refresh token)

Выдаёт новый access_token по refresh_token без повторной авторизации. Вызывайте, когда access_token истёк (через expires_in секунд).

Метод - POST
Endpoint - {base_url}/v1/auth/refresh?token={refresh_token} — без заголовка Authorization.
Content-Type (заголовок) - application/json

Query-параметры

Поле	Тип	Обязательно	Длина / формат	Описание
`token`	string	Да	JWT	`refresh_token` из авторизации (7.1) или из предыдущего ответа обновления.
`client_id`	string	Да	Не пустое	Идентификатор клиента, выданный RS-ID.

Ответ

Поле	Тип	Описание
`data.access_token`	string (JWT)	Новый токен для заголовка `Authorization: Bearer`.
`data.token_type`	string	Всегда `Bearer`.
`data.expires_in`	integer	Срок жизни токена в секундах.
`data.scope`	string	Выданные права, через пробел.
`code`	integer	`0` при успехе.
`message`	string	Текст результата.

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write"
  },
  "code": 0,
  "message": "Success"
}

Если refresh-токен истёк или недействителен, авторизуйтесь заново (7.1).

7.3 Создание сессии

Создаёт сессию идентификации для одного пользователя. Каждая сессия привязана к ip_address пользователя. Это гарантирует, что сессия работает только на текущем устройстве пользователя и только один раз.

Метод - POST
Endpoint - {base_url}/v1/sessions
Authorization (заголовок) - Bearer {access_token}
Content-Type (заголовок) - application/json

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`client_type`	string (enum)	Да	`WEB`	Канал интеграции. Для Web SDK всегда `WEB`.
`ip_address`	string	Да	IPv4 / IPv6	Публичный IP-адрес пользователя (возьмите его из запроса пользователя к вашему бэкенду). Страница RS-ID работает только с этого IP — см. примечание ниже.
`user_info`	object	Нет	—	Данные гражданина. Передайте, чтобы создать сессию с user_info; не передавайте для сессии без user_info.
`user_info.pinfl`	string	Условно	Ровно 14 цифр	ПИНФЛ. Передавайте либо `pinfl`, либо `id_number`, но не оба.
`user_info.id_number`	string	Условно	9 символов: 2 буквы + 7 цифр, например `AA1234567`	Номер паспорта / ID-карты. Передавайте либо `pinfl`, либо `id_number`, но не оба.
`user_info.birth_date`	string	Да, если передан `user_info`	`dd.MM.yyyy`	Дата рождения. Пользователю должно быть не меньше 16 лет.
`external_id`	string	Нет	—	Ваш собственный идентификатор (заказа, заявки или клиента) для связи сессии с вашими данными. Рекомендуется случайный `uuid`.
`retry_count`	integer	Нет	> 0	Максимальное число попыток. Если не передано, равно 0 или больше системного максимума — используется системный максимум.
`threshold`	number	Нет	`0.0` – `1.0`	Минимальный порог сходства лиц для прохождения. Если не передан, используется значение по умолчанию.
`locale`	string (enum)	Нет	`UZ`, `RU`, `EN`	По умолчанию `UZ`.
`additional_params`	object	Нет	Только ключи ниже	Настройки страницы RS-ID. Любой другой ключ отклоняется.
`additional_params.redirect_url`	string	Рекомендуется	URL	Куда перенаправить пользователя после успешной идентификации (см. 7.6).
`additional_params.lang`	string	Нет	`uz`, `ru`, `en`	Язык страницы RS-ID.
`additional_params.theme`	string	Нет	например `light`, `dark`	Тема страницы RS-ID.
`additional_params.primary_color`	string	Нет	Цвет в HEX, например `#1A73E8`	Акцентный цвет страницы RS-ID.

Порог (threshold). threshold — минимальная оценка сходства лиц (от 0.0 до 1.0), которую селфи должно получить при сравнении с фото из паспорта, чтобы идентификация прошла. Если параметр не передан, используется значение по умолчанию 0.5. Если вы передаёте его сами, рекомендуем значение выше 0.5. Для высокоточной (строгой) идентификации передавайте значение выше 0.7. Чем выше значение, тем строже проверка и ниже риск, что пройдёт другой человек, но настоящим пользователям может понадобиться больше попыток.

Привязка к IP. Сессия привязана к ip_address. Когда пользователь открывает страницу RS-ID, RS-ID сравнивает его IP с этим значением. Если они не совпадают, страница показывает ошибку (-1028). Передавайте реальный публичный IP пользователя, а не IP вашего сервера.

Примеры запросов — выберите вариант:

Сессия с user_info

Вариант 1 — Сессия с user_info

Бэкенд клиента уже знает данные пользователя. Страница RS-ID сразу откроет камеру.

{
  "client_type": "WEB",
  "ip_address": "84.54.70.12",
  "external_id": "ORDER-123",
  "retry_count": 3,
  "threshold": 0.7,
  "locale": "UZ",
  "user_info": {
    "pinfl": "12345678901234",
    "birth_date": "01.01.1990"
  },
  "additional_params": {
    "redirect_url": "https://shop.example.uz/kyc/done?order=ORDER-123",
    "lang": "uz"
  }
}

С номером документа вместо ПИНФЛ:

"user_info": { "id_number": "AA1234567", "birth_date": "01.01.1990" }

Сессия без user_info

Ответ

Поле	Тип	Длина / формат	Описание
`data`	string	UUID, 36 символов	`session_id`. Используйте его, чтобы открыть страницу RS-ID и получить результат.
`code`	integer		`0` при успехе.
`message`	string		Текст результата.

{
  "data": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": 0,
  "message": "Success"
}

Ошибки

Код	Причина
`-1000`	Некорректный запрос — например, в `user_info` переданы оба поля `pinfl` / `id_number` или ни одного.
`-1002`	Учётные данные не принадлежат клиенту Web SDK.
`-1024`	Неверный формат `id_number`.
`-1025`	Неверный формат `pinfl`.
`-1026`	Не передан `birth_date`.
`-1034`	Неизвестный ключ в `additional_params`.
`-1052`	`threshold` вне диапазона 0–1.
`-1090`	Пользователю меньше 16 лет.
`400`	Ошибка валидации поля, например `ip address cannot be blank`.

7.4 Открытие страницы RS-ID

По session_id фронтенд клиента открывает страницу RS-ID — переходом (3.1) или в iFrame (3.2):

Окружение	URL
Stage	`https://sdk.stage.rsid.uz/?session_id={session_id}`
Production	`https://sdk.rsid.uz/?session_id={session_id}`

У сессии ограничены срок жизни и число попыток. Открывайте страницу сразу после создания сессии; если сессия истекла, создайте новую.

7.5 Действия пользователя на странице RS-ID

У страницы RS-ID два режима. Какой из них увидит пользователь, зависит от того, как была создана сессия в 7.3:

Режим страницы	Когда показывается	Что делает пользователь
with_info	Сессия создана без `user_info` (Вариант 2)	Вводит свои данные, затем делает селфи
without_info	Сессия создана с `user_info` (Вариант 1)	Только делает селфи

with_info — ввод данных, затем камера

Сначала странице нужны данные пользователя.

Пользователь вводит серию и номер паспорта или ПИНФЛ и дату рождения (дд.мм.гггг), затем нажимает Далее.

Страница запрашивает доступ к камере. Пользователь нажимает Разрешить в окне браузера или Разрешить доступ на странице.

Открывается камера (тот же экран, что в режиме without_info ниже). Пользователь размещает лицо в круге, и делается селфи.

RS-ID проверяет «живость» и сравнивает лицо с фото из паспорта указанного человека.

При успехе пользователь перенаправляется на redirect_url (7.6).

without_info — только камера

Данные пользователя уже известны, поэтому страница сразу переходит к камере.

Страница запрашивает доступ к камере — тот же экран, что на шаге 2 режима with_info выше. Пользователь разрешает доступ.

Открывается камера. Пользователь размещает лицо в круге. Пока лицо не найдено, круг красный и на странице написано «Лицо не обнаружено»; как только лицо в нужном положении, делается селфи.

RS-ID проверяет «живость» и сравнивает лицо с фото из паспорта.

При успехе пользователь перенаправляется на redirect_url (7.6).

Неудачные попытки

Если пользователь запретил доступ к камере, страница не может продолжить — пользователю нужно разрешить камеру в настройках браузера и перезагрузить страницу.

Если селфи отклонено (обнаружена подделка, лицо не совпало, гражданин не найден), страница показывает причину и позволяет повторить попытку, пока остаются попытки (retry_count). Когда попытки закончились или сессия истекла, страница показывает ошибку, и клиенту нужно создать новую сессию.

7.6 Перенаправление после успешной идентификации

После успешной идентификации страница RS-ID перенаправляет пользователя на additional_params.redirect_url из запроса создания сессии.

В redirect flow браузер пользователя возвращается на ваш сайт.

В iFrame flow iframe переходит на redirect_url; используйте это, чтобы уведомить родительскую страницу (см. 3.2).

Добавьте в redirect_url свой идентификатор (например ?order=ORDER-123), чтобы понимать, какая сессия завершилась. Затем бэкенд клиента получает результат (7.7).

Не считайте сам факт перенаправления подтверждением идентификации — этот URL может открыть кто угодно. Всегда проверяйте результат с бэкенда через 7.7.

7.7 Получение результата идентификации

Бэкенд клиента получает подтверждённый профиль гражданина.

Метод - GET
Endpoint - {base_url}/v1/user/{session_id}
Authorization (заголовок) - Bearer {access_token}

Параметры пути

Поле	Тип	Обязательно	Длина / формат	Описание
`session_id`	string	Да	UUID, 36 символов	Из 7.3.

Ответ

Поле	Тип	Описание
`data.session_id`	string	Идентификатор сессии.
`data.comparison_value`	number	Оценка сходства лиц, 0–1.
`data.note`	string	Примечание об ошибке, если есть.
`data.profile.user_info.first_name`	string	Имя.
`data.profile.user_info.last_name`	string	Фамилия.
`data.profile.user_info.middle_name`	string	Отчество.
`data.profile.user_info.pinfl`	string	ПИНФЛ, 14 цифр.
`data.profile.user_info.gender`	string	Пол.
`data.profile.user_info.birth_date`	string	`yyyy-MM-dd`.
`data.profile.user_info.birth_place`	string	Место рождения.
`data.profile.user_info.birth_country`	string	Страна рождения.
`data.profile.user_info.nationality`	string	Национальность.
`data.profile.user_info.citizenship`	string	Гражданство.
`data.profile.document_info.document`	string	Серия и номер документа.
`data.profile.document_info.type`	string	Тип документа.
`data.profile.document_info.issued_by`	string	Кем выдан.
`data.profile.document_info.issued_at`	string	Дата выдачи, `yyyy-MM-dd`.
`data.profile.document_info.expiry_at`	string	Срок действия, `yyyy-MM-dd`.
`data.profile.permanent_address`	object	`country`, `country_id`, `region_id`, `district_id`, `address`.
`data.profile.temporary_address`	object	Может быть `null`.

{
  "data": {
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "comparison_value": 0.93,
    "profile": {
      "user_info": {
        "first_name": "ALISHER",
        "last_name": "KARIMOV",
        "middle_name": "BAXTIYOROVICH",
        "pinfl": "12345678901234",
        "gender": "MALE",
        "birth_date": "1990-01-01",
        "birth_place": "TOSHKENT",
        "birth_country": "UZBEKISTAN",
        "nationality": "UZBEK",
        "citizenship": "UZBEKISTAN"
      },
      "document_info": {
        "document": "AA1234567",
        "type": "PASSPORT",
        "issued_by": "IIV 26283",
        "issued_at": "2018-05-10",
        "expiry_at": "2028-05-09"
      },
      "contact_info": {},
      "permanent_address": {
        "country": "UZBEKISTAN",
        "country_id": 182,
        "region_id": 26,
        "district_id": 2603,
        "address": "..."
      },
      "temporary_address": null
    }
  },
  "code": 0,
  "message": "Success"
}

Ошибки

Код	Причина
`-1005`	Идентификация не прошла.
`-1027`	Сессия истекла — запрашивайте результат сразу после перенаправления.
`-1029`	Сессия не найдена.
`-1002`	Сессия принадлежит другому клиенту.

8. Коды ошибок

Код	Название	Значение
`0`	SUCCESS	Успех.
`-5`	BAD_CREDENTIALS	Неверные учётные данные или пользователь токена не найден.
`-9`	SYSTEM_ERROR	Непредвиденная ошибка сервера.
`-1000`	BAD_REQUEST	Некорректный запрос.
`-1002`	CLIENT_NOT_PERMITTED	Недоступно для этого клиента.
`-1005`	UNSUCCESS_JOB	Идентификация не прошла.
`-1008`	IDENTIFICATION_FAILED	Лицо не совпало.
`-1024`	INVALID_ID_NUMBER	Неверный номер документа.
`-1025`	INVALID_PINFL	Неверный ПИНФЛ.
`-1026`	BIRTH_DATE_NOT_NULL	Требуется дата рождения.
`-1027`	SESSION_EXPIRED	Сессия истекла.
`-1028`	IP_RESTRICTED_FOR_SESSION	IP пользователя не совпадает с `ip_address` сессии.
`-1029`	JOB_SESSION_NOT_FOUND	Сессия не найдена.
`-1031`	RETRY_COUNT_EXPIRED	Попытки закончились.
`-1032`	SUCCESS_JOB_EXISTS_FOR_SESSION	Сессия уже успешно пройдена.
`-1033`	SPOOFED_FILE_DETECTED	Проверка «живости» не пройдена.
`-1034`	ADDITIONAL_PARAMS_INVALID	Неизвестный ключ в `additional_params`.
`-1052`	INVALID_THRESHOLD_LIMIT	`threshold` вне диапазона 0–1.
`-1090`	USER_AGE_OLDER_THAN_16	Пользователю должно быть не меньше 16 лет.
`-2001`	AI_ERROR	Ошибка сервиса распознавания лиц.

Руководство по интеграции

Интеграция с Web SDK#

1. Что такое RS-ID Web SDK#

Сценарии использования#

2. Терминология#

3. Типы интеграции#

3.1 Redirect flow (переход по ссылке)#

3.2 iFrame flow (встраивание)#

4. Схема интеграции#

5. Окружения#

6. Общие правила#

Формат ответа#

Заголовки#

7. Описание API#

7.1 Авторизация (Sign in)#

7.2 Обновление токена (Refresh token)#

7.3 Создание сессии#

Вариант 1 — Сессия с user_info#

7.4 Открытие страницы RS-ID#

7.5 Действия пользователя на странице RS-ID#

with_info — ввод данных, затем камера#

without_info — только камера#

Неудачные попытки#

7.6 Перенаправление после успешной идентификации#

7.7 Получение результата идентификации#

8. Коды ошибок#

Интеграция с Web SDK

1. Что такое RS-ID Web SDK

Сценарии использования

2. Терминология

3. Типы интеграции

3.1 Redirect flow (переход по ссылке)

3.2 iFrame flow (встраивание)

4. Схема интеграции

5. Окружения

6. Общие правила

Формат ответа

Заголовки

7. Описание API

7.1 Авторизация (Sign in)

7.2 Обновление токена (Refresh token)

7.3 Создание сессии

Вариант 1 — Сессия с user_info

7.4 Открытие страницы RS-ID

7.5 Действия пользователя на странице RS-ID

with_info — ввод данных, затем камера

without_info — только камера

Неудачные попытки

7.6 Перенаправление после успешной идентификации

7.7 Получение результата идентификации

8. Коды ошибок