Уведомления

В сервисе реализованы уведомления по следующим каналам:

• по электронной почте - предназначены для информирования пользователей;
• Webhook - предназначены для информационных систем.

Уведомления по электронной почте

Уведомления по электронной почте могут рассылаться автоматически, а так же по запросу.

Базовые уведомления по электронной почте

Поддерживаются следующие типы базовых уведомлений по электронной почте (email):

1. уведомления о подписании нового документа;
2. уведомления о добавлении подписи к документу;
3. уведомления о добавлении подписи к документу, подписанному пользователем;
4. уведомление о превышении квоты архива подписанных данных;
5. уведомление об истечении срока действия квоты архива подписанных данных;
6. уведомления о предрегистрации документа;
7. уведомления о регистрации нового пакета документов.

Сервис рассылает уведомления о подписании нового документа (1) тем получателям, которые были указаны в массиве emailNotifications.to при регистрации документа с помощью POST /api - регистрация нового документа в системе. Рассылаемые электронные письма содержат ссылки на страницу подписанного документа, а так же к ним прикреплены подлинники подписанных документов (можно отключить с помощью флага doNotAttachDocument). Подлинник подписанного документа может быть не прикреплен к письму в том случае, если прикрепляемый файл не прошел проверку антивирусным программным обеспечением, либо если он большого размера.

В том случае, если используется функция предрегистрации, то сервис отправляет уведомления о предрегистрации документа (6). Эти уведомления подобны уведомлениям о подписании нового документа (1), но не содержат информации о том, кто первым подписал документ, вместо этого они содержат информацию о том, какая организация отправила документ на подписание.

Так же каждому пользователю, подписавшему какой-либо документ, сервис отправляет уведомление в том случае, если к этому документу была добавлена подпись - это уведомления о добавлении подписи к документу, подписанному пользователем (3). В этом случае электронные письма содержат ссылку на страницу подписанного документа и информацию о том, кто добавил подпись, подлинник подписанного документа к письму не прикрепляется. Адреса для отправки этих уведомлений сервис берет из настроек пользователей (поле email в POST /api/settings - сохранить настройки аутентифицированного пользователя), которых сервис идентифицирует по ИИН. По умолчанию в настройки заносится тот адрес электронной почты, который был указан в сертификате, который пользователь использовал первый раз для подписания документа на сервисе, либо аутентификации. Эта опция отключена по умолчанию, для того, чтобы получать эти уведомления, пользователям нужно активировать ее в своих настройках.

Помимо этого сервис рассылает уведомления о новых подписях под документами на те адреса электронной почты, которые были указаны при регистрации документа - уведомления о добавлении подписи к документу (2).

Рассмотрим пример:

• при регистрации нового документа были указаны два адреса электронной почты 1@example.com и 2@example.com, первым подписал документ пользователь, у которого в настройках указан адрес me@example.com;
• сервис отправил уведомления о новых документах (1) на адреса 1@example.com и 2@example.com;
• далее пользователь, у которого в настройках указан адрес other@example.com, добавил подпись к этому документу;
• сервис отправил одно уведомление о добавлении подписи (3) на адрес me@example.com и два уведомления о добавлении подписи (2) на адреса 1@example.com и 2@example.com;
• после этого пользователь, у которого в настройках указан адрес 1@example.com, тоже добавил подпись к этому документу;
• сервис отправил два уведомления о добавлении подписи (3) на адрес me@example.com и other@example.com и одно уведомление о добавлении подписи (2) на адрес 2@example.com.

Таким образом все заинтересованные стороны получают актуальную информацию о состоянии своих подписанных документов.

При регистрации пакета документов сервис рассылает уведомления о регистрации нового пакета документов (7) тем получателям, которые были указаны в массиве emailNotifications.to POST /api/package - регистрация пакета документов. Рассылаемые электронные письма содержат ссылки на страницу пакета документов, а так же к ним прикреплены подлинники подписанных документов (можно отключить с помощью флага doNotAttachDocuments). Подлинники подписанных документов могут быть не прикреплены к письму в том случае, если прикрепляемые файлы не прошли проверку антивирусным программным обеспечением, либо если они большого размера. Так же подлинники подписанных документов не будут прикреплены к письму в том случае, если они не находятся в архиве или временном хранилище.

Уведомления, связанные с архивированием подписанных данных - уведомление о превышении квоты архива подписанных данных (4) и уведомление об истечении срока действия квоты архива подписанных данных (5), сервис рассылает на отдельные адреса электронной почты указанные в поле dataArchiveContactEmail в ностройках пользователей (POST /api/settings - сохранить настройки аутентифицированного пользователя) и организаций (POST /api/organizationSettings - сохранить настройки организации).

Дополнительные уведомления по электронной почте запрашиваемые при регистрации подписей

Предусмотрена возможность отправки уведомлений по электронной почте на произвольные адреса при регистрации подписей под документами и пакетами документов следующими вызовами:

• POST /api/{id} - добавление подписи к документу
• POST /api/package/{packageId} - добавление подписей к документам пакета

За отправку уведомлений отвечает поле signatureEmailNotifications.

Уведомления по электронной почте рассылаемые по запросу

С помощью следующих вызовов можно запросить отправку уведомлений на произвольные адреса в произвольный момент времени:

• POST /api/{id}/notify - отправка уведомлений о документе
• POST /api/package/{packageId}/notify - отправка уведомлений о пакете документов

Webhook уведомления

Для информирования интегрированных систем и приложений о новых зарегистрированных в SIGEX подписях можно использовать механизм Webhook уведомлений. Параметры рассылки Webhook уведомлений настраиваются индивидуально для каждой организации в настройках соответствующей организации (POST /api/organizationSettings - сохранить настройки организации).

Сервис отправляет POST запросы на указанные в настройках организации URL в следующих случаях:

• регистрация нового документа с подписью;
• регистрация новой подписи под документом;
• изменение состояния операции упрощенного подписания документа через eGov m/b;
• изменение состояния операции упрощенного подписания пакета документов через eGov m/b.

Тело запроса будет содержать идентификаторы пакета документов, документа и подписи в формате JSON:

{
  "packageId": "xxx",
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 123,
  "egovOperationId": 123
}

• packageId - опциональное поле, идентификатор пакета документов;
• documentId - опциональное поле, идентификатор документа;
• signId - опциональное поле, идентификатор подписи;
• egovOperationId - опциональное поле, идентификатор операции упрощенного подписания через eGov m/b.

Наличие полей зависит от типа уведомления:

Наш сервис, при отправке Webhook уведомлений, поддерживает двусторонний HTTPS, то есть он может предоставлять клиентский сертификат https://ru.wikipedia.org/wiki/HTTPS#Идентификация_клиента и выполнять mTLS аутентификацию. Этот механизм доступен по запросу принимающего Webhook уведомления сервера, мы используем наш стандартный HTTPS сертификат для этих целей. Благодаря этому сервер принимающий Webhook уведомления может определять что это именно наш сервер отправляет уведомления.

Получателю следует ответить HTTP кодом 200 (Success) с пустым телом. В том случае, если отправить запрос не удастся, либо получатель ответит иным кодом, сервис попробует повторно отправить запрос через некоторый промежуток времени.

Сервис отправляет Webhook уведомления о новой зарегистрированной подписи в том случае, если:

• Webhook уведомления настроены для организации, сертификат сотрудника юридического лица которой был использован для формирования регистрируемой подписи;
• новая подпись добавлена к документу уже подписанному сотрудником организации, для которой настроены Webhook уведомления;
• новая подпись добавлена к документу зарегистрированному информационной системой организации, для которой настроены Webhook уведомления.

Рассмотрим пример:

• у организации A настроена отправка Webhook уведомлений по URL https://a.kz/webhooks
• у организации B настроена отправка Webhook уведомлений по URL https://b.kz/webhooks
• сотрудник организации A подписывает документ, идентификатор документа D1, идентификатор подписи S-A
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-A по URL одному https://a.kz/webhooks
• сотрудник организации B добавляет подпись к документу D1, идентификатор новой подписи S-B
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-B по URL двум https://a.kz/webhooks и https://b.kz/webhooks
• физическое лицо добавляет подпись к документу D1, идентификатор новой подписи S-P
• сервис отправляет Webhook уведомление с идентификатором документа D1 и идентификатором подписи S-P по URL двум https://a.kz/webhooks и https://b.kz/webhooks