Канал SberBusinessAPI в 1С

[art-nv]

Добрый день. Подскажите пожалуйста, кто ни будь внедрял систему SberBusinessAPI в 1С (УФ). Или подскажете, конфигурации, примеры, ссылки использования системы. Конкретно интересует система перевода B2C, с бизнес-карт на карты физлиц. Документация по сервису "https://developers.sber.ru/docs/ru/sberbusinessapi/host/business-card/transfer

Документация для разработчиков

Обновлено

10 февраля 2023

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

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

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

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

Сервисы переводов SberBusinessAPI позволяют запрашивать расчет комиссии за перевод, отправлять заявление на перевод, а также запрашивать статус этого заявления.

В заявлении на перевод должны указываться: карта отправителя, карта получателя, сумма перевода, размер комиссии, назначение перевода, а также внешний идентификатор заявления на перевод.

Карта отправителя должна указываться в виде идентификатора. Идентификаторы бизнес-карт организации можно получить в ответе на запрос получения списка бизнес-карт организации GET /v1/business-cards (поле businessCardId).

Перевод по номеру карты	Отправитель перевода
Вид карты	Дебетовая бизнес-карта ПАО Сбербанк
Валюта перевода	Рубли РФ
География	Трансграничные переводы запрещены
Платежная система	VISA, Mastercard, МИР

В зависимости от типа перевода (перевод B2B или B2C) карта получателя может быть указана разными способами.

Переводы B2C

Переводы с бизнес-карт Сбера физическому лицу могут осуществляться с помощью:

• Указания номера карты получателя (любая карта ПАО Сбербанк и других банков-эмитентов РФ). В этом случае в заявлении на перевод заполняется поле receiverCardNumber, а receiverPhoneNumber не заполняется;

• Указания номера телефона получателя (карта ФЛ ПАО Сбербанк). В этом случае в заявлении на перевод должно заполняться поле receiverPhoneNumber (формат заполнения поля: 79000000000), а receiverCardNumber не заполняется.

Переводы B2B

В случае перевода с бизнес-карты Сбера юридическому лицу перевод осуществляется только с указанием номера карты получателя (любая карта ПАО Сбербанк и других банков-эмитентов РФ). В заявлении на перевод заполняется поле receiverCardNumber, а receiverPhoneNumber не заполняется.

Заполнение поля receiverCardNumber

В поле receiverCardNumber не допускается передача номера карты получателя в открытом виде, значение номера карты должно быть обязательно зашифровано. Номер карты перед шифрованием не должен содержать пробелов и спецсимволов. Получившуюся строку необходимо зашифровать, используя алгоритм RSA шифрования "RSA/OAEP" с ключом длиной 2048.

Пример:

Строка перед шифрованием - 0000000000000000

Зашифрованная строка - HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT

Открытая компонента ключа будет предоставлена Банком при подключении сервиса.

Перевод между бизнес-картами должен осуществляться в несколько этапов:

1. Запросить значение комиссии за перевод.
2. Отправить заявление на перевод, указав значение комиссии из предыдущего шага.
3. Опрашивать статус заявления на перевод до получения конечного статуса.

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

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

Шаги

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
amount (number)	Сумма перевода в рублях Пример: 250.00
commission (number, read only)	Размер комиссии в рублях Пример: 1.00
receiverCardNumber (string)	Зашифрованный номер карты получателя Пример: HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT
receiverPhoneNumber (string)	Номер телефона получателя Пример: 79880098877
senderBusinessCardId (string)	ID карты отправителя Пример: f8ad3141-b7e8-4924-92de-3de4fd0a464e-1

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

{ "amount": 25.00, "commission": 2.00, "receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22" }


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

Наименование	Описание
BusinessCardCommissionResponse
amount (number)	Сумма перевода в рублях
bankComment (string, optional, read only)	Комментарий
bankStatus (string)	Статус запроса
commission (number, read only)	Размер комиссии в рублях
receiverCardNumber (string)	Зашифрованный номер карты получателя
receiverFullName (string)	ФИО получателя
receiverPhoneNumber (string)	Номер телефона получателя
senderBusinessCardId (string)	ID карты отправителя

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

{ "amount": 25.00, "bankComment": "Некорректный размер комиссии", "bankStatus": "OK", "commission": 3.00, "receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "receiverFullName": "ИЛЬЯ ЛЕОНИДОВИЧ Е." "senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22" }


Отправка заявления на перевод между бизнес-картами

Ресурс /v1/business-cards/transfer позволяет создавать документ «Заявление на перевод между бизнес-картами» как в виде черновика, так и в виде документа, заверенного ЭП.

Шаги

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

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

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
amount (number)	Сумма перевода в рублях Пример: 250.00
commission (number)	Размер комиссии в рублях Пример: 1.00
Signature
base64Encoded (string)	Значение электронной подписи, закодированное в Base64
certificateUuid (string)	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
externalId (string)	Внешний идентификатор заявления на перевод Пример: 31663ef5-7975-4016-b0f3-f1d70a4e9c22
purpose (string)	Назначение перевода
receiverCardNumber (string)	Зашифрованный номер карты получателя Пример: HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT
receiverPhoneNumber (string)	Номер телефона получателя Пример: 79880098877
senderBusinessCardId (string)	ID карты отправителя Пример: 31663ef5-7975-4016-b0f3-f1d70a4e9c22

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

{ "amount": 25.00, "commission": 2.00, "digestSignatures": [{ "base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6" } ], "externalId": "f8ad3141-b7e8-4924-92de-3de4fd0a464e", "purpose": "Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС", "receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22" }


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

Наименование	Описание
BusinessCardTransferResponse
amount (number)	Сумма перевода в рублях
bankComment (string, optional, read only)	Банковский комментарий к статусу документа
bankStatus (string)	Статус документа
commission (number, read only)	Размер комиссии в рублях
Signature
base64Encoded (string)	Значение электронной подписи, закодированное в Base64
certificateUuid (string)	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
externalId (string)	Внешний идентификатор заявления на перевод
purpose (string)	Назначение перевода
receiverCardNumber (string)	Зашифрованный номер карты получателя
receiverFullName (string)	ФИО получателя
receiverPhoneNumber (string)	Номер телефона получателя
senderBusinessCardId (string)	ID карты отправителя

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

{ "amount": 25.00, "bankComment": "string", "bankStatus": "DELIVERED", "commission": 2.00, "digestSignatures": [{ "base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6" } ], "externalId": "f8ad3141-b7e8-4924-92de-3de4fd0a464e", "purpose": "Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС", "receiverCardNumber": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==", "receiverFullName": "СЕРГЕЙ ВАСИЛЬЕВИЧ А.", "senderBusinessCardId": "31663ef5-7975-4016-b0f3-f1d70a4e9c22" }


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

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

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

Для заявлений можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

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

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

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

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

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

С дополнительной информацией можно ознакомиться в инструкции.

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

В дайджесте в соответствии с запросом должно быть указано либо поле receiverCardNumber, либо поле receiverPhoneNumber.

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

В дайджесте не указывается значение number.

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

Наименование поля	Описание поля	Пример
amount	Размер перевода	25.00
commission	Размер комиссии	2.00
externalId	Внешний идентификатор документа	f8ad3141-b7e8-4924-92de-3de4fd0a464e
purpose	Назначение перевода	Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДС
receiverCardNumber	Зашифрованный номер карты получателя	HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep
receiverPhoneNumber	Номер телефона получателя	79880098877
senderBusinessCardId	ID карты отправителя бизнес-карты	31663ef5-7975-4016-b0f3-f1d70a4e9c22

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

amount=25.00commission=2.00externalId=f8ad3141-b7e8-4924-92de-3de4fd0a464epurpose=Иванов Иван Ильич, 1234 987654; ПСА №123 от 01.01.2020; лом стальной, 123 кг, 15000 руб./т.; без НДСreceiverCardNumber=HlaeIHXXEcGT1bFxo1NlpAzprreceiverPhoneNumber=79880098877senderBusinessCardId=31663ef5-7975-4016-b0f3-f1d70a4e9c22


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

Ресурс /v1/business-cards/transfer/{externalId}/state позволяет получить статус ранее отправленного заявления на перевод между бизнес-картами.

Шаги

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

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
externalId (number)	Внешний идентификатор документа Пример: 550e8400-e29b-41d4-a716-446655440000

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

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


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

Наименование	Описание
BusinessCardTransferResponse
bankComment (string)	Банковский комментарий к статусу документа Пример: null
bankStatus (string)	Статус документа Пример: CREATED
channelInfo (string)	Комментарий, специфичный для документа, полученного по данному каналу Пример: null

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

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


Возможные статусы

Код состояние документа	Наименование статуса
	Промежуточный/Продолжать опрашивать
ACCEPTED	Принят
CREATED	Создан
DELIVERED	Доставлен
EXPORTED	Выгружен
SIGNED	Подписан
	Окончательный/Прекратить опрос
CHECKERROR	Ошибка контроля
FRAUDDENY	Отвергнут ФРОД
INVALIDEDS	ЭП/АСП не верна
PROCESSERROR	Отказано Банком
REFUSEDBYABS	Отказан АБС
	Окончательный(Успешный)/Прекратить опрос
PROCESSED	Исполнен

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

Код возврата	Описание кода возврата	Причина возникновения
200	OK
	Успешный код возврата
201	CREATED
	Документ создан
400	DESERIALIZATION_FAULT
	Неверный формат запроса	Неверный формат запроса.
	WORKFLOW_FAULT
	Ошибка расчета комиссии, операция отклонена. Обратитесь к агрегатору	Проверка полученной комиссии от Платформы на минимально возможную не пройдена.
	Операция отклонена. Обратитесь к агрегатору	Размер выставленной суммы комиссии за перевод равен "0" или равен = меньше установленной суммы.
	Карта с идентификатором хххххххх-хххх-хххх-хххх-хххххххххххх недоступна для внешнего сервиса
	Не указан номер документа
	Номер документа длиннее допустимого
	Номер документа не должен содержать пробелы
	Номер документа содержит недопустимые символы
	Номер документа не может быть равен нулю
	Некорректно заполнена дата документа
	Некорректный номер карты списания
	Карта списания не найдена
	Карта списания неактивна
	Перевод невозможен, данные держателя карты не совпадают с данными вашей учетной записи
	Не указана сумма перевода
	В документе указана нулевая или отрицательная сумма
	Не установлен лимит на транзакцию для перевода с карты на карту
	Сумма перевода превышает лимит на транзакцию для перевода с карты на карту
	Некорректный номер карты зачисления
	Для карты зачисления указан тот же счёт, что и у карты списания
	Наличие комплаенс-блокировки
	В поле "${fieldName}" необходимо указать 11 цифр
	Карта с идентификатором хххххххх-хххх-хххх-хххх-хххххххххххх недоступна для внешнего сервиса
	Возникли проблемы с картой получателя
	Карта зачисления не является картой Сбербанка
	Недостаточно средств
	Операция в данный момент недоступна, попробуйте повторить позднее
	Операция недоступна для выбранной карты
	Перевод не может быть выполнен. Превышен лимит по карте
	Перевод не может быть выполнен. Проверьте номер карты получателя
	Пожалуйста, для проверки карты отправителя обратитесь в контактный центр Банка по телефону 8-800-5555-777, с моб. 0321
	Пожалуйста, обратитесь в контактный центр Банка для проверки карты
	VALIDATION_FAULT
	Ошибка валидации	Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
401	UNAUTHORIZED
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	ACTION_ACCESS_EXCEPTION
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404	NOT_FOUND
	Ресурс не найден
	CARD_ID_NOT_FOUND
	Бизнес-карта с указанным ID не найдена	Невозможно найти бизнес-карту отправителя с указанным внешним идентификатором.
500	UNKNOWN_EXCEPTION
	Внутренняя ошибка сервера	Внутренняя ошибка сервера
503	UNAVAILABLE_RESOURCE_EXCEPTION
	Сервис временно недоступен	Проводятся технические работы

"