Подписание по QR-коду электронной подписью (RS-IMZO / E-IMZO)

1. Что такое подписание по QR-коду

Подписание по QR-коду позволяет пользователю подписать содержимое с вашего сайта своей электронной подписью (RS-IMZO или E-IMZO), которая хранится в мобильном приложении RS-ID.

Ваш бэкенд создаёт QR-токен с содержимым для подписи. Ваш сайт показывает QR-код; пользователь сканирует его в мобильном приложении RS-ID, видит содержимое, выбирает ключ подписи и подписывает. RS-ID проверяет подпись, отправляет подписанные данные (PKCS#7) на ваш callback_url и отмечает QR-токен как завершённый.

Вам не нужно устанавливать плагины E-IMZO или работать с ключами подписи на сайте — подписание происходит на телефоне пользователя.

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

Сценарий	Пример
Подписание документов	Пользователь подписывает договор займа, аренды или оказания услуг, показанный на вашем сайте.
Согласование несколькими подписантами	Документ должны подписать определённые люди или компании (по ПИНФЛ или ИНН); QR завершается, когда подписали все.
Вход с электронной подписью	Ваш сайт помещает одноразовую случайную строку в `sign_content`; пользователь подписывает её, и после проверки подписи вы выполняете вход.
Подтверждение операции	Подписание платёжного поручения или заявки перед обработкой.

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

Термин	Кто / что это
Клиент	Компания, которая интегрирует RS-ID (вы). Зарегистрирована в RS-ID как клиент Web SDK и получила `client_id` / `client_secret`. Включает бэкенд клиента и фронтенд клиента.
Пользователь	Человек, который подписывает, — у него есть мобильное приложение RS-ID с добавленной электронной подписью.
Мобильное приложение RS-ID	Приложение RS-ID на телефоне пользователя. Хранит электронные подписи пользователя и подписывает содержимое.
Сервер	Сервер RS-ID: создаёт QR-токены, проверяет подписи и отправляет callback.
QR-токен	Один запрос на подписание, определяется `qr_id`. Имеет срок жизни (`expire_time`) и статус.
RS-IMZO / E-IMZO	Типы электронной подписи (`sign_method`).
Подписант	Человек или компания, которым разрешено подписать, определяются по ПИНФЛ (14 цифр, физическое лицо) или ИНН (9 цифр, компания).
PKCS#7	Стандартный формат подписанных данных (CMS), который RS-ID отправляет на ваш `callback_url`.

3. Как это работает

Ваш бэкенд проходит авторизацию (7.1) и создаёт QR-токен с содержимым для подписи (7.3).

Ваш сайт показывает QR-код пользователю.

Пользователь сканирует его в мобильном приложении RS-ID, читает содержимое и подписывает ключом RS-IMZO или E-IMZO (7.4).

RS-ID проверяет подпись и то, что подписанту разрешено подписывать.

RS-ID отправляет подписанные данные (PKCS#7) на ваш callback_url (7.5).

Ваш бэкенд проверяет статус QR (7.6 / 7.7), пока он не станет COMPLETED или EXPIRED.

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

5. Окружения

Окружение	Базовый URL API	Ссылка (внутри QR-кода)
Stage (тестовое)	`https://sdk.stage.rsid.uz/web/api`	`https://auth.stage.rsid.uz/{qr_id}`
Production	`https://sdk.rsid.uz/web/api`	`https://auth.rsid.uz/{qr_id}`

Для stage и production используются разные client_id / client_secret. QR-код, созданный на stage, сканируется только stage-версией приложения RS-ID.

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 и access_token хранятся только на вашем бэкенде. Фронтенду нужно только изображение или ссылка QR.

Проверяйте PKCS#7 сами, когда приходит callback: что подпись действительна, что подписанное содержимое совпадает с вашим sign_content и что сертификат принадлежит ожидаемому лицу (ПИНФЛ / ИНН).

Используйте HTTPS для callback_url и сопоставляйте callback со своей записью по external_id.

7. Описание API

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

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

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`client_id`	string	Да	Не пустое; не может начинаться с цифры	Идентификатор клиента Web SDK, выданный 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"
}

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

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

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

7.3 Создание QR-токена

Создаёт запрос на подписание и возвращает QR-код.

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

Тело запроса

Поле	Тип	Обязательно	Длина / формат	Описание
`sign_content`	string	Да	Не пустое	Содержимое, которое подписывает пользователь. Показывается пользователю в приложении RS-ID.
`expire_time`	integer	Да	> 0, секунды	Срок жизни QR-токена в секундах, например `300` (5 минут).
`sign_method`	string (enum)	Нет	`RS_IMZO`, `E_IMZO`	Разрешённый тип подписи. Если не передан, пользователь может подписать любой своей подписью.
`signers`	array	Нет	—	Кому разрешено подписать. Если не передан, подписать может любой пользователь, один раз. Если передан, каждый подписант подписывает один раз, и QR завершается, когда подписали все.
`signers[].signer`	string	Да, если передан `signers`	ПИНФЛ (14 цифр) или ИНН (9 цифр)	Человек или компания, которым разрешено подписать.
`signers[].allow_id`	string	Нет	—	Дополнительный идентификатор подписанта, сохраняется вместе с подписью.
`external_id`	string	Нет	Уникальный в рамках клиента	Ваш собственный идентификатор (документа или заказа). Позволяет проверять статус по вашему id (7.7). Должен быть уникальным — повтор возвращает `-1080`.
`callback_event`	object	Нет	—	Настройки callback.
`callback_event.callback_url`	string	Рекомендуется	HTTPS URL	Куда RS-ID отправит подписанные данные после каждой подписи (7.5).
`redirect_url`	string	Нет	URL	Ссылка, которая возвращается в приложение RS-ID после подписания.
`document_provider_type`	string (enum)	Нет	`HUJJAT_UZ`, `DIDOX`	Провайдер документа, если документ из него.
`qr_response_type`	string (enum)	Нет	`BASE64`, `DATA`, `ALL`	Что вернуть. По умолчанию `BASE64`. `BASE64` — изображение PNG; `DATA` — ссылка внутри QR; `ALL` — оба.
`width`	integer	Нет	px	Ширина изображения QR. По умолчанию `100`.
`height`	integer	Нет	px	Высота изображения QR. По умолчанию `100`.

Примеры запросов

Подписывает любой пользователь

{
  "sign_content": "Договор № A-7781 от 09.11.2026. Я согласен с условиями договора об оказании услуг.",
  "expire_time": 300,
  "sign_method": "RS_IMZO",
  "external_id": "CONTRACT-A-7781",
  "callback_event": {
    "callback_url": "https://shop.example.uz/webhooks/rsid/sign"
  },
  "qr_response_type": "ALL",
  "width": 256,
  "height": 256
}

Определённые подписанты

Вход с электронной подписью

Ответ

Поле	Тип	Описание
`data.qr_id`	string	Идентификатор QR-токена. Используйте его в 7.6.
`data.qr_base64`	string	QR-код в виде изображения PNG в base64. Возвращается для `BASE64` и `ALL`.
`data.qr_data`	string	Ссылка внутри QR-кода (`https://auth.rsid.uz/{qr_id}`). Возвращается для `DATA` и `ALL`.
`data.expire_at`	string	Время истечения, `yyyy-MM-dd HH:mm:ss`.
`data.qr_status`	string	`ACTIVE` для нового токена.
`code`	integer	`0` при успехе.
`message`	string	Текст результата.

{
  "data": {
    "qr_id": "9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_data": "https://auth.rsid.uz/9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+...",
    "expire_at": "2026-11-09 17:35:00",
    "qr_status": "ACTIVE"
  },
  "code": 0,
  "message": "Success"
}

Показывайте изображение через <img src="data:image/png;base64,{qr_base64}"> или рисуйте свой QR по qr_data.

Ошибки

Код	Причина
`-1002`	Учётные данные не принадлежат клиенту Web SDK.
`-1080`	QR-токен с таким `external_id` уже существует.
`-5`	Пользователь токена не найден.
`400`	Ошибка валидации, например `sign content cannot be blank` или `expire_time` не передан / не положительный.

7.4 Действия пользователя в мобильном приложении RS-ID

Пользователь открывает мобильное приложение RS-ID и сканирует QR-код.

Приложение показывает содержимое для подписи (sign_content).

Пользователь выбирает электронную подпись (если задан sign_method, показываются только ключи этого типа). Если заданы signers, можно использовать только подписи с разрешённым ПИНФЛ / ИНН.

Пользователь подписывает. Приложение отправляет подпись (PKCS#7) в RS-ID.

RS-ID проверяет подпись и отправляет callback (7.5).

Приложение показывает ошибку, и подпись не принимается, если:

Ситуация	Результат
Срок QR-токена истёк	`QR token expired` — создайте новый QR-токен.
QR-токен уже завершён	`QR token completed`.
ПИНФЛ / ИНН подписи нет в `signers`	Пользователю не разрешено подписывать.
Этот подписант уже подписал	Документ уже подписан этой подписью.
Все подписанты уже подписали	Документ полностью подписан.

7.5 Callback с подписанными данными

После каждой успешной подписи RS-ID отправляет POST-запрос на callback_event.callback_url.

Метод - POST
URL - ваш callback_url
Content-Type - application/json

Тело запроса (отправляет RS-ID)

Поле	Тип	Описание
`sign_request_data`	string	JSON вашего исходного запроса на создание (7.3) в виде строки. Найдите свою запись по его `external_id`.
`pkcs7`	string	Подписанные данные, PKCS#7 (CMS) в base64. Содержит подписанное содержимое, подпись и сертификат подписанта.

{
  "sign_request_data": "{\"signers\":null,\"expire_time\":300,\"sign_method\":\"RS_IMZO\",\"sign_content\":\"Договор № A-7781 от 09.11.2026. Я согласен с условиями договора об оказании услуг.\",\"redirect_url\":null,\"external_id\":\"CONTRACT-A-7781\",\"document_provider_type\":null,\"callback_event\":{\"callback_url\":\"https://shop.example.uz/webhooks/rsid/sign\"},\"qr_response_type\":\"ALL\",\"width\":256,\"height\":256}",
  "pkcs7": "MIIKvgYJKoZIhvcNAQcCoIIKrzCCCqsCAQExDjAMBggqhlADAgIBAQUAMIIBDgYJKoZIhvcNAQcBoIIA..."
}

Ваш ответ — верните HTTP 200. Callback отправляется один раз и не повторяется, поэтому также проверяйте статус через 7.6 / 7.7.

При нескольких signers callback отправляется после каждой подписи.

7.6 Статус QR-токена по `qr_id`

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

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

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

Ответ

Поле	Тип	Описание
`data.qr_id`	string	Идентификатор QR-токена.
`data.qr_status`	string	`ACTIVE` — ожидает подписи; `COMPLETED` — подписано (всеми `signers`, если заданы); `EXPIRED` — срок истёк; `DELETED` — удалён.
`data.expire_at`	string	Время истечения, `yyyy-MM-dd HH:mm:ss`.
`data.qr_data`	string	Ссылка внутри QR-кода.
`data.qr_base64`	string	Изображение QR (PNG 100×100, base64) — чтобы показать его снова.

{
  "data": {
    "qr_id": "9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_data": "https://auth.rsid.uz/9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAQMAAABKLAcXAAAABlBMVEX///8AAABVwtN+...",
    "expire_at": "2026-11-09 17:35:00",
    "qr_status": "COMPLETED"
  },
  "code": 0,
  "message": "Success"
}

Опрашивайте каждые несколько секунд, пока qr_status = ACTIVE.

Ошибки

Код	Причина
`-1035`	QR-токен не найден или принадлежит другому клиенту.
`-1002`	Учётные данные не принадлежат клиенту Web SDK.

7.7 Статус QR-токена по `external_id`

То же, что 7.6, но по вашему external_id из 7.3.

Метод - GET
Endpoint - {base_url}/v1/qr/status/by-external/{external_id}
Authorization (заголовок) - Bearer {access_token}

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

Поле	Тип	Обязательно	Длина / формат	Описание
`external_id`	string	Да	—	`external_id` из 7.3.

Ответ — как в 7.6.

Ошибки — как в 7.6.

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

Код	Название	Значение
`0`	SUCCESS	Успех.
`-5`	BAD_CREDENTIALS	Неверные учётные данные или пользователь токена не найден.
`-9`	SYSTEM_ERROR	Непредвиденная ошибка сервера.
`-1000`	BAD_REQUEST	Некорректный запрос.
`-1002`	CLIENT_NOT_PERMITTED	Не клиент Web SDK.
`-1035`	INVALID_QR_TOKEN	QR-токен не найден или принадлежит другому клиенту.
`-1080`	QR_TOKEN_EXISTS_BY_EXTERNAL_ID	QR-токен с таким `external_id` уже существует.

Подписание по QR-коду

Подписание по QR-коду электронной подписью (RS-IMZO / E-IMZO)#

1. Что такое подписание по QR-коду#

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

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

3. Как это работает#

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

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

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

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

Заголовки#

Безопасность#

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

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

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

7.3 Создание QR-токена#

7.4 Действия пользователя в мобильном приложении RS-ID#

7.5 Callback с подписанными данными#

7.6 Статус QR-токена по qr_id#

7.7 Статус QR-токена по external_id#

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

Подписание по QR-коду электронной подписью (RS-IMZO / E-IMZO)

1. Что такое подписание по QR-коду

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

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

3. Как это работает

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

5. Окружения

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

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

Заголовки

Безопасность

7. Описание API

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

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

7.3 Создание QR-токена

7.4 Действия пользователя в мобильном приложении RS-ID

7.5 Callback с подписанными данными

7.6 Статус QR-токена по `qr_id`

7.7 Статус QR-токена по `external_id`

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