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

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

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

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

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

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

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

Код возврата	Описание кода возврата	Причина возникновения
200 (GET-запроса)	`OK`
201 (POST-запрос)	`CREATED`
	Создан
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`
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404	`DATA_NOT_FOUND_EXCEPTION`
	Не найдено ни одного заранее данного акцепта за указанную дату	Не найдено ни одного заранее данного акцепта за указанную дату
415	`JWS_EXCEPTED`
	В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization	Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500	`UNKNOWN_EXCEPTION`
	Внутренняя ошибка сервера
503	`UNAVAILABLE_RESOURCE_EXCEPTION`
	Сервис временно недоступен	Проводятся технические работы

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

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

Шаги﻿

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

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

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

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

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

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

Шаги﻿

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

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

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

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

Шаги﻿

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

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

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

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

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

Шаги﻿

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

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

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

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

Шаги﻿

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

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

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

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

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

Шаги﻿

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

Пример﻿

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

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

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

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

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

Шаги

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

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

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

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

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

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

Шаги

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

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

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

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

Шаги

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

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

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

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

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

Шаги

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

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

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

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

Шаги

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

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

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

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

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

Шаги

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

Пример

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

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

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

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