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

Инструменты сайта


ssem-api-description

Это старая версия документа!


Автор: Владимир Недорослев

Общее описание

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

  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.

Возможные ошибки

ErrorCode Причина Код статуса HTTP
InvalidJsonFormat Тело запроса в неверном JSON-формате 400 Bad Request
InvalidPinFormat pin содержит недопустимые символы 400 Bad Request
PinMustBe14Digits Длина значения pin не 14 символов 400 Bad Request
EmptyPin pin не был передан или является пустой строкой 400 Bad Request
EmptyContent content не был передан или является пустой строкой 400 Bad Request
EmptySubject subject не был передан или является пустой строкой 400 Bad Request
ContentLengthLimitExceeded Длина значения content превышает допустимое значение 400 Bad Request
SubjectLengthLimitExceeded Длина значения subject превышает допустимое значение 400 Bad Request
UserNotFound Указанный ПИН не зарегистрирован в ЕСИА 404 Not Found
UserHasNoTelegram Указанный пользователь не имеет настроенного Telegram'a. 404 Not Found
UserHasNoEmail Указанный пользователь не имеет настроенного Email'a 404 Not Found
UserHasNoPhoneNumber Указанный пользователь не имеет настроенного номера телефона 404 Not Found
TooManySmsRequests Превышено ограничение по количеству отправленных СМС на данный pin 429 Too Many Requests
InternalServerError При отправке сообщения по каналу связи возникла ошибка со стороны сервера 500 Internal Server Error

Если отправить запрос с 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 (100)"
      }
  ]
}

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

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"
      }
  ]
}

Получение Access Token'a

Формат запроса к Token endpoint

Предаврительно убедитесь, что при регистрации в ЕСИА для вас добавили соответствующие настройки — разрешили grant_type=client_credentials и разрешили обращаться к scope-значению 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.

Пример получения Access Token'a

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

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 notification_api openid phone profile"
}

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

Telegram

Адрес 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

SMS

Адрес 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.»
}

Email

Адрес 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 have used some e-service on 05.03.2020»
}
ssem-api-description.1584435921.txt.gz · Последние изменения: 2020/03/17 09:05 — admin1