Выпуск УНЭП

Перед тем как сотрудник подпишет что-либо через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа., эта подпись должна быть ему выпущена. Выпуск — отдельный процесс с жизненным циклом и набором API-методов.

Общие сведения о типах подписей — в разделе Подписи.

Когда использовать

Используйте эту страницу, когда интеграция должна заранее выпустить УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. сотрудникам, сменить канал подтверждения подписи или понять, почему сотрудник не может подписать через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа..

Что нужно заранее

Что нужно	Где получить
tenantHost	Адрес тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink
clientId	Текущий пользователь
Токен с правом на выпуск УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.	Аутентификация и Роли и права доступа
clientUserId сотрудника	Получить пользователей или Получить пользователя клиента по СНИЛС
ФИО и документы сотрудника	В системе-источнике или профиле HRlink
Канал подтверждения	Телефон или email сотрудника

Типовые сценарии

Выпустить УНЭП

1. Найдите пользователя клиента.
2. Вызовите Выпустить УНЭП.
3. Дождитесь состояния FINISHED в lastNQESIssueRequest.

Отменить выпуск

1. Проверьте, что задача выпуска ещё не в терминальном состоянии.
2. Вызовите Отменить выпуск УНЭП.
3. Перечитайте сотрудника и проверьте состояние CANCELED.

Сменить канал подписания

1. Убедитесь, что у сотрудника уже есть выпущенный УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа..
2. Вызовите Сменить канал подписания УНЭП.
3. Проверьте новый nqesConfirmationChannel в данных сотрудника.

Ограничения и ошибки

• Одновременно у сотрудника может идти только один процесс выпуска или смены канала.
• Интегратор не подтверждает выпуск за сотрудника: сотрудник проходит шаги в ЛК HRlink.
• Подписание через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. всегда требует код из SMS или email.
• Провайдера УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. и удалённую идентификацию задаёт администратор тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов., а не запрос API.

Что делает кто

Участник	Что делает
Интегратор	Запускает выпуск, отслеживает прогресс, при необходимости отменяет
Сотрудник	Подтверждает выпуск кодом, проходит идентификацию, принимает выпущенный сертификат — всё через ЛК HRlink
Система HRlink	Генерирует заявление, отправляет уведомления, общается с провайдером, обновляет состояние
Провайдер УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.	Выпускает сертификат. Администратор тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. выбирает провайдера в настройках: Астрал или Контур
Госуслуги	Проверяют личность сотрудника при удалённой идентификации (тип REMOTE)

Интегратор не управляет всем процессом

Через публичный API доступны только три действия: инициация выпуска, отмена и смена канала подписания. Подтверждение выпуска, идентификацию и приём сертификата сотрудник делает сам в ЛК HRlink — публичных методов для этого нет.

Флоу выпуска

Параллельно в любой момент интегратор может отменить процесс — задача перейдёт в CANCELED. Если система не смогла продвинуть процесс после серии повторов, задача уйдёт в AUTO_FAILED.

Методы интегратора

Инициировать выпуск

Выпустить УНЭП — POST /api/v1/clients/{clientId}/users/issue/nqes.

В запросе — массив заявок issueRequests. На каждого сотрудника:

Поле	Описание
clientUserId	IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. пользователя клиента (обязательно)
personIdentificationType	IN_PERSON — очная идентификация с печатью формы; REMOTE — через Госуслуги (обязательно)
firstName, lastName	ФИО для сертификата (обязательны)
phone или email	Хотя бы одно — контакт для отправки уведомления о выпуске и кода подтверждения. После завершения выпуска становится каналом подписания
snils, inn, passport	Данные физлица для сертификата
documentsVerificationEnabled	Проверять документы (СНИЛС, паспорт, ИНН) перед выпуском

После успешного ответа { "result": true } в системе появляется задача выпуска в состоянии CREATED — дальше процесс идёт автоматически.

Нельзя запустить второй выпуск поверх активного

Система отклонит запрос, если у сотрудника уже есть активный УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. или незавершённый процесс выпуска. Сначала дождитесь FINISHED или отмените текущую задачу.

Отменить выпуск

Отменить выпуск УНЭП — POST /api/v1/clients/{clientId}/users/nqesIssues/cancel.

В теле — clientUserId. Отмена возможна из любого нетерминального состояния. Задача перейдёт в CANCELED.

Сменить канал подписания

Сменить канал подписания УНЭП — POST /api/v1/clients/{clientId}/usersByExternalId/{userExternalId}/nqesChannelChangeRequests.

Канал подписания — куда сотрудник получает код подтверждения при каждой операции подписи через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.. Возможные значения: SMS, EMAIL. Система выбирает канал автоматически при выпуске (по данным сотрудника), а после завершения выпуска интегратор меняет его этим методом.

Сменить канал во время выпуска нельзя

Валидация отклонит запрос, если у сотрудника нет выпущенного УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа., или есть активный процесс выпуска, или уже есть незавершённый запрос на смену канала.

Как отслеживать прогресс

Отдельного метода «получить состояние выпуска УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.» нет. Состояние последней задачи выпуска приходит как поле lastNQESIssueRequest внутри UserFullInfoDTO — при чтении сотрудника или пользователя клиента любым из методов:

• Получить список сотрудников
• Получить сотрудника по ID
• Получить сотрудника по externalId
• Получить пользователя клиента по СНИЛС

Внутри lastNQESIssueRequest:

• state — текущее состояние (NqesIssuingState)
• nqesIssueTaskId — IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. задачи выпуска
• provider — ASTRAL или KONTUR
• nqesConfirmationChannel — текущий канал подписания
• Даты переходов: createdDate, applicationCreatedDate, userNotifiedAboutIssueRequestDate, issuingConfirmedDate, nqesIssuedDate, certificateAcceptedDate, finishedDate и другие

Для интеграции это значит: периодически читайте сотрудников и смотрите на state — отдельный polling не нужен, информация есть там же, где остальные данные о сотруднике.

Подписание через УНЭП

После того как выпуск достиг FINISHED, сотрудник может подписывать через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.. Флоу всегда двухшаговый: инициировать → подтвердить кодом.

Что подписываем	Инициация	Подтверждение
Документ	Инициировать подписание документа УНЭП	Подтвердить подписание документа УНЭП
Группа заявлений	Инициировать подписание группы заявлений УНЭП	Подтвердить подписание группы заявлений УНЭП
Пакет массовой подписи	Создать запрос массового подписания УНЭП	Подтвердить массовое подписание УНЭП

После инициации система отправляет сотруднику код на текущий канал подписания (SMS или EMAIL). Сотрудник передаёт код в интеграцию, интеграция вызывает метод подтверждения.

Автоподписание от лица сотрудника через УНЭП не работает

Код подтверждения физически приходит сотруднику — на его телефон или почту. Интегратор не может подписать документ УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. «за сотрудника», даже с использованием мастер-токенаMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. и impersonationImpersonation Выполнение API-запросов от имени другого пользователя при использовании мастер-токена. Пользователь указывается через заголовки Impersonated-User-Id и Impersonated-User-Id-Type.-заголовков. Это принципиально отличает УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. от ПЭППЭП Простая электронная подпись (SES). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания..

Справочник состояний

Полный перечень NqesIssuingState с указанием, кто инициирует переход и что означает состояние.

Состояние	Кто продвигает	Смысл
CREATED	Система	Задача создана
APPLICATION_CREATION_PENDING	Система	Готовится файл заявления
APPLICATION_CREATED	Система	Файл заявления готов, отправляется уведомление сотруднику
USER_NOTIFIED_ABOUT_ISSUE_REQUEST	Сотрудник	Ждём, пока сотрудник подтвердит выпуск в ЛК
ISSUING_CONFIRMED	Система	Сотрудник подтвердил, процесс продолжается
ISSUING_REJECTING_PENDING	Система	Запущен процесс отклонения
PERSON_IDENTIFICATION_CREATED	Сотрудник	Создана задача удалённой идентификации, ждём прохождения через Госуслуги (только для REMOTE)
PERSON_IDENTIFIED	Система	Удалённая идентификация через Госуслуги пройдена (только для REMOTE)
PRINT_FORM_CREATION_PENDING	Система	Готовится печатная формапечатная форма PDF-документ с визуальным оттиском подписей, который система формирует после завершения документооборота. Печатная форма доступна для скачивания и используется для архивного хранения. с оттиском ПЭППЭП Простая электронная подпись (SES). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания.
PRINT_FORM_CREATED	Система	Печатная формапечатная форма PDF-документ с визуальным оттиском подписей, который система формирует после завершения документооборота. Печатная форма доступна для скачивания и используется для архивного хранения. готова
NQES_ISSUE_REQUEST_CREATED	Система	Запрос ушёл в провайдер (Астрал или Контур)
NQES_ISSUED	Система	Провайдер вернул сертификат
USER_NOTIFIED_ABOUT_CERTIFICATE	Сотрудник	Ждём, пока сотрудник примет или отклонит сертификат в ЛК
CERTIFICATE_ACCEPTED	Система	Сотрудник принял — процесс завершается

Терминальные состояния (после них задача не меняется) — сгруппированы по смыслу.

Успех

Состояние	Что произошло	Что делать
FINISHED	УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. успешно выпущен и принят сотрудником	Можно подписывать

Выпуск не состоялся — сертификат так и не был выпущен. С точки зрения бизнес-логики все три состояния равнозначны: сотрудник остаётся без УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа..

Состояние	Что произошло	Что делать
ISSUING_REJECTED	Сотрудник отказался от выпуска на этапе подтверждения	Уточнить с сотрудником и запустить новый выпуск
PERSON_IDENTIFICATION_FAILED	Удалённая идентификация через Госуслуги не прошла	Разобраться с данными и запустить новый выпуск
NQES_ISSUE_REQUEST_FAILED	Провайдер УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. отклонил запрос	Запустить новый выпуск после исправления причины

Сертификат отклонён после выпуска

Состояние	Что произошло	Что делать
CERTIFICATE_DECLINED	Сотрудник отклонил выпущенный сертификат	Запустить новый выпуск

Процесс прерван

Состояние	Что произошло	Что делать
CANCELED	Интегратор отменил процесс	—
AUTO_FAILED	Система превысила лимит попыток автоматических переходов	Обратиться в поддержку

Ограничения

• Один активный процесс на сотрудника. Одновременно может идти либо выпуск, либо смена канала — но не оба сразу.
• Провайдера и возможность удалённой идентификации задаёт администратор тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. в настройках — не параметры запроса.
• Автоподписание (impersonationImpersonation Выполнение API-запросов от имени другого пользователя при использовании мастер-токена. Пользователь указывается через заголовки Impersonated-User-Id и Impersonated-User-Id-Type.) не поддерживается. Для подписи через УНЭПУНЭП Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. нужен реальный сотрудник, который введёт код из SMS или почты.