ym88659208ym87991671
Большие файлы | Документация для разработчиков

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

Обновлено 17 июня 2024

В целях усиления мер обеспечения кибербезопасности при предоставлении информации, относящейся к банковской тайне и содержащей персональные данные Клиента, в соответствии с 152-ФЗ ("О персональных данных") и 149-ФЗ ("Об информации, информационных технологиях и о защите информации") были выполнены доработки в сервисе Sber Api.

Теперь при загрузке/скачивании файлов: Сведения о валютных операциях, Справка о подтверждающих документах, Валютный контракт, Ведомость банковского контроля, Письма для целей валютного контроля, в рамках сервиса «большие файлы» Вам потребуется TLS-сертификат, привязанный к Вашему внешнему сервису.

В связи с этим, если Ваш в запрос на загрузку/выгрузку файла, не зашифрован TLS сертификатом, то возможно будет лишь направить запрос на создание валютного документа, но без загрузки файла.

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

  • Тестовый контур 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"
]
}

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

При скачивании файла с Выпиской стоит ограничение на размер файлов до 40 мб.

Ресурс /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://apifiles.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
Параметры запроса
NumberИдентификатор задачи на скачивание. Вы его получаете с помощью ресорса /v1/statement/print или /v1/statement/files
Указывается в качестве path-параметра в запросе.

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

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

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

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

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

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

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

Код статусаНаименованиеСостояние
PROCESSINGВыписка в процессе формированияПромежуточный / Продолжать опрашивать
EXECUTEDВыписка сформированаКонечный результат (Успешный) / Прекратить опрос
ERRORОшибка формирования выпискиКонечный / Прекратить опрос
EXPIREDСрок действия ссылки истекКонечный / Прекратить опрос

Всем Партнерам при В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.pdf' https://{host}:{port}/sbns-app/upload/{fileId}

Где filename=@/Users/NikitaO/Desktop/File_upl.pdf - абсолютный путь к загружаемому файлу, 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)Формата документа.

Поддерживаемые форматы файлов к валютным документам: pdf, jpeg, jpg, png, tiff, tif, pcx
Максимальный размер файла: 30 мб

Поддерживаемые форматы файлов к остальным документам: doc, docx, xls, xlsx, ppt, pptx, csv, dbf, rtf, txt, pdf, jpg, png, gif, bmp, tiff, zip, rar, arj, xml, jpeg
Максимальный размер файла: 50 мб
}Signature {
base64Encoded (string)Значение электронной подписи,
закодированное в Base64 ,
certificateUuid (string)Уникальный идентификатор сертификата
ключа проверки электронной подписи (UUID)
}

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

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

Поле 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 или /v1/crypto/eio)22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

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

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

При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.

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

Подробнее о работе с ЭЦП в Sber 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://iftfintech.testsbi.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://apifiles.sberbank.ru:9443/sbns-app/upload/020b7237-f874-42ce-89bb-02d39d400bcd"
}

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

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

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

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

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