ym88659208ym87991671
Большие файлы | Документация SmartMarket
Skip to main content

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

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

  • Тестовый контур https://edupirfintech.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": [
"TwyoRxWisy_YQI6hBHGKZSOAYrzV-LTz0I_Jy5eTMEpTJW4_R_W8y9_2StuKtv8p"
]
}

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

Ресурс /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Неизвестный статус загрузки файлаПромежуточный / Продолжать опрашивать

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

С помощью ресурса /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
Создан
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
Операция не может быть выполнена: доступ к ресурсу запрещенУ пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
404DATA_NOT_FOUND_EXCEPTION
Не найдено ни одного заранее данного акцепта за указанную датуНе найдено ни одного заранее данного акцепта за указанную дату
415JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact SerializationОшибка возникает, если в настройках внешних сервисов выставлен флаг «Требуется подпись для внешнего сервиса»
500UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступенПроводятся технические работы
Обновлено 27 апреля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней