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

Обновлено 20 апреля 2022

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

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

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

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

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

Запрос списка карт производится постранично. Необходимо запрашивать постранично данные бизнес-карт, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить 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 
}

Возможна установка лимита только с кодом 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 может содержать одно из двух значений:

application/json – запрос без подписи.
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.

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

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

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

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

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

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

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

Шаги﻿

Авторизация﻿

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

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

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

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

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

Шаги﻿

Авторизация﻿

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

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

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

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

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

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

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

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

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

Шаги﻿

Авторизация﻿

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

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

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

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

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

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

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

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

Шаги

Авторизация

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

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

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

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

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

Шаги

Авторизация

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

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

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

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

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

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

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

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

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

Шаги

Авторизация

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

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

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

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

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

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

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