Большие файлы

Обновлено 19 сентября 2023

Обращаем внимание, что с 01.07.2023 в связи с усилением мер обеспечения кибербезопасности при предоставлении информации, относящейся к банковской тайне и содержащей персональные данные Клиента, в соответствии с 152-ФЗ («О персональных данных») и 149-ФЗ («Об информации, информационных технологиях и о защите информации») при В2В интеграции Партнерам при использовании ресурса /v1/files/tasks-for-download необходимо скачивать файл с выпиской под своим TLS-сертификатом в свое хранилище и передавать ссылку Клиентам уже на свое хранилище, в котором не будет проверки TLS-сертификата.

Данные доработки Партнерам необходимо реализовать в срок до 01 октября 2023, после указанного срока при скачивании файла будет осуществляться проверка на наличие и принадлежность TLS-сертификата.

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

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

Получение ссылки на скачивание файла

Ресурс /v1/files/download позволяет получить ссылку для скачивания файла. Скачать файл после получения ссылки возможно только после получения положительного статуса о готовности файла для скачивания. Проверка статуса осуществляется с помощью ресурса /v1/files/downloadState.

Шаги

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

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

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

Для создания запроса ссылки на скачивание файла необходимо отправить POST-запрос (/v1/files/download), в заголовке запроса необходимо передать авторизационный токен организации (Access Token).

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
FileDownloadRequest {
fileIds (Array[string])	Список идентификаторов файлов
}

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

{
   "fileIds":[
      "ada5de61-4e8d-419c-9f3d-1409198924b3",
      "dee05d88-9a4d-40ef-924b-f80373d4007f"
   ]
}

Получение статуса файла

Ресурс /v1/files/downloadState позволяет получить статус о готовности файла для скачивания.

Шаги

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
FileDownloadStateRequestt {
fileIds (Array[string])	Список идентификаторов файлов
}

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

{
"fileIds": [
"TwyoRxWisy_YQI6hBHGKZSOAYrzV-LTz0I_Jy5eTMEpTJW4_R_W8y9_2StuKtv8p"
]}

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

Наименование	Описание
FileDownloadStateRequest [
FileDownloadStateRequest 1
]FileDownloadStateRequest 1 {
bankComment (string, optional)	Банковский комментарий к статусу загрузки файла,
fileId (string, optional)	Идентификатор файла,
status (string, optional)	Статус загрузки файла = [`PREPARING_FOR_DOWNLOAD`, `READY_FOR_DOWNLOAD`, `ERROR`, `OUTDATED`, `SPOILED`, `UNKNOWN_STATUS`] stringEnum: `PREPARING_FOR_DOWNLOAD`, `READY_FOR_DOWNLOAD`, `ERROR`, `OUTDATED`, `SPOILED`, `UNKNOWN_STATUS`
url (string, optional)	Ссылка для загрузки файла
}

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

[{
"bankComment": "string",
"fileId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"status": "PREPARING_FOR_DOWNLOAD",
"url": "https://bf.sberbank.ru:9443/sbns-app/download/020b7237-f874-42ce-89bb-02d39d400bcd"
}]

Получение ссылки для загрузки формы

Ресурс /v1/files/tasks-for-download позволяет получить ссылку для загрузки печатной формы файла выписки, по ранее сформированной задаче.

Шаги

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

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

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

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

Модель запроса и ответа

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1`
Параметры запроса
taskId (String)	Идентификатор задачи на скачивание.

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/files/
tasks-for-download/5120f687-c916-300b-9d68-0ce22f4f3f9d'

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

Наименование	Описание
TaskForDownload {
filename (string, optional)	Имя файла ,
id (integer, optional)	Идентификатор ,
state (string, optional)	Состояние = ['CREATED', 'PROCESSING', 'ERROR', 'EXECUTED', 'EXPIRED'],
url (string, optional)	Ссылка для загрузки файла
}

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

{
"filename": "Выписка за 2020.05.08 счет 40802810600000200000.zip",
"id": 1,
"state": "CREATED",
"url": "https://bf.sberbank.ru:9443/sbns-app/download/020b7237-f874-42ce-89bb02d39d400bcd"
}

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

Код статуса	Наименование	Состояние
`PREPARING_FOR_DOWNLOAD`	Подготовка файла к загрузке	Промежуточный / Продолжать опрашивать
`READY_FOR_DOWNLOAD`	Файл готов к загрузке	Конечный результат (Успешный) / Прекратить опрос
`ERROR`	Ошибка загрузки файла	Конечный / Прекратить опрос
`OUTDATED`	Задача загрузки устарела	Конечный / Прекратить опрос
`SPOILED`	Задача загрузки замещена другой	Конечный / Прекратить опрос
`UNKNOWN_STATUS`	Неизвестный статус загрузки файла	Промежуточный / Продолжать опрашивать

Всем Партнерам при В2В интеграции (когда файл с выпиской запрашивается по счетам Клиентов) необходимо сделать доработки на своей стороне: при получении ссылки на скачивание файла с выпиской по методу /v1/files/tasks-for-download скачивать файл под своим TLS-сертификатом в свое хранилище и передавать ссылку Клиенту на свое хранилище, в котором уже не будет проверки TLS-сертификата.

Загрузка файлов

С помощью ресурса /v1/files/upload можно загружать файлы на ресурс Банка для дальнейшей привязки к документу.

Сценарий:

1. Получение ссылки с помощью ресурса /v1/files/upload.

2. Загрузка файла по полученной ссылке осуществляется через составной POST-запрос с параметром multipart/form-data.

Пример:

curl -v -F 'filename=@/Users/NikitaO/Desktop/File_upl.txt' https://{host}:{port}/sbns-app/upload/{fileId}

Где filename=@/Users/NikitaO/Desktop/File_upl.txt - абсолютный путь к загружаемому файлу, https://{host}:{port}/sbns-app/upload/{fileId} - ссылка, полученная с помощью ресурса /v1/files/upload.

3. Проверка статуса загрузки файла с помощью ресурса /v1/files/upload/{fileId}/state.

Шаги

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

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

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
FileUploadRequest {
digestSignature (Signature, optional)	Электронная подпись файла ,
subType (string)	Тип передаваемого документа/справочника ,
type (string)	Тип задачи
}Signature {
base64Encoded (string)	Значение электронной подписи,
закодированное в Base64 ,
certificateUuid (string)	Уникальный идентификатор сертификата
ключа проверки электронной подписи (UUID)
}

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

{
   "digestSignature":{
      "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
      "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
   },
   "subType":"DebtRegistry",
   "type":"DOC"
}

Для документов поле type будет заполняться значением DOC ('type':'DOC').

Поле subType может заполняться значениями:

Тип документа (subType)	Описание документа
`0401060`	Платежное поручение
`InternalControlStatement`	Ведомость банковского контроля
`CurrControlInfoReq`	Запрос информации валютного контроля
`PayDocCur`	Валютное платежное поручение
`DebtRegistry`	Реестр задолженностей
`GenericLetterToBank`	ПСФ в Банк
`ConfDocInq_138I`	Справка о подтверждающих документах (СПД)
`CurrencyOperationDetails`	Сведения о валютной операции (СВО)
`ContractChangeApplication`	Заявление о внесении изменений в I раздел ВБК (валютный контракт с нерезидентом)
`ContractCloseApplication`	Заявление о переуступке/снятии с учета контракта (кредитного договора)
`CCMessageToBank`	Письмо для целей ВК (в Банк)

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

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

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

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

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

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

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

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

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

Наименование	Описание
FileUploadState {
bankComment (string, optional)	Банковский комментарий к статусу выгрузки файла ,
fileId (string, optional)	Идентификатор файла ,
status (string, optional)	Статус выгрузки файла = [`ATTACHING`, `ATTACH_FINISHED`, `UPLOADING`, `UPLOADED`, `UPLOAD_ERROR`, `ANTIVIRUS_ERROR`, `FILE_TYPE_ERROR`, `FILE_EXTENSION_ERROR`, `MAX_SIZE_ERROR`, `SIGN_ERROR`, `SIGNING`, `SIGNED`, `PARTIALLY_UPLOADED`, `UNKNOWN_STATUS`] stringEnum: `ATTACHING`, `ATTACH_FINISHED`, `UPLOADING`, `UPLOADED`, `UPLOAD_ERROR`, `ANTIVIRUS_ERROR`, `FILE_TYPE_ERROR`, `FILE_EXTENSION_ERROR`, `MAX_SIZE_ERROR`, `SIGN_ERROR`, `SIGNING`, `SIGNED`, `PARTIALLY_UPLOADED`, `UNKNOWN_STATUS`
url (string, optional)	Ссылка для выгрузки файла
}

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

{
   "bankComment":"string",
   "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "status":"ATTACHING",
   "url":"https://185.157.96.20:9443/sbns-app/upload/020b7237-f874-42ce-89bb-02d39d400bcd"
}

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

Ресурс /v1/files/upload/{fileId}/state позволяет получить статус загрузки файла. После успешной загрузки возможна дальнейшая отправка документа с вложенным файлом.

Шаги

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры запроса
fileId (string)	Идентификатор файла

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/files/upload/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6/state'

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

Наименование	Описание
FileUploadState {
bankComment (string, optional)	Банковский комментарий к статусу выгрузки файла,
fileId (string)	Идентификатор файла,
status (string, optional)	Статус выгрузки файла,
url (string, optional)	Ссылка для выгрузки файла

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

{
  "bankComment": "string",
  "fileId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
  "status": "ATTACHING",
  "url": "https://bf.sberbank.ru:9443/sbns-app/upload/020b7237-f874-42ce-89bb-02d39d400bcd"
}

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

Код статуса	Наименование	Состояние
`UPLOADING`	Файл загружается	Промежуточный / Продолжать опрашивать
`ATTACHING`	Прикрепление файла к документу	Промежуточный / Продолжать опрашивать
`UPLOADED`	Файл загружен	Промежуточный / Прекратить опрашивать (Для продолжения загрузки отправьте документ с вложенным файлом)
`ATTACH_FINISHED`	Файл успешно загружен и прикреплен к документу	Статус окончательный / Успешно
`UPLOAD_ERROR`	Ошибка загрузки файла	Статус окончательный / Неуспешно
`ATTACH_ERROR`	Ошибка прикрепления файла к документу	Статус окончательный / Неуспешно
`SIGN_ERROR`	Ошибка при подписи или проверке подписи файла	Статус окончательный / Неуспешно
`SIGNING`	Идет процесс подписи или проверки подписи файла	Промежуточный / Продолжать опрашивать
`PARTIALLY_UPLOADED`	Промежуточная выгрузка	Промежуточный / Продолжать опрашивать
`UNKNOWN_STATUS`	Неизвестный статус выгрузки файла	Промежуточный / Продолжать опрашивать

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

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

Код возврата	Описание кода возврата	Причина возникновения
200 (GET-запроса)	`OK`
201 (POST-запрос)	`CREATED`
	Создан
400	`DESERIALIZATION_FAULT`
	Неверный формат запроса	Неверный формат запроса
	`WORKFLOW_FAULT`
	Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ	Для внешнего сервиса недоступны операции по счету: счет не добавлен в список разрешенных в оферте; внешний сервис заблокирован в СББОЛ; счет указан неверно. Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
	Документ с такими реквизитами уже существует	Документ с такими реквизитами уже существует. Проверка по номер документа в течении года.
	Не указан идентификатор сертификата подписи	Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
	Некорректный формат параметра kid заголовка JWS	Некорректный формат параметра kid заголовка JWS(ожидается UUID)
	`VALIDATION_FAULT`
	Ошибка валидации	Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
401	`UNAUTHORIZED`
	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token.
403	`ACTION_ACCESS_EXCEPTION`
	Операция не может быть выполнена: доступ к ресурсу запрещен	У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404	`DATA_NOT_FOUND_EXCEPTION`
	Не найдено ни одного заранее данного акцепта за указанную дату	Не найдено ни одного заранее данного акцепта за указанную дату
415	`JWS_EXCEPTED`
	В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization	Ошибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500	`UNKNOWN_EXCEPTION`
	Внутренняя ошибка сервера
503	`UNAVAILABLE_RESOURCE_EXCEPTION`
	Сервис временно недоступен	Проводятся технические работы

Большие файлы

Получение ссылки на скачивание файла﻿

Шаги﻿

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

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

Получение статуса файла﻿

Шаги﻿

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

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

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

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

Получение ссылки для загрузки формы﻿

Шаги﻿

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

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

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

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

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

Загрузка файлов﻿

Шаги﻿

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

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

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

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

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

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

Шаги﻿

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

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

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

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

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

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

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

Получение ссылки на скачивание файла

Шаги

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

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

Получение статуса файла

Шаги

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

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

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

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

Получение ссылки для загрузки формы

Шаги

Модель запроса и ответа

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

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

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

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

Загрузка файлов

Шаги

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

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

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

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

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

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

Шаги

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

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

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

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

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

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

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