Методы «Кредит в корзине»
Сценарий
1. Получить AccessToken.
2. Получить информацию по кредитным предложениям.
3. Создать кредитную заявку.
4. Получить статус платежки.
5. Выставить счет на оплату (только для виджета V2 после пункта 2).
На стороне авторизации нет метода, который позволяет завершить сессию СберБизнес.
Сессия СберБизнес завершается в случае если:
- Истекает срок действия Access Token (60 минут).
- Инициировано ее закрытие из интерфейса СберБизнес.
- Предлагается вариант решения данного ограничения на стороне партнера:
Вывести клиенту информационное сообщение о том, что при попытке сменить пользователя/выйти из ЛК SberBusinessID важно завершить сессию на стороне СберБизнес. Для этого необходимо выйти из СберБизнес и предложить ему вариант "Выйти из СберБизнес?". В случае согласия навигировать его в соседней вкладке на СберБизнес для выхода из ЛК SberBusinessID.
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443
Промышленный контур
https://fintech.sberbank.ru:9443
Условия доступности покупки в кредит
Возможность покупки в кредит на ресурсе Партнера должна предоставляться только при выполнении определенных условий:
Значение параметра buyOnCreditMmb, возвращаемого на запрос /user-info, - true.
Значение параметра orgBusinessSegment, возвращаемого на запрос /user-info, - 02 или 03.
ОПФ организации - ИП/ООО/ГКФХ.
Дата создания организации 6 или более месяцев от текущей даты.
Получение информации по кредитным предложениям
Ресурс /v1/credit-offers
позволяет получить информацию по кредитным предложениям от банка для сервиса Партнера, содержащую условия возможности покупки в кредит Клиентами сервиса.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения информации необходимо отправить GET-запрос (/v1/credit-offers), в котором передать авторизационный токен (Access Token), идентификатор сервиса и организационно-правовую форму. Авторизационный токен передается в параметре Authorization заголовка запроса.
Для получения информации по кредитным продуктам нужно отправить Access token организации-партнера.
Для получения информации по возобновляемой кредитной линии нужно отправить Access token организации-клиента (поля: contractNumber, availableSum, dateSince, dateUntil).
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис GET_CREDIT_OFFERS
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token организации-партнера, полученный через SSO Access token организации-клиента, полученный через SSO (получение информации по ВКЛ) Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1 |
Параметры запроса | |
clientID (Number) | Идентификатор сервиса |
lawForm (String) | Общепринятое сокращение организационно-правовой формы организации, для которой необходимо получить кредитные предложения |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/credit-offers?clientId=2345&lawForm=ИП'
Модель ответа
Наименование | Описание |
---|---|
creditOffers [ | |
creditOffer | |
] | |
creditOffer { | |
checkSum (number(16), optional) | Сумма займа, после которой потребуется выездная проверка по месту ведения бизнеса, |
clientId (number(38)) | Идентификатор внешнего сервиса, |
delayRepayment (integer, optional) | Льготный период, |
individual (boolean, optional), | |
orgLawForms (Array[OrgLawForm], optional) | Перечень организационно-правовых форм организаций, для которых доступен кредитный продукт, |
productCode (string(20)) | Код кредитного продукта, |
productName (string(255), optional) | Наименование кредитного продукта, |
questions (Array[QuestionForm], optional) | Список топ вопросов с ответами по созданию кредитной заявки, |
rate (string, optional) | Ставка по кредитному предложению (%), |
sumMax (string, optional) | Максимальная сумма доступная для покупки в кредит, |
sumMin (string, optional) | Минимальная сумма доступная для покупки в кредит, |
termMax (number(5), optional) | Максимальный срок кредита (в месяцах), |
termMin (number(5), optional) | Минимальный срок кредита (в месяцах) , |
contractNumber (string(255), optional) | Номер договора , |
availableSum (string, optional) | Сумма лимита , |
dateSince (date, optional) | Дата начала действия договора , |
dateUntil (date, optional) | Дата окончания договора , |
} | |
OrgLawForm { | |
name (string(130)) | Полное наименование организационно-правовой формы, |
shortName (string(5)) | Общепринятое сокращение организационно-правовой формы , |
} | |
QuestionForm { | |
answer (string(2500), optional) | Ответ на вопрос по созданию кредитной заявки, |
question (string(2500), optional) | Вопрос по созданию кредитной заявки |
} |
Пример ответа
[
{
"checkSum": 1.01,
"clientId": 1005,
"delayRepayment": 30,
"individual": true,
"orgLawForms": [
{
"name": "Индивидуальный предприниматель",
"shortName": "ИП"
}
],
"productCode": "MB-F-ip-19",
"productName": "СМАРТ-кредит",
"questions": [
{
"answer": "Подайте заявку онлайн.",
"question": "Как мне оплатить счет кредитными деньгами?"
}
],
"rate": 1.01,
"sumMax": 1.01,
"sumMin": 1.01,
"termMax": 36,
"termMin": 12
}
]
Наименование организационно-правовых форм, для которых доступны кредитные продукты и предложения для покупки в кредит
Полное наименование организационно - правовой формы | Общепринятое сокращение |
---|---|
Общество с ограниченной ответственностью | ООО |
Индивидуальный предприниматель | ИП |
Глава крестьянского (фермерского) хозяйства | ГКФХ |
Создание заявки на кредитный договор
Ресурс /v1/credit-requests
позволяет создать заявку на оформление кредитного договора.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
3. Подписать запрос транспортной подписью (опционально).
Для создания заявки необходимо отправить POST-запрос (/v1/credit-requests), в котором передать авторизационный токен к данным организации клиента (Access Token) и информацию по заявке. Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CREDIT_REQUEST
.
Параметры с меткой read only не отправляются в запросе.
Модель запроса и ответа
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Параметры тела запроса | |
CreditRequest { | |
account (string(34)) | Расчетный счет для зачисления денежных средств за заказ , |
amount (number(19, 2)) | Сумма заказа , |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа , |
bankStatus (string, optional, read only) | Статус документа. Возможные значение: RECEIVED – запрос получен банком, PROCESSED – кредитная заявка обработана клиентом , |
consent (Consent, optional ) | Информация по согласиям от партнера , |
creditAmount (number(19, 2)) | Запрошенная сумма кредита , |
creditProductCode (string(20)) | Код продукта для кредитного предложения, в рамках которого для клиента оформляется заявка , |
creditTerm (number(5)) | Срок кредита (в месяцах) , |
deliveryAmount (number(19, 2), optional) | Сумма доставки , |
externalId (string(36)) | Идентификатор запроса, присвоенный партнером , |
limitAmountMarketplace (number(19, 2), optional) | Сумма кредита от маркетплейса , |
marketplaceData (MarketplaceData, optional) | Данные от партнера об оборотах клиента , |
negativeOrderUrl (string(1000)) | Ссылка на заказ при отказе в выдаче кредита , |
orderId (string(50)) | Идентификатор заказа клиента (номер) , |
orderInfo (Array[OrderInfo], optional) | Информация о составе заказа , |
orderUrl (string(1000)) | Ссылка на заказ , |
payeeInfo (object[PayeeInfo], optional) | Реквизиты получателя , |
purpose (string(210)) | Назначение платежа , |
vatAmount (number(19,2), optional) | Сумма НДС , |
} | |
Consent { | |
consent (string(5)) | Получено согласие ("Yes"/"No") , |
consentHash (string(256)) | SHA-256 хеш поля consentText , |
consentText (string) | Текст согласия , |
firstname (string(36)) | Имя представителя , |
lastname (string(36)) | Фамилия представителя , |
middlename (string(36)) | Отчество представителя , |
position (string(36)) | Должность представителя ("Директор"/"ИП") , |
startDate (string(36)) | Дата подписания согласия , |
} | |
MarketplaceData { | |
commissions (Array[Commission], optional) | Информация по комиссиям , |
sellings (Array[Selling], optional) | Информация по реализации товара , |
stock (Stock, optional) | Информация по товарным остаткам , |
} | |
OrderInfo { | |
numOfPosition (integer, optional) | Количество позиций/товаров , |
position (string(100), optional) | Позиция/Наименование товара , |
price (number, optional) | Стоимость позиции , |
totalPrice (number, optional) | Итоговая стоимость , |
} | |
PayeeInfo { | |
payeeBankBic (string) | БИК получателя , |
payeeCorrAcc (string) | Кор счет получателя , |
payeeInn (string) | ИНН получателя , |
payeeKpp (string) | КПП получателя , |
payeeName (string) | Наименование получателя |
} | |
Commission { | |
logistic (number(19,2)) | Комиссия за доставку и логистику , |
period (string(38)) | Месяц реализации (мм.гггг) , |
stock (number(19,2)) | Начисления за услуги склада (хранение и операции сборки-разборки, приемки и тд) , |
transaction (number(19,2)) | Транзакционная комиссия |
} | |
Selling { | |
amount (number(19,2)) | Количество реализованного товара за период (реально выкупленный) , |
fov (number(5,2)) | FOV (Выкупаемость) , |
gmv (number(19,2)) | Совокупная стоимость товаров, проданных на торговой площадке за определенный период времени без учета возвратов, обмена и скидок , |
period (string(38)) | Месяц реализации (мм.гггг) , |
productDescription (string(800)) | Описание продукта , |
revenue (number(19,2)) | Выручка в руб. за период |
} | |
Stock { | |
amount (number(19,2)) | Количество остатка , |
assortiment (integer) | Количество уникальных товаров (ассортимент) , |
averagePrice (number(19,2)) | Средняя цена товара , |
date (string) | Дата, на момент которой имеется остаток , |
duration (integer) | Сколько дней в среднем товар лежит на складе (передается целое число, округленное математически) , |
productDescription (string (800)) | Описание продукта , |
registrationDate (string) | Дата регистрации партнера на площадке , |
warehousingModel (string (64)) | Модель работы с площадкой |
} |
Пример
{
"account": "40802810600000200000",
"amount": 1.01,
"bankComment": "string",
"bankStatus": "string",
"consent": {
"consent": "Yes",
"consentHash": "string",
"consentText": "string",
"firstname": "Дмитрий",
"lastname": "Петров",
"middlename": "Сергеевич",
"position": "Директор",
"startDate": "2018-12-31"
},
"creditAmount": 1.01,
"creditProductCode": "MB-F-ip-150",
"creditTerm": 48,
"deliveryAmount": 1.01,
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"limitAmountMarketplace": 1.01,
"marketplaceData": {
"commissions": [
{
"logistic": 1.01,
"period": "11.2021",
"stock": 1.01,
"transaction": 1.01
}
],
"sellings": [
{
"amount": 1.01,
"fov": 1.01,
"gmv": 1.01,
"period": "11.2021",
"productDescription": "Описание продукта",
"revenue": 1.01
}
],
"stock": {
"amount": 1.01,
"assortiment": 48,
"averagePrice": 1.01,
"date": "2018-12-31",
"duration": 48,
"productDescription": "Описание продукта",
"registrationDate": "2018-12-31",
"warehousingModel": "fbs"
}
},
"negativeOrderUrl": "https://www.partner.ru/negative_basket",
"orderId": "2128506",
"orderInfo": [
{
"numOfPosition": 1,
"position": "string",
"price": 1.01,
"totalPrice": 1.01
}
],
"orderUrl": "https://example.ru/order?uid=2128506",
"payeeInfo": {
"payeeBankBic": "044525225",
"payeeCorrAcc": "30101810400000000225",
"payeeInn": "7707083893",
"payeeKpp": "222201001",
"payeeName": "Общество с ограниченной ответственностью \"Клиент\""
},
"purpose": "Оплата заказа №2128506 от 23.12.2019. НДС 20% - 1,01 рублей",
"vatAmount": 1.01
}
Правила заполнения полей сумма заказа (amount) и запрошенная сумма кредита (creditAmount):
Если сумма заказа (значение amount) больше максимальной суммы доступной для покупки в кредит (значение sumMax, полученное в ответе на запрос /v1/credit-offers), то уведомлять клиента о сумме заказа, которую он может оплатить.
Если клиенту доступна оплата несколькими платежами, то предлагать выбор: оплатить часть заказа или изменить сумму заказа (значение amount).
Если клиент выбирает оплатить часть заказа, то заполнять сумму заказа (значение amount) значением остатка по кредитной линии (availableSum, полученное в ответе на запрос /v1/credit-offers).
Если сумма заказа (значение amount) меньше минимальной суммы доступной для покупки в кредит (значение sumMin, полученное в ответе на запрос /v1/credit-offers), то заполнять сумму заказа значением amount, а запрошенную сумму кредита (creditAmount) заполнять минимальной суммой доступной для покупки в кредит (sumMin).
Если сумма заказа (значение amount) между минимальной (sumMin) и максимальной (sumMax) суммами доступными для покупки в кредит, то заполнять сумму заказа и запрошенную сумму кредита (creditAmount) значением amount.
В запросе создания кредитной заявки (POST /v1/credit-requests) нужно включать контекст НДС в поле purpose (назначение платежа):
- ... НДС ...
- ... НДС не облагается ...
- Вот примеры заполнения:
- Оплата заказа ххх от dd.mm.yy. НДС не облагается.
- Оплата заказа ххх от dd.mm.yy. В том числе НДС - ..... руб.
При указании размера НДС в рублях и копейках, не допускается расчет далее 2х знаков после запятой (корректный пример 7675,44, пример некорректного заполнения 6475,444). Знак разделения разрядов может быть как точка, так и запятая.
Переадресация клиента на кредитную заявку
- Партнер определяет с помощью ресурса /v1/oauth/user-info тип криптопрофиля клиента (userCryptoType)
- Партнер переадресует клиента по ссылке: 2.1. Если СМС, то URL СберБизнес = https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic/dcb/index.html#/credits/credit-financing/credit-partners?order=externalID 2.2 Если токен, то URL СберБизнес = http://localhost:28016/ic/dcb/index.html#/credits/credit-financing/credit-partners?order=externalID
Дополнительная информация
Подписание запроса транспортной подписью
Content-Type может содержать одно из двух значений:
- application/json – запрос без подписи
- application/jose – запрос, подписанный транспортной подписью
Если Content-Type имеет значение application/jose, то запрос должен содержать данные в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).
JWS состоит из трёх частей:
- Заголовок (Header) - определяет алгоритм подписи и тип токена
- Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
- Электронная подпись (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) | / |
Коды возврата
Код возврата | Описание кода возврата | Причина возникновения | |
---|---|---|---|
200 (GET-запроса) | OK | ||
201 (POST-запрос) | CREATED | ||
Создан | |||
400 | DESERIALIZATION_FAULT | ||
Неверный формат запроса | Неверный формат запроса | ||
WORKFLOW_FAULT | |||
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ | Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика | ||
Документ с такими реквизитами уже существует | Документ с такими реквизитами уже существует. Проверка по номер документа в течении года. | ||
Не указан идентификатор сертификата подписи | Не указан идентификатор сертификата подписи(параметр kid заголовка JWS) | ||
Некорректный формат параметра kid заголовка JWS | Некорректный формат параметра kid заголовка JWS(ожидается UUID) | ||
Указана некорректная ссылка на заказ | В теле запроса в поле orderUrl указана некорректная ссылка на заказ | ||
VALIDATION_FAULT | |||
Ошибка валидации | Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели. | ||
SIGN_CHECK_EXCEPTION | |||
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным | Ошибка возникает, если не удалось установить подлинность подписи | ||
401 | UNAUTHORIZED | ||
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х | Указан некорректный или просроченный access_token. | ||
403 | ACTION_ACCESS_EXCEPTION | ||
Операция не может быть выполнена: доступ к ресурсу запрещен | У пользователя нет прав на использование соответствующего сервиса Sber API, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом. | ||
404 | DATA_NOT_FOUND_EXCEPTION | ||
Не найдено ни одного заранее данного акцепта за указанную дату | Не найдено ни одного заранее данного акцепта за указанную дату | ||
415 | JWS_EXCEPTED | ||
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization | Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса» | ||
500 | UNKNOWN_EXCEPTION | ||
Внутренняя ошибка сервера | |||
503 | UNAVAILABLE_RESOURCE_EXCEPTION | ||
Сервис временно недоступен | Проводятся технические работы |