Передача банковских и небанковских продуктов

Обновлено 19 сентября 2023

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

Текущий тестовый контур https://edupirfintech.sberbank.ru:9443
Новый тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
Промышленный контур https://fintech.sberbank.ru:9443

Информация о внешних сервисах

Ресурс /v1/client-extservice-products позволяет получить информацию о подключенных у клиента внешних сервисах для сервиса Партнера.

Шаги

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

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

Для получения информации необходимо отправить GET-запрос (/v1/client-extservice-products) и передать авторизационный токен к данным организации клиента/собственной организации (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-extservice-products'

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

Наименование	Описание
extserviceProducts {
name (string, optional)	Наименование внешнего сервиса,
category (string, optional)	Категория продукта,
shortDesc (string, optional)	Краткое описание продукта,
fullDesc (string, optional)	Полное описание продукта,
sinceDate (string, optional)	Дата подключения,
productId (string, optional)	Идентификатор продукта
}

Пример ответа

{
"name": "Бухгалтерия для ИП",
"category": "Бухгалтерия и финансовый учет",
"shortDesc": "Облачная бухгалтерия",
"fullDesc": "Сервис позволяет выполнять сдачу необходимой бухгалтерской, налоговой и финансовой отчетности в электронном виде в государственные органы",
"sinceDate": "2020-02-01",
"productId": "12"
}

Информация по персональным предложениям

Ресурс /v1/personal-offers позволяет Партнеру получить информацию по персональным предложениям клиента для того, чтобы продавать персональные предложения на своем ресурсе.

Шаги

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

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

Для получения информации необходимо отправить GET-запрос (/v1/personal-offers) и передать авторизационный токен к данным организации клиента/собственной организации (Access Token) и страницу размещения предложения (placement). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
placement (String)	Страница размещения предложения

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/personal-offers?placement=website'

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

Наименование	Описание
InlineModel [
InlineModel1
]
InlineModel 1 {
activatedUrl (string, optional)	Ссылка для перенаправления пользователя, если продукт
подключен ,
adviseMediaLink (string, optional)	Ссылка на картинку для контекстного совета ,
buttonAction (integer, optional)	Действие по кнопке персонального предложения ,
buttonLink (string, optional)	Ссылка для перехода по кнопке персонального предложения ,
buttonName (string, optional)	Наименование кнопки целевого действия для персонального предложения ,
campaignName (string, optional)	Наименование кампании ,
category (string, optional)	Категория продукта ,
channel (string, optional)	Канал ,
contextAdvise (string, optional)	Контекстный совет ,
creditProduct (string, optional)	Наименование кредитного продукта ,
crmProductId (string, optional)	Идентификатор продукта персонального предложения в CRM ,
currency (string, optional)	Валюта ,
currencyCode (string, optional)	Цифровой код валюты ,
dateSince (string, optional)	Дата начала действия предложения ,
dateUntil (string, optional)	Дата окончания действия предложения ,
depositType (string, optional)	Тип депозита ,
fmLink (string, optional)	Ссылка на внешний сайт при нажатии «Узнать больше» ,
fmMsg (string, optional)	Текст при переходе на внешний сайт при нажатии «Узнать больше» ,
fullDesc (string, optional)	Полное описание продукта ,
iconDocLink (string, optional)	Ссылка на картинку в документарных разделах ,
iconImageLink (string, optional)	Ссылка на картинку для ленты ,
iconLink (string, optional)	Иконка маркетингового исследования или новостей ,
imgLink (string, optional)	Ссылка на картинку на развороте предложения ,
imgLinkDcb (string, optional)	Ссылка на картинку для DCB ,
isApproved (string, optional)	Признак одобренного / предодобренного продукта ,
maxOfferAmount (number, optional)	Максимальная сумма предложения, в тысячах ,
needPledge (boolean, optional)	Признак необходимости залога при получении кредита на сумму свыше 5 млн. ,
offerAmount (integer, optional)	Сумма ,
offerGuid (string, optional)	Идентификатор предложения ,
offerLink (string, optional)	Персональная ссылка в тексте предложения ,
offerRate (number, optional)	Процентная ставка ,
offerSetLimit (string, optional)	Набор сумм с символом "\|" в качестве разделителя ,
offerSetRate (string, optional)	Набор ставок с символом "\|" в качестве разделителя ,
offerSetTerm (string, optional)	Набор сроков с символом "\|" в качестве разделителя ,
offerTerm (integer, optional)	Срок ,
priority (integer, optional)	Приоритет показа предложения ,
productCode (string, optional)	Код продукта персонального предложения ,
productName (string, optional)	Наименование карточки продукта ,
productSystemName (string, optional)	Наименование продукта персонального предложения ,
serviceName (string, optional)	Наименование внешнего сервиса в системе ,
shortDesc (string, optional)	Краткое описание продукта ,
specialCondition (string, optional)	Условия специального предложения ,
telInText (string, optional)	Телефон в тексте персонального предложения ,
textBandCard (string, optional)	Текст на карточке в ленте ,
textDocCard (string, optional)	Текст на карточке в документарных разделах ,
type (string, optional)	Тип предложения
}

Пример ответа

[
   {
      "activatedUrl":"string",
      "adviseMediaLink":"https://21.21.21.21/redesign/share/stories/sovet.svg",
      "buttonAction":1,
      "buttonLink":"credits/products?targetCode=40",
      "buttonName":"Подключить",
      "campaignName":"Кредит",
      "category":"Кредит",
      "channel":"SBBOL",
      "contextAdvise":"Деньги заказывали?",
      "creditProduct":"Одобренный SMART-кредит",
      "crmProductId":"1-27RUCY00",
      "currency":"USD",
      "currencyCode":"840",
      "dateSince":"2018-12-31",
      "dateUntil":"2018-12-31",
      "depositType":"Депозит Классический Онлайн",
      "fmLink":"string",
      "fmMsg":"string",
      "fullDesc":"Сервис позволит вам направить заявку на получение банковского кредита без посещения отделения банка",
      "iconDocLink":"https://21.21.21.21/redesign/share/stories/mini_main_credit.jpg",
      "iconImageLink":"https://21.21.21.21/redesign/share/stories/mini_shop.jpg",
      "iconLink":"string",
      "imgLink":"string",
      "imgLinkDcb":"https://www.sberbank.ru/img/files/file.jpg",
      "isApproved":"1",
      "maxOfferAmount":10000,
      "needPledge":false,
      "offerAmount":30000,
      "offerGuid":"12345678-1234-1234-1234-123456789012",
      "offerLink":"string",
      "offerRate":17,
      "offerSetLimit":"10000|20000|30000|40000",
      "offerSetRate":"15|16|17|18",
      "offerSetTerm":"12|24|36|48",
      "offerTerm":36,
      "priority":100,
      "productCode":"kredit",
      "productName":"Бухгалтерия для ИП",
      "productSystemName":"SMART_SBOFF",
      "serviceName":"Бухгалтерия для ИП",
      "shortDesc":"Кредит на любые цели",
      "specialCondition":"2",
      "telInText":"89269999999",
      "textBandCard":"Кредит [br] для бизнеса",
      "textDocCard":"Как приобрести [br] транспорт",
      "type":"38/943/04"
   }
]

Действия по персональным предложениям

Ресурс /v1/personal-offers/response позволяет Партнеру отправить сведения о действиях пользователя по персональным предложениям с целью определения востребованности контента.

Шаги

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации-клиента, полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
AsupResponse {
channel (string)	Канал получения отклика = ['SBBOL', 'DCB', 'MP', 'SBB', 'SBBOL3', 'FINTECH'],
datetime (string, optional)	Дата и время создания отклика ,
offerId (string)	Идентификатор предложения ,
placement (string, optional)	Страница размещения предложения (плейсмента) ,
type (string)	Тип отклика = ['SHM', 'STA', 'STL', 'HDC', 'UHC', 'SCT', 'STR', 'NPC', 'THL', 'ORC', 'ORL', 'HIM', 'OCS', 'SHW', 'HDF', 'SLL', 'SLR', 'SLS', 'OC', 'BAD', 'LGN', 'OR', 'TXL', 'TXW', 'TXN', 'OCB', 'WEL', 'MCC', 'MCS']
}

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

{
"channel": "FINTECH",
"datetime": "2018-12-31T23:59:59",
"offerId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"placement": "MAIN[MAIN_FEED]",
"type": "OR"
}

Информация о банковских продуктах

Ресурс /v1/client-bank-products позволяет Партнеру получить информацию о подключенных клиенту банковских продуктах для предоставления информации на своих ресурсах.

Шаги

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

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

Для получения информации необходимо отправить GET-запрос (/v1/client-bank-products) и передать авторизационный токен к данным организации клиента/собственной организации (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример:`Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-bank-products'

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

InlineModel [
InlineModel 1
]
InlineModel 1 {
category (string, optional)	Категория продукта ,
fullDesc (string, optional)	Полное описание продукта ,
name (string, optional)	Наименование внешнего сервиса ,
productId (string, optional)	Идентификатор продукта ,
shortDesc (string, optional)	Краткое описание продукта
}

Пример ответа

[
   {
      "category":"Бухгалтерия и финансовый учет",
      "fullDesc":"Сервис позволяет выполнять сдачу необходимой бухгалтерской, налоговой и финансовой отчетности в электронном виде в государственные органы",
      "name":"Бухгалтерия для ИП",
      "productId":"korpkarta",
      "shortDesc":"Облачная бухгалтерия"
   }
]

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

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

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

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

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

JWS состоит из:

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

Формирование компактной сериализации JWS

JWS формируется из трех составляющих:

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

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

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

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

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

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

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

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

Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

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

В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

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

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

Код возврата	Описание кода возврата	Причина возникновения
200 (GET-запроса)	`OK`
204	`NO_CONTENT`
	Для указанного клиента отсутствуют подключенные пакеты услуг	Запрос обработан, но для указанного клиента отсутствуют подключенные пакеты услуг
400	`DESERIALIZATION_FAULT`
	Неверный формат запроса	Неверный формат запроса
401	`UNAUTHORIZED`
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	`ACTION_ACCESS_EXCEPTION`
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
500	`UNKNOWN_EXCEPTION`
	Внутренняя ошибка сервера
503	`UNAVAILABLE_RESOURCE_EXCEPTION`
	Сервис временно недоступен	Проводятся технические работы

Передача банковских и небанковских продуктов

Информация о внешних сервисах﻿

Шаги﻿

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

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

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

Пример ответа﻿

Информация по персональным предложениям﻿

Шаги﻿

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

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

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

Пример ответа﻿

Действия по персональным предложениям﻿

Шаги﻿

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

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

Информация о банковских продуктах﻿

Шаги﻿

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

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

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

Пример ответа﻿

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

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

Формирование компактной сериализации JWS﻿

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

Информация о внешних сервисах

Шаги

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

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

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

Пример ответа

Информация по персональным предложениям

Шаги

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

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

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

Пример ответа

Действия по персональным предложениям

Шаги

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

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

Информация о банковских продуктах

Шаги

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

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

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

Пример ответа

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

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

Формирование компактной сериализации JWS

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