ym88659208ym87991671
Управление тарифными планами | Документация для разработчиков

Управление тарифными планами

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

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

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

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

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

Для управления тарифным планом необходимо произвести соответствующие настройки сервиса на стороне Банка.

Получение информации по тарифным планам

Ресурс /v1/tariff-plans/list-activated позволяет Партнеру получить актуальную информацию по тарифным планам, которые подключены пользователю организации.

Шаги

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

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

Для получения информации необходимо отправить GET-запрос (/v1/tariff-plans/list-activated), в заголовке запроса указать авторизационный токен клиента (Authorization). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

НаименованиеОписание
Параметры заголовка
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'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/tariff-plans/list-activated'

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

НаименованиеОписание
Inline Model [
Inline Model 1
]Inline Model 1 {
account (string, optional)Номер счета для списания комиссии
bankStatus (string)Статус подписки ,
freePeriod (integer)Бесплатный период ,
freePeriodType (string)Размерность бесплатного периода (Y - год, Q - квартал, M - месяц) ,
freezeDate (string)Дата и время приостановки тарифа ,
freezed (boolean)Показатель приостановки тарифа ,
paymentEndDate (string)Дата, до которой оплачен тариф ,
paymentStartDate (string)Дата начала тарификации ,
paymentType (string)Тип оплаты тарифа = ['PREPAID', 'POSTPAID', 'UNPAID']
stringEnum: "PREPAID", "POSTPAID", "UNPAID",
tariffActivationDate (string)Дата подключения тарифа ,
tariffDescription (string)Описание тарифного плана ,
tariffDisconnectionDate (string)Дата окончания тарификации ,
tariffName (string)Наименование тарифного плана ,
tariffSystemName (string)Системное наименование тарифного плана
}

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

{
"account":"40817810099910004312",
"bankStatus":"ACTIVE",
"freePeriod":2,
"freePeriodType":"М",
"freezeDate":"2018-12-31T23:59:59",
"freezed":true,
"paymentEndDate":"2018-12-31",
"paymentStartDate":"2018-12-31",
"paymentType":"UNPAID",
"tariffActivationDate":"2018-12-31",
"tariffDescription":"Продукт позволяет избежать ограничений по 115-ФЗ",
"tariffDisconnectionDate":"2018-12-31",
"tariffName":"Безопасный бизнес Базовый",
"tariffSystemName":"SECURE_BUSINESS_BASIC"
}

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

СтатусНаименованиеОписание
WAITINGОжидает оплатыПрисваивается при подключении к предоплатному тарифу с необходимостью оплаты в день подключения (т.е. без триального периода)
REQUISITEERRORОшибка реквизитовПрисваивается при ошибке счета списания комиссии. Счет списания более недействителен и подлежит замене.
REFUSEDBYBANKОтвергнута БанкомПрисваивается при возникновении блокировок, при которых отключается тарифицируемый сервис (настраиваемо для каждого отдельного сервиса). Перечень возможных блокировок:
Блокировка пользователя банком
Блокировка пользователя безопасностью
Блокировка пользователя системой
Блокировка пользователя клиентом
Блокировка организации
Договор расторгнут
Финансовая блокировка
Приостановить оказание услуг
Комплаенс-блокировка
Массовые блокировки договоров/организации
FREEZEDПриостановленаПрисваивается при получении из ЕКС ответа, что оплата продления подписки не удалась
DELETEDУдаленаПрисваивается при неудачной оплате предоплатного тарифа в день подключения
DEACTIVATEDОтключенаПрисваивается при отключении услуги клиентом
ACTIVEАктивнаПрисваивается при подключении к постоплатному тарифу или предоплатному тарифу с триальным периодом, а также по факту погашения задолженности при получении ответа из ЕКС по оплате начислений за тариф

Подключение или отключение тарифного плана

Ресурс /v1/tariff-plans/activation позволяет Партнеру отправить запрос на подключение/отключение тарифного плана организации.

Шаги

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации-клиента, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
TariffPlanActivationRequest {
account (number)Номер счета для списания комиссии ,
bankStatus (string, optional, read only)Статус обработки ,
enableTariff (boolean)Признак включения тарифного плана (true - включение тарифа, false - выключение тарифа) ,
tariffSystemNameСистемное наименование подключаемого/отключаемого тарифного плана ,

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

{
"account": "40817810099910004312",
"bankStatus": "ACTIVE",
"enableTariff": true,
"tariffSystemName": "SECURE_BUSINESS_BASIC"
}

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

СтатусНаименованиеОписание
WAITINGОжидает оплатыПрисваивается при подключении к предоплатному тарифу с необходимостью оплаты в день подключения (т.е. без триального периода)
FREEZEDПриостановленаПрисваивается при получении из ЕКС ответа, что оплата продления подписки не удалась
DELETEDУдаленаПрисваивается при неудачной оплате предоплатного тарифа в день подключения
DEACTIVATEDОтключенаПрисваивается при отключении услуги клиентом
ACTIVEАктивнаПрисваивается при подключении к постоплатному тарифу или предоплатному тарифу с триальным периодом, а также по факту погашения задолженности при получении ответа из ЕКС по оплате начислений за тариф

Список тарифных планов

Ресурс /v1/tariff-plans/list-available позволяет Партнеру получить список тарифных планов доступных внешнему сервису.

Шаги

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

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

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

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

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

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

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

curl -X GET --header 'Accept: /' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/tariff-plans/list-available'

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

НаименованиеОписание
Inline Model [
Inline Model 1
]Inline Model 1 {
freePeriod (integer)Бесплатный период,
freePeriodType (string)Размерность бесплатного периода (Y - год, Q - квартал, M - месяц),
paymentType (string)Тип оплаты тарифа = ['PREPAID', 'POSTPAID', 'UNPAID']
stringEnum: "PREPAID", "POSTPAID", "UNPAID",
tariffDescription (string)Описание тарифного плана,
tariffName (string)Наименование тарифного плана,
tariffPlansDetails (Array[TariffPlansDetails], optional)Тарифицируемые объекты тарифного плана,
tariffSystemName (string)Системное наименование тарифного плана
}TariffPlansDetails {
billingObjectCode (string, optional)Код тарифицируемого объекта,
billingObjectName (string, optional)Наименование тарифицируемого объекта,
billingObjectStrategy (string, optional)Стратегия тарификации = ['MAX', 'LAST']
stringEnum: "MAX", "LAST",
tariffPackCount (integer, optional)Пакетные тарифы. Количество сообщений в тарифе,
tariffPackFree (integer, optional)Пакетные тарифы. Количество бесплатных сообщений в тарифе
}

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

[
{
"freePeriod":2,
"freePeriodType":"М",
"paymentType":"UNPAID",
"tariffDescription":"Продукт позволяет избежать ограничений по 115-ФЗ",
"tariffName":"Безопасный бизнес Базовый",
"tariffPlansDetails":[
{
"billingObjectCode":"ft-payment",
"billingObjectName":"Создание рублевого платежного поручения",
"billingObjectStrategy":"MAX",
"tariffPackCount":1000,
"tariffPackFree":500
}
],
"tariffSystemName":"SECURE_BUSINESS_BASIC"
}
]

Потребление тарифа сверх нормы

Ресурс /v1/tariff-plans/over-billing позволяет Партнеру отправить запрос со сведениями о потреблении клиентом сверх нормы тарифного плана, чтобы с клиента списывалась дополнительная плата по тарифному плану.

Шаги

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

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

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

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

nen

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации-клиента, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
TariffPlanOverBillingRequest {
billingObjectCode (string)Код платного сервиса,
countServiceFact (integer)Количество фактов потребления услуги за период
(состояние на конец периода),
dateUntil (string, optional)Дата окончания актуальности списания,
tariffSystemName (string)Системное наименование тарифного плана услуги
}

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

{
"billingObjectCode": "ft-payments",
"countServiceFact": 1000,
"dateUntil": "2018-12-31",
"tariffSystemName": "SECURE_BUSINESS_BASIC"
}

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

В ответ возвращается http-код

Список тарифных планов

Ресурс /v1/tariff-plans позволяет получить список активных и архивных тарифных планов пользователя организации.

Шаги

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

2. Выбрать номер страницы (опционально).

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'https://edupirfintech.sberbank.ru:9443 /fintech/api/v1/tariff-plans?page=1'

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

НаименованиеОписание
{_links (Массив объектов JSON (array))[{
href (string (100))Абсолютный или относительный адрес
rel (string (4))Отношение ссылки к текущей сущности (next, prev)
}]
tariffPlans (Массив объектов JSON (array))[{
tariffSystemName (string (100))Системное наименование тарифного плана
tariffName (string (36))Наименование тарифного плана
tariffDescription (string (2000))Описание тарифного плана
tariffFreePeriod (number (3), optional)Бесплатный период
tariffFreePeriodType (string (1), optional)Размерность бесплатного периода, Y - год, Q - квартал, M - месяц, D - день
tariffPaymentType (string (36))Тип оплаты тарифа
tariffActivationDate (date)Дата подключения тарифа
tariffDisconnectionDate (date)Дата окончания тарификации
paymentStartDate (date)Дата начала тарификации
account (number (38), optional)Счет списания комиссии
freezeDate (date, optional)Дата и время приостановки тарифа
paymentEndDate (date, optional)Дата до которой оплачен тариф
bankStatus (string (50))Статус подписки
}]
}

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

{
"_links":[
{
"href":2,
"rel":"next"
}
],
"tariffPlans":[
{
"tariffSystemName": "Secure_business_Basic",
"tariffName": "Безопасный бизнес Базовый",
"tariffDescription": "Продукт позволяет избежать ограничений по 115-ФЗ",
"tariffFreePeriod": 1,
"tariffFreePeriodType": "M",
"tariffPaymentType": "UNPAID",
"tariffActivationDate": "2020-01-01",
"tariffDisconnectionDate": "2020-02-01",
"paymentStartDate": "2020-01-01",
"account": "40817810099910004312,
"freezeDate": "2020-02-01T23:59:59",
"paymentEndDate": "2020-02-01",
"bankStatus": "ACTIVE"
}]
}

Обновление счета для списания комиссии

Ресурс /v1/tariff-plans/account-update позволяет обновлять счет для списания комиссии подписки на тариф услуги в биллинге КИБ.

Шаги

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

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

Для изменения счета списания комиссии необходимо отправить POST-запрос (/v1/tariff-plans/account-update). Запрос обязательно должен содержать авторизационный токен к данным организации клиента (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

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

Пример

{
"tariffSystemName": Secure_business_Basic
"account": 40817810099910004312
}

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

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

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 преобразования:

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

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

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

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