Все запросы в данном руководстве разделены построчно для удобства чтения.

ГСЭС позволяет клиентам ЕСИ отправлять пользователям сообщения по следующим каналам связи:

1. Email
2. SMS
3. Telegram

Для этого ЕСИ предоставляет API со следующим адресом:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/{канал-связи}/Send

{канал-связи} – канал связи, по которому Вы хотите доставить сообщение. Возможные каналы связи:

• email
• sms
• telegram

Для обращения к API, клиенту необходимо отправить POST запрос с заголовками:

• Authorization типа Bearer и поместить туда Access Token, имеющий scope-значение notification_api.
• Content-Type со значением application/json.

Само сообщение помещается в теле запроса в формате JSON. Обязательные поля для каждого запроса:

• pin — персональный номер человека, которому надо отправить сообщение. Должен быть размером 14 символов.
• content — сообщение. Каждый канал связи имеет своё ограничение по размеру.

Пример заголовка Authorization:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA

При получении запроса API посылает ответ о прошедшей операции в формате JSON со следующими полями:

• RequestID (Обязательное) — ID запроса.
• Succeeded (Обязательное) — boolean-значение, показывающее успешно ли был обработан запрос или нет.
• Errors (Если succeeded=false) — массив ошибок, возникших во время обработки запроса. Состоит из объектов со следующими полями:
  • Code — код ошибки
  • Message — понятное для человека описание ошибки.

Если значение succeeded=true, то запрос был обработан успешно и сообщение было отправлено. При этом код статуса будет 200 OK.

Если отправить запрос с Content-Type не равным application/json, то ответом будет код статуса 415 Unsupported Media Type.

Неправильный запрос на отправку сообщение по Email'у:

https://{базовый-адрес-ЕСИ}/notifications/api/v1/email/send 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
  "pin":"123123123123ab",
  "content":""
}

Ответ:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "requestId": "07d17b36-4f7b-49ba-8841-3bd639b926ba",
  "succeeded": false,
  "errors": [
      {
         "code": "PinMustBe14Digits",
         "message": "Pin must be 14 digits long"
      },
      {
          "code": "EmptyContent",
          "message": "Content cannot be empty"
      },
      {
          "code": "EmptySubject",
          "message": "Subject cannot be empty"
      }
  ]
}

Неправильный запрос на отправку сообщения по SMS:

https://{базовый-адрес-ЕСИ}/notifications/api/v1/sms/send 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
   "pin":"12345678900000",
   "content":"very biiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiig message"
}

Ответ:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "requestId": "2ef87452-5918-4d5a-944c-8a6e6e1aa0c2",
  "succeeded": false,
  "errors": [
      {
          "code": "ContentLengthLimitExceeded",
          "message": "Content exceeds length limit (70)"
      }
  ]
}

Правильный запрос, но пользователь не найден:

https://{базовый-адрес-ЕСИ}/notifications/api/v1/telegram/send 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
   "pin":"12345678900000",
   "content":"some message"
}

Ответ:

 HTTP/1.1 404 Not Found
 Content-Type: application/json
{
  "requestId": "b9eb157b-c204-49c7-87d0-b21e8cef4aba",
  "succeeded": false,
  "errors": [
      {
          "code": "UserNotFound",
          "message": "Could not find user with the given pin"
      }
  ]
}

Предаврительно убедитесь, что при регистрации в ЕСИ для вас добавили соответствующие настройки — разрешили grant_type=client_credentials и разрешили обращаться к scope-значению IdentityServerApi и notification_api.

Для получения Access Token'a клиенты должны обратиться к Token endpoint, используя client credentials flow (Machine-to-machine).

Адрес Token endpoint:

https://{базовый-адрес-ЕСИ}/connect/token

Необходимо отправить POST запрос с заголовками:

• Authorization типа Basic. В качестве username выступать ваш client_id, а в качестве пароля client_secret.
• Content-Type со значением application/x-www-form-urlencoded.

В теле запроса должно быть grant_type=client_credentials.

Будем считать, что:

client_id=mvc-client
client_secret=secret

Пример запроса через curl для получения Access Token'a:

curl -X POST -H "Authorization: Basic bXZjLWNsaWVudDpzZWNyZXQ=" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" https://{базовый-адрес-ЕСИ}/connect/token

Ответ от ЕСИ:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNhZzBDYk1UYzh4d293MDVaVDRpRFEiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODQwOTY3NjgsImV4cCI6MTU4NDEwMDM2OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzY29wZSI6WyJub3RpZmljYXRpb25fYXBpIl19.LWK8VKAplbACSf2Upbwkbc_PWRIpRy1V8CC5NL_Q898qUQUVCtTT_x9QcJ_ver_r02_VjyxhAVgWnvw1RO5Bbeum1o42md5lULJOFthwvDIeXsApKyBsYJ2ENWSQDUC5PWdTVmf-x7kVMK12DlKv9YJaroMxtEUx_8OQlGcHCNtY8OZB0sBTkPv_JCWtMlXHr7Mo0qDyXzAlWwhnOtHlJIfkcmMx-o4CdHRqolrPbB_t1sQrZbwt2tuwikBqHcrTRuXi7WzoysK12ThM9-x3bGFDOSRSpArdykCDfFpBPm3yw85jhJicsDMgDvMDiArZaW2_hAl8g96J95xHg19w_w",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "email IdentityServerApi notification_api openid phone profile"
}

Access Token приходит в формате JWT. Декодировать можно на сайте https://jwt.io

Адрес API:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Telegram/Send

Максимальный размер content — 2000 символов.

Пример запроса:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Telegram/Send
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
  «pin»: «21508197012345»,
  «content»: «Sample Telegram notification.»
}

Сообщения в Telegram поддерживают HTML теги. Возможны следующие теги:

<b>жирный текст</b>, <strong>жирный текcт</strong>
<i>курсив</i>, <em>курсив</em>
<u>подчёркнутый текст</u>, <ins>подчёркнутый текст</ins>
<s>зачёркнутый</s>, <strike>зачёркнутый</strike>, <del>зачёркнутый</del>
<b>жирный <i>жирный и курсив<s>жирный, курсив и зачёркнутый</s> <u>подчёркнутый, курсив и жирный</u></i> жирный</b>
<a href="http://www.example.com/">встроенный URL</a>
<a href="tg://user?id=123456789">встроенное упомянание пользователя</a>
<code>встроенный код с фиксированной шириной </code>
<pre>преформатированный блок кода с фиксированной шириной</pre>

Чтобы использовать символы <, > и & независимо от HTML-тегов, их необходимо экранировать:

<  &lt;
>  &gt;
&  &amp;

Источник:Telegram Bot API, HTML style

Адрес API:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Sms/Send

Максимальный размер content — 70 символов.

Пример запроса:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Telegram/Send
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
  «pin»: «21508197012345»,
  «content»: «Sample SMS notification.»
}

Адрес API:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Email/Send

Имеет допольнительное обязательное поле: subject — тема сообщения (до 100 символов).

Максимальный размер content - 10000.

Пример запроса:

https://{базовый-адрес-ЕСИ}/Notifications/Api/V1/Telegram/Send
Authorization: Bearer   eyJhbGciOiJSUzI1NiIsImtpZCI6IkVKRzlFYXVuZVZJUktBNHFvM25EV0EiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE1ODI3OTM5NTgsImV4cCI6MTU4Mjc5NzU1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo3MDAwIiwiYXVkIjoibm90aWZpY2F0aW9uX2FwaSIsImNsaWVudF9pZCI6Im12Yy1jbGllbnQiLCJzdWIiOiIxMDAwMDAwIiwiYXV0aF90aW1lIjoxNTgyNzgyNDU4LCJpZHAiOiJsb2NhbCIsInNjb3BlIjpbInByb2ZpbGUiLCJvcGVuaWQiLCJlbWFpbCIsInBob25lIiwibm90aWZpY2F0aW9uX2FwaSIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJtZmEiXX0.xEivo3rUVGYMTtX3Zjm_Bj-j5rgIgi-4ehXlx_jPiYzFtB7g-O5wxjLJyllYU4fYS6vTHJ8H2qwNu42mT9IKL7Ywsi3pqEhWbfuBGJoOZ9Nn5VrwDscWDwKaJwH3YOn8pXipe1gwiz3-xFuw5UOSNWSx_PW8QayUG1fymOQ69D7VC-migg6YO3lSlTcUmgK0AiZ-64exzaebYn58YPEKhE_bMF7eqpMd1EjDcOv2gZRX-fjUmDrhwG1_qVxfuCpkS4qmKj1cdypEG0GL7ZruALtbarB-ZW9qpsJd1Z1ZYaNFtOUQK0G9ZqEUT3kD5xmaegdgmMG1-GnDlryFVG0YQA
Content-Type: application/json
{
  «pin»: «21508197012345»,
  «subject»: «E-service notification»
  «content»: «You used some e-service on 05.03.2020»
}