Отправка уведомлений клиентам

Обновлено 29 февраля 2024

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

• Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443

• Промышленный контур https://fintech.sberbank.ru:9443

Отправки уведомлений клиентам

Ресурс /v1/notify-messages позволяет Партнеру отправлять уведомления клиентам СББОЛ с целью информирования.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для отправки уведомления необходимо отправить POST-запрос (/v1/notify-messages), в котором передать авторизационный токен к данным клиента (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис NOTIFY_MESSAGES.

Модель запроса

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации-клиента, полученный через SSO Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры тела запроса
Notification {
attributes (string, optional)	Дополнительные параметры сообщения,
codeMessageKind (integer)	Код вида сообщения,
datetimeSince (string)	Дата и время, начиная с которой должно быть отправлено сообщение,
datetimeUntil (string, optional)	Дата и время, до которого должно быть отправлено сообщение (дата, указанная в параметре datetimeUntil должна совпадать с датой, указанной в параметре datetimeSince),
externalId (string)	Идентификатор уведомления, присвоенный партнером (UUID)
}

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

{
"attributes": "CONTRACT_DATE=10.01.2020, CONTRACT_NUM=10012020, INFO_LIST_DATE=01.05.2020, LOGIN=test",
"codeMessageKind": 8705,
"datetimeSince": "2018-12-31T23:59:59",
"datetimeUntil": "2018-12-31T23:59:59",
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}

Модель ответа

Только http-код

Получение статуса уведомления

Ресурс /v1/notify-messages/{externalId}/state позволяет Партнеру получить статус уведомления отправленного клиенту.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения статус необходимо отправить GET-запрос (/v1/notify-messages/{externalId}/state), в котором передать авторизационный токен к данным клиента (Access Token) и идентификатор уведомления (externalID). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис NOTIFY_MESSAGES.

Модель запроса

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры запроса
externalId (String)	Идентификатор уведомления, присвоенный партнером

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/service-package'

Модель ответа

string (Возвращается один из статусов перечисленных ниже)

Возможные статусы

Статус	Описание статуса
DEFERRED	Отложен
NEW	Новое
POSTED	Отправлено (отправлено в шлюз)
RECEIVED	Получено (доставлено провайдеру)
READED	Прочитано (доставлено абоненту)
ERROR	Ошибка
DELAYED	Просрочено
IN_PROGRESS	Обрабатывается

Дополнительная информация

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

• application/json – запрос без подписи
• application/jose – запрос, подписанный транспортной подписью

Если Content-Type имеет значение application/jose, то запрос должен содержать данные в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из трёх частей:

1. Заголовок (Header) - определяет алгоритм подписи и тип токена
2. Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
3. Электронная подпись (Signature) - вычисляется с использованием приватного ключа клиента

Base64Url(Header) || ’.’ ||  Base64Url(Payload) || ’.’ || Base64Url(Signature)

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg (в нашем случае gost34.10-2012) и вычисляется от исходных данных:

Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

При кодировании JWS используется преобразование Base64Url. Преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

• функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x,
• функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование Base64Url, отличается от Base64 преобразования:

• В Base64Url не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
• Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

BASE64URL	BASE64
- (minus)	+
_ (underline)	/

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

Коды возврата

Код возврата	Описание кода возврата	Причина возникновения
400	DESERIALIZATION_FAULT
	Неверный формат запроса	Неверный формат запроса
	WORKFLOW_FAULT
	Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ	Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
	Документ с такими реквизитами уже существует	Документ с такими реквизитами уже существует. Проверка по номер документа в течении года.
	Не указан идентификатор сертификата подписи	Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
	Некорректный формат параметра kid заголовка JWS	Некорректный формат параметра kid заголовка JWS(ожидается UUID)
	VALIDATION_FAULT
	Ошибка валидации	Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
	SIGN_CHECK_EXCEPTION
	Подлинность подписи не установлена/Сертификат не обнаружен или не является активным	Ошибка возникает, если не удалось установить подлинность подписи
401	UNAUTHORIZED
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	ACTION_ACCESS_EXCEPTION
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса Sber API, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
415	JWS_EXCEPTED
	В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization	Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500	UNKNOWN_EXCEPTION
	Внутренняя ошибка сервера
503	UNAVAILABLE_RESOURCE_EXCEPTION
	Сервис временно недоступен	Проводятся технические работы