ym88659208ym87991671
Управление лимитами | Документация SmartMarket
Skip to main content

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

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

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

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

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

Получение списка карт

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

note

Запрос списка карт производится постранично. Необходимо запрашивать постранично данные бизнес-карт, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить href c признаком "rel": "next", что будет означать, что следующей страницы нет. На запрос первой страницы в ответе вернется список карт, если они существуют, и контейнер links с параметром (href) на следующую страницу и признаком "rel": "next". На запрос второй страницы в ответе вернется список карт и контейнер links с параметром (href) на следующую и предыдущую страницы и признаками "rel": "prev", "rel": "next". Получение последующих страниц производится по аналогии.

Шаги

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

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

Авторизация

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token полученный через SSO
Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры запроса
page (Integer)Номер страницы со списком бизнес-карт Пример: 1
statusCodes (String)Список статусов бизнес-карт. Указывается в случае, если необходимо получить список бизнес-карт, имеющих один из перечисленных статусов
Возможные статусы:

ACTIVE – Активна,

BLOCKED – Заблокирована,

TO_BE_REISSUED – Запрошен перевыпуск,

TO_BE_BLOCKED – Запрошена блокировка,

NOT_DELIVERED – Выпущена, но не доставлена

Передается в формате: statusCodes=ACTIVE,NOT_DELIVERED
Изменение разовых лимитов возможны только для карт в статусах ACTIVE и NOT_DELIVERED

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

curl -X POST --header 'Accept: application/json' --header
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/business-cards?page=1&statusCodes=ACTIVE,NOT_DELIVERED'

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

НаименованиеОписание
BusinessCards
links (массив JSON (array))
href (String (60), optional)Абсолютный или относительный адрес
rel (String, optional)Отношение ссылки к текущей сущности
businessCards (массив JSON (array))
accountNumber (String, optional)Номер счета, к которому привязана карта
bankBic (String, optional)БИК банка бизнес-карты
businessCardId (String, optional)Уникальный идентификатор бизнес-карты
embossedText (String, optional)Эмбоссированный текст
cardExpiredDate (Date, optional)Срок действия карты
cardholderName (String, optional)ФИО держателя
cardholderBirthday (Date, optional)Дата рождения держателя
cardPan (String, optional)Маскированный номер карты
cardType (String, optional)Тип карты
status (String, optional)Статус карты

ACTIVE – Активна,

BLOCKED – Заблокирована,

TO_BE_REISSUED – Запрошен перевыпуск,

TO_BE_BLOCKED – Запрошена блокировка,

NOT_DELIVERED – Выпущена, но не доставлена)

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

{
"links":[
{
"href":"?page=2",
"rel":"prev"
},
{
"href":"?page=4",
"rel":"next"
}
],
"businessCards":[
{
"accountNumber":"40802840600000200000",
"bankBic":"044525225",
"businessCardId":"5fd99a56-b8a3-11eb-8529-0242ac130003",
"embossedText":"KARTY BUSINESS",
"cardExpiredDate":"2021-04-01",
"cardholderName":"Иванов Иван Иванович",
"cardholderBirthday":"1980-01-01",
"cardPan":"1234********5678",
"cardType":"Visa BusinessCard",
"status":"ACTIVE"
}
]
}

Создание заявления

Ресурс /v1/business-cards/limits позволяет создавать документ: «Заявления на изменение лимита бизнес-карты» – черновик или ЭД заверенный ЭП.

Шаги

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

2. Сформировать ЭП.

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

4. Получить статус.

Авторизация

Для создания заявления на изменение лимита бизнес-карты необходимо отправить POST-запрос (/v1/business-cards/limits), в котором нужно передать авторизационный токен к данным собственной организации (Access Token) и реквизиты заявления. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String )Access token полученный через SSO.
Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры запроса
BusinessCardLimitChangeRes
code (string)Код лимита
businessCardId (string)Идентификатор бизнес-карты
externalId (string)Идентификатор документа, присвоенный партнером (UUID)
limit (Number (38, 2))Код лимита
digestSignatures
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

{
"code": "NON_RENEW",
"businessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22",
"digestSignatures": [{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22",
"limit": 2650000.00
}
note

Возможна установка лимита только с кодом NON_RENEW – Лимит на период.
Если лимит с кодом NON_RENEW устанавливается равным 0, то срок его действия равен сроку жизни карты. Если лимит с кодом NON_RENEW устанавливается на большую сумму – срок его действия истекает в конце следующего календарного дня с даты установки лимита.
Изменение разовых лимитов возможны только для карт в статусах ACTIVE и NOT_DELIVERED

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

НаименованиеОписание
BusinessCardLimitChangeRes
bankComment (string, optional, read only)Банковский комментарий к статусу документа
bankStatus (string, optional, read only)Статус документа
code (string)Код лимита
businessCardId (string)Идентификатор бизнес-карты
date (Date, optional)Дата заявления
externalId (string)Идентификатор документа, присвоенный партнёром (UUID)
limit (Number (38, 2))Код лимита
number (String, optional)Номер заявления
digestSignatures
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

{
"bankComment":null,
"bankStatus":"CREATED",
"code":"NON_RENEW",
"businessCardId":"31663ef5-7975-4016-b0f3-f1d70a4e9c22",
"date":"2021-01-01",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"31663ef5-7975-4016-b0f3-f1d70a4e9c22",
"limit":2650000.00,
"number":"5"
}

Передача электронной подписи вместе с документом

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature (все поля обязательны):

Наименования поляОписания поляПример
base64Encoded (string)Значение ЭП документаHlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (string)Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto)22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

Можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа. Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу. Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись;
  • первая и вторая подписи.

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля, когда пользователь Партнера создается в Банке.

Алгоритм сортировки дайджеста

Теги дайджеста должны быть отсортированы по алфавиту.

Формат дайджеста

Наименование поляОписание поляПример
businessCardIdИдентификатор бизнес-карты31663ef5-7975-4016-b0f3-f1d70a4e9c22
codeКод лимитаNON_RENEW
externalIdИдентификатор заявления в организации-партнёре31663ef5-7975-4016-b0f3-f1d70a4e9c22
limitРазмер лимита на период2650000.00

Пример дайджеста

businessCardId=31663ef5-7975-4016-b0f3-f1d70a4e9c22
code=NON_RENEW
externalId=31663ef5-7975-4016-b0f3-f1d70a4e9c22
limit=2650000.00

Получение статуса заявления

Ресурс /v1/business-cards/limits/{externalId}/state позволяет партнеру получить статус ранее отправленного электронного документа\черновика – «Заявление на изменение лимита бизнес-карты».

Шаги

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

2. Получить externalId.

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

Авторизация

Для получения информации о статусе рассмотрения заявления на изменение лимита бизнес-карты необходимо отправить GET запрос (/v1/business-cards/limits/{externalId}/state), в котором нужно передать авторизационный токен к данным организации клиента (Access Token) и идентификатор заявления. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token полученный через SSO
Пример: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1
Параметры запроса
externalId (String)Идентификатор документа, присвоенный в организации-партнере
Пример: 550e8400-e29b-41d4-a716-446655440000

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/business-cards/limits/550e8400-e29b-41d4-a716-446655440000/state'

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

НаименованиеОписание
DocState
bankComment (string, optional, read only)Комментарий к статусу,
bankStatus (string, optional)Статус заявления на открытие бизнес-карты

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

{
"bankStatus":"EXPORTED",
"bankComment":null
}

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

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

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

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

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

JWS состоит из:

  • заголовка (Header),
  • JSON-документа с реквизитным составом платежного поручения (Payload),
  • подписи запроса (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.

BASE64URLBASE64
- (minus)+
_ (underline)/

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

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

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

Код возвратаОписание кода возвратаПричина возникновения
200 (GET-запроса)CREATED
Создан
201 (POST-запрос)CREATED
Создан
400DESERIALIZATION_FAULT
Неверный формат запросаНеверный формат запроса
VALIDATION_FAULT
Ошибка валидацииОшибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели
401UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан некорректный или просроченный access_token.
403ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещенУ пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом
404DATA_NOT_FOUND_EXCEPTION
Бизнес-карта с указанным ID не найденаНевозможно найти бизнес-карту с указанным внешним идентификатором
500UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступенПроводятся технические работы
Обновлено 20 апреля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней