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

Обновлено 29 февраля 2024

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

Тестовый контур https://iftfintech.testsbi.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 f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
page (Integer)	Номер страницы со списком бизнес-карт. По умолчанию 100 карт на странице. Пример: 1
statusCodes (String, optional)	Список статусов бизнес-карт. Указывается в случае, если необходимо получить список бизнес-карт, имеющих один из перечисленных статусов Возможные статусы: `ACTIVE` – Активна, `BLOCKED` – Заблокирована, `TO_BE_REISSUED` – Запрошен перевыпуск, `TO_BE_BLOCKED` – Запрошена блокировка, `NOT_DELIVERED` – Выпущена, но не доставлена Передается в формате: `statusCodes=ACTIVE,NOT_DELIVERED` `statusCodes=ACTIVE&statusCodes=NOT_DELIVERED` Изменение разовых лимитов возможны только для карт в статусах `ACTIVE` и `NOT_DELIVERED`

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

curl -X POST --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://iftfintech.testsbi.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))
businessCardId (String, optional)	Уникальный идентификатор бизнес-карты
cardExpiredDate (Date, optional)	Срок действия карты
cardholderName (String, optional)	Замаскированное ФИО держателя
cardPan (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": [
        {
            "businessCardId": "5fd99a56-b8a3-11eb-8529-0242ac130003",
            "cardExpiredDate": "2021-04-01",
            "cardholderName": "И**** И**** И****",
            "cardPan": "1234********5678",
            "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 f8ad3141-b7e8-4924-92de-3de4fd0a464e-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` или `/v1/crypto/eio)`	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 f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
externalId (String)	Идентификатор документа, присвоенный в организации-партнере Пример: 550e8400-e29b-41d4-a716-446655440000

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/business-cards/limits/550e8400-e29b-41d4-a716-446655440000/state'

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

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

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

{
    "bankComment": null,
    "bankStatus": "CREATED",
    "channelInfo": null
}

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

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

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-запроса)	`CREATED`
	Создан
201 (POST-запрос)	`CREATED`
	Создан
400	`DESERIALIZATION_FAULT`
	Неверный формат запроса	Неверный формат запроса
	`WORKFLOW_FAULT`
	Не указан идентификатор сертификата подписи	Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
	Некорректный формат параметра kid заголовка JWS	Некорректный формат параметра kid заголовка JWS(ожидается UUID)
	Системный параметр получения срока действия лимита выключен	На стороне банка не указан системный параметр срока действия лимита выключен
	По данной карте установить лимит невозможно. Пожалуйста, обратитесь в техническую поддержку
	Карта с идентификатором 31663ef5-7975-4016-b0f3-f1d70a4e9c22 недоступна для внешнего сервиса	Для внешнего сервиса недоступны операции по счету: счет, к которому привязана карта, не добавлен в список разрешенных в оферте;
	`VALIDATION_FAULT`
	Ошибка валидации	Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели
	`SIGN_CHECK_EXCEPTION`
	Подлинность подписи не установлена/Сертификат не обнаружен или не является активным	Ошибка возникает, если не удалось установить подлинность подписи
401	`UNAUTHORIZED`
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	`ACTION_ACCESS_EXCEPTION`
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса Sber API (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом
404	`CARD_ID_NOT_FOUND`
	Бизнес-карта с указанным ID не найдена	Невозможно найти бизнес-карту с указанным внешним идентификатором
	`NOT_FOUND`
	Ресурс не найден
415	`JWS_EXCEPTED`
	В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization	Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500	`UNKNOWN_EXCEPTION`
	Внутренняя ошибка сервера
503	`UNAVAILABLE_RESOURCE_EXCEPTION`
	Сервис временно недоступен	Проводятся технические работы

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

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

Шаги﻿

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

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

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

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

Создание заявления на изменение лимита бизнес-карты﻿

Шаги﻿

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

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

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

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

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

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

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

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

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

Шаги﻿

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

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

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

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

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

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

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

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

Шаги

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

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

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

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

Создание заявления на изменение лимита бизнес-карты

Шаги

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

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

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

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

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

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

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

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

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

Шаги

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

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

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

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

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

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

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