Управление тарифными планами
Для обращения к ресурсу необходимо отправлять запрос на:
Текущий тестовый контур
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 | ||
Сервис временно недоступен | Проводятся технические работы |