🔐 Руководство по интеграции API-ключа RS-Imzo

Этот документ объясняет, как интегрировать вашу систему с RS-Imzo, используя аутентификацию по API-ключу для подписания и проверки электронных документов.

🧩 Обзор

Интеграция с RS-Imzo позволяет сторонним системам:

Зарегистрироваться и получить API-ключ и публичный ключ
Подтвердить регистрацию домена с помощью публичного ключа (frontend)
Использовать API-ключ (backend) для проверки PKCS#7-подписей, объединения или аутентификации

🧱 Этапы интеграции

Вход в кабинет RS-Imzo
- Перейдите в кабинет вашей организации в системе RS-Imzo.
- Откройте раздел API Интеграция.
- Зарегистрируйтесь для интеграции API.
Получение ключей
- После регистрации вы получите:
  - Публичный ключ — используется на фронтенде для проверки домена.
  - API-ключ — используется на бекенде для работы с подписями.

⚙️ Интеграция Backend

После того как фронтенд получает PKCS#7-подпись, бекенд использует API RS-Imzo, чтобы выполнять проверку подписи, объединение подписей и аутентификацию, используя стандарт PKCS#7.

Базовый URL

$base_url=https://api.rs-imzo.uz/api/v1/backend

⚙️ Точки API

Метод	Эндпоинт	Описание
`POST`	`/pkcs7/verify`	Проверить PKCS#7 подпись
`POST`	`/pkcs7/merge`	Объединить две PKCS#7 подписи
`POST`	`/auth`	Аутентифицировать и извлечь данные пользователя

🧩 Заголовки

Все запросы требуют следующих заголовков:

Заголовок	Описание
`X-API-KEY`	Уникальный API-ключ вашей организации
`Content-Type`	Всегда `application/x-www-form-urlencoded`

Пример:

X-API-KEY: your-api-key
Content-Type: application/x-www-form-urlencoded

🧾 Параметры запроса

Поле	Тип	Описание
`pkcs7`	`string`	PKCS#7 подпись в Base64
`detachedData`	`string`	(Опционально) Отдельные данные, если есть

🧾 Информация об объекте ответа

Поле	Тип	Описание
`data`	`string`	Данные, подписанные пользователем (в Base64)
`detached`	`boolean`	Указывает, используется ли подпись как attached или detached
`signers`	`List<Signer>`	Список подписантов в PKCS#7
`certificate`	`Object`	Информация о пользователе, издателе, валидности и др.
`digest`	`string`	Подписанное содержимое в формате `md5`
`signed_time`	`date`	Время подписи
`verified`	`boolean`	Указывает, прошла ли подпись проверку
`issuer`	`Object`	Объект с данными издателя подписи
`serial`	`string`	Уникальный идентификатор подписи
`subject`	`Object`	Объект с данными пользователя
`validity`	`Object`	Срок действия подписи
`C`	`string`	Страна издателя или субъекта
`CN`	`string`	Полное имя владельца подписи
`O`	`string`	Название организации
`1.3.6.1.4.1.64375.1.2`	`string`	ПИНФЛ владельца подписи
`1.3.6.1.4.1.64375.1.1`	`string`	ИНН организации
`not_after`	`date`	Действительна до этой даты
`not_before`	`date`	Действительна с этой даты

💻 Пример на Java

Ниже приведён пример использования API RS-Imzo в стиле Java с использованием RestTemplate из Spring. (Код полностью совпадает с англоязычным примером, изменены только комментарии.)

🧩 Контрольный список интеграции

✅ Получите X-API-KEY у администратора RS-Imzo.
✅ Реализуйте сервис RSImzoClient.
✅ Протестируйте API verify, merge, auth в вашем приложении.
✅ Логируйте все неудачные попытки верификации.

🧠 Итог

Компонент	Назначение	Аутентификация
Frontend	Проверка домена	`Authorization: Bearer <PUBLIC_KEY>`
Backend	Проверка, объединение или аутентификация PKCS#7	`X-API-Key: <API_KEY>`

🔒 Примечания

Никогда не раскрывайте API-ключ на фронтенде.
Публичный ключ можно использовать только для клиентской валидации.
PKCS#7 — это контейнер подписи, он не должен изменяться между проверкой и объединением.
Если верификация не проходит, убедитесь, что:
- apiKey принадлежит правильной организации.
- Подпись не была изменена или не истек срок её действия.