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

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

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

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

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

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

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

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

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

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

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

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

3. Тип интеграции — нативный SDK

Экраны RS-ID работают внутри вашего приложения через RS-ID SDK. Пользователь не покидает приложение.

Добавьте RS-ID SDK в Android / iOS проект. Пакет и инструкцию по установке RS-ID предоставляет вместе с учётными данными.

Разрешите доступ к камере в приложении:

Android — android.permission.CAMERA в AndroidManifest.xml;

iOS — NSCameraUsageDescription в Info.plist (текст, который увидит пользователь при запросе камеры).

Запустите SDK с session_id, полученным от вашего бэкенда (7.4).

Обработайте результат, который SDK вернёт в приложение, — успех, неудача или отмена пользователем (7.6).

Подтвердите результат на бэкенде через GET /v1/user/{session_id} (7.7).

В отличие от Web SDK, сессии Mobile SDK не привязаны к IP-адресу и не используют redirect_url — результат возвращается в ваше приложение из SDK.

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

5. Окружения

Окружение	Базовый URL API
Stage (тестовое)	`https://sdk.stage.rsid.uz/mobile/api`
Production	`https://sdk.rsid.uz/mobile/api`

Для stage и production используются разные client_id / client_secret. Учётные данные Mobile SDK отличаются от учётных данных Web SDK — клиент Web SDK не может создавать мобильные сессии (-1002).

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` и `refresh`
`Accept-Language`	`uz` / `ru` / `en`	Необязательно — язык поля `message`

Безопасность. client_secret должен храниться только на бэкенде клиента. Никогда не добавляйте его в приложение — файлы приложения можно извлечь. Вызывайте sign-in и создание сессии только с бэкенда.

7. Описание API

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

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

Тело запроса

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

{
  "client_id": "mobile-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"
}

Используйте access_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	Да	Не пустое; не может начинаться с цифры	Идентификатор клиента Mobile SDK, выданный RS-ID.
`client_secret`	string	Да	Не пустое	Секрет клиента, выданный RS-ID.

{
  "client_id": "mobile-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)	Новый refresh-токен для следующего обновления.
`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"
}

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

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

Создаёт сессию идентификации для одного пользователя. Сессия принадлежит вашему клиенту: использовать её можно только с токеном вашего клиента.

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

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`client_type`	string (enum)	Да	`MOBILE`	Канал интеграции. Для Mobile SDK всегда `MOBILE`.
`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 лет.
`session_id`	string	Нет	UUID, 36 символов	Прошлая сессия вашего клиента для этого же пользователя. Новая сессия берёт из неё данные гражданина, и пользователю не нужно вводить их снова. Игнорируется, если передан `user_info`.
`external_id`	string	Нет	—	Ваш собственный идентификатор (заказа, заявки или клиента) для связи сессии с вашими данными. Рекомендуется случайный `uuid`.
`retry_count`	integer	Нет	> 0	Максимальное число попыток. Если не передано, равно 0 или больше системного максимума — используется системный максимум.
`threshold`	number	Нет	`0.0` – `1.0`	Минимальный порог сходства лиц для прохождения. По умолчанию `0.5`. См. примечание ниже.
`locale`	string (enum)	Нет	`UZ`, `RU`, `EN`	По умолчанию `UZ`.
`additional_params`	object	Нет	Только ключи ниже	Настройки экранов RS-ID SDK. Любой другой ключ отклоняется.
`additional_params.lang`	string	Нет	`uz`, `ru`, `en`	Язык экранов SDK.
`additional_params.theme`	string	Нет	например `light`, `dark`	Тема экранов SDK.
`additional_params.primary_color`	string	Нет	Цвет в HEX, например `#1A73E8`	Акцентный цвет экранов SDK.

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

Без привязки к IP и без перенаправления. Мобильные сессии не используют ip_address и redirect_url. Результат возвращается в ваше приложение из SDK (7.6).

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

Сессия с user_info

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

Бэкенд клиента уже знает данные пользователя. SDK сразу откроет камеру.

{
  "client_type": "MOBILE",
  "external_id": "ORDER-123",
  "retry_count": 3,
  "threshold": 0.7,
  "locale": "UZ",
  "user_info": {
    "pinfl": "12345678901234",
    "birth_date": "01.01.1990"
  },
  "additional_params": {
    "lang": "uz"
  }
}

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

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

Сессия без user_info

Повторная проверка (session_id)

Ответ

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

{
  "data": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "code": 0,
  "message": "Success"
}

Ошибки

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

7.4 Запуск RS-ID SDK

По session_id приложение клиента запускает RS-ID SDK.

Ваш бэкенд создаёт сессию (7.3) и возвращает session_id в приложение.

Приложение запускает RS-ID SDK с параметрами:

Параметр	Описание
`session_id`	Из 7.3.
`access_token`	Действующий токен доступа вашего клиента Mobile SDK. SDK использует его для запросов к серверу RS-ID; сервер принимает запросы по сессии только с токеном клиента, который её создал.
Окружение	Stage или production — должно совпадать с окружением, где создана сессия.

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

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

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

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

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

SDK начинается с экрана ввода данных.

Пользователь вводит серию и номер паспорта или ПИНФЛ (JSHSHIR) и дату рождения (DD.MM.YYYY).

Пользователь принимает Пользовательское соглашение и Политику конфиденциальности переключателем. Кнопка Продолжить (Davom etish) становится активной; пользователь нажимает её.

Приложение запрашивает доступ к камере (системное окно). Пользователь разрешает доступ.

Открывается камера с подсказкой «Держите лицо внутри круга» (Yuzingizni doira ichida tuting). Пока лицо не найдено, круг красный; как только лицо в нужном положении, делается селфи.

RS-ID проверяет «живость» и сравнивает лицо с фото из паспорта указанного человека. SDK показывает «Идёт идентификация» (Identifikatsiya amalga oshirilmoqda).

При успехе SDK показывает «Идентификация успешно выполнена!» (Identifikatsiya qilish muvaffaqiyatli amalga oshirildi!) и возвращает результат в приложение (7.6).

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

Приложение запрашивает доступ к камере (системное окно). Пользователь разрешает доступ.

Открывается камера. Пользователь размещает лицо в рамке, и делается селфи.

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

SDK возвращает результат в приложение (7.6).

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

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

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

7.6 Результат в приложении

Когда пользователь завершает проверку, SDK возвращает результат в ваше приложение:

Результат	Что делать
Успех	Сообщите бэкенду, что сессия завершена; бэкенд получает профиль (7.7).
Неудача	Попытки закончились или сессия истекла. Создайте новую сессию (7.3), если пользователь хочет попробовать снова.
Отмена	Пользователь закрыл SDK. Пока сессия активна, SDK можно запустить снова с тем же `session_id`.

Не считайте результат в приложении подтверждением идентификации — приложение работает на устройстве пользователя и может быть изменено. Всегда проверяйте результат с бэкенда через 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": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "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`	Сессия истекла — запрашивайте результат сразу после успеха в SDK.
`-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	Сессия истекла.
`-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	Ошибка сервиса распознавания лиц.

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

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

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

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

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

3. Тип интеграции — нативный SDK#

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

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

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

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

Заголовки#

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

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

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

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

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

7.4 Запуск RS-ID SDK#

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

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

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

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

7.6 Результат в приложении#

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

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

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

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

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

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

3. Тип интеграции — нативный SDK

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

5. Окружения

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

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

Заголовки

7. Описание API

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

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

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

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

7.4 Запуск RS-ID SDK

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

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

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

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

7.6 Результат в приложении

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

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