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

Обновлено 22 ноября 2024

Информация о сервисе

Сервис «Большие файлы» — ваш помощник в работе с документами.

С помощью сервиса вы сможете загружать документы в банк для различных целей, например:

предоставление документов в валютный контроль Банка;
экспорт файлов с выписками по счетам для импорта в другие системы;
отправка в Банк иных документов по разным вопросам.

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

Авторизация

Все запросы в Sber API выполняются от имени конкретного пользователя СберБизнес, в том числе при интеграции для работы с информацией только по собственной компании. Запросы в Sber API в заголовке (Header) содержат параметр - Authorization. В нем требуется передавать токен доступа (access_token) пользователя. Получение токена доступа осуществляется с помощью сервиса СберБизнес ID. Подробно о подключении и работе сервиса авторизации рассказали в соответствующем разделе документации.

При интеграции по собственной компании потребуется выбрать одного пользователя СберБизнес и пройти им авторизацию через СберБизнес ID единоразово. В дальнейшем вам потребуется своевременно обновлять токен доступа при помощи токена обновления - обновить токен доступа.

Варианты реализации

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

Сценарии описали общие, для более легкого восприятия информации описания работы с продуктом Зарплатный проект в Sber API.

Можно использовать разные триггеры запуска того или иного сценария - действия пользователя, регламентный запуск по времени, наступление определенных событий и другие варианты.

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

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

Мы рекомендуем использовать сценарий с автоматическим запуском в других сценариях.

Представим, что ваша Платформа предлагает Пользователю создать запрос на постановку контракта на учет через форму в пользовательском интерфейсе (UI). В этой форме Пользователь загружает документы контракта.

Когда файлы загружаются в UI Платформы, и Пользователь подтверждает отправку запроса, автоматически запускается соответствующий сценарий для каждого файла.

Шаги

Получить ссылку для загрузки
Загрузить файл
Получить статус загрузки

Участники usecase

Платформа - любой web-ресурс (интернет-магазин, облачный сервис, мобильное приложение и т.д.) либо ваша внутренняя система (ERP, учетная система и др.), которую используют Пользователи
Sber API - в контексте usecase представляет из себя запросы и ресурсы Sber API, к которым обращается Платформа

Предварительные условия

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

Результат применения

Файл загружен в Банк
Платформа получила ссылку на файл в системе Банка

Используемые запросы

№	Точка вызова	Описание	Операция в scope	Шаг в схеме
1	`/fintech/api/v1/files/upload`	Запрос ссылки на загрузку файла в Банк	FILES	1. Получить ссылку для загрузки
2	`/ic/sso/api/v2/oauth/token`	Обновление токена доступа	openid	1. Получить ссылку для загрузки
3	`/fintech/api/v1/files/upload/{fileId}/state`	Получение статуса загрузки файла в Банк	FILES	3. Получить статус загрузки

Скачивание ранее загруженных файлов

Этот сценарий позволяет скачивать ранее загруженные в Банк документы.

Шаги

Запросить подготовку файла для скачивания
Получить статус загрузки
Скачать файл

Участники usecase

Пользователь - сотрудник вашей компании либо представитель ЮЛ/ИП, от лица которого он работает в рамках вашего сервиса (Платформа)
Платформа - любой web-ресурс (интернет-магазин, облачный сервис, мобильное приложение и т.д.) либо ваша внутренняя система (ERP, учетная система и др.), которую используют Пользователи
Sber API - в контексте usecase представляет из себя запросы и ресурсы Sber API, к которым обращается Платформа

Предварительные условия

Запуск доступен только при реализации хотя бы 1 раз сценария "Загрузка файлов в Банк"
Пользователь имеет пользовательский профиль в СберБизнес своей компании
Пользователь находится в пространстве Платформы
Пользователь прошел авторизацию с помощью СберБизнес ID

Результат применения

Файл скачен в пространство Платформы
Платформа предоставила файл Пользователю в своем UI

Используемые запросы

№	Точка вызова	Описание	Операция в scope	Шаг в схеме
1	`/fintech/api/v1/files/download`	Запрос ссылки на выгрузку файлов	FILES	1. Запросить подготовку файла для скачивания
2	`/ic/sso/api/v2/oauth/token`	Обновление токена доступа	openid	1. Запросить подготовку файла для скачивания
3	`/fintech/api/v1/files/downloadState`	Получение статусов выгрузки файлов	FILES	2. Получить статус загрузки

Доступные форматы файлов для загрузки в Банк

Сервис является вспомогательным при работе в сценариях других сервисов Sber API.

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

ВЭД
Переписка с банком

subType:

InternalControlStatement - Ведомость банковского контроля (ВБК)

ConfDocInq_138I - Справка о подтверждающих документах (СПД)

CurrencyOperationDetails - Сведения о валютной операции (СВО)

CCMessageToBank - Письмо для целей ВК (в банк)

Размерность файла - до 30 Мбайт

Форматы файлов - pdf, jpeg, jpg, png, tiff, tif, pcx, txt, doc, docx, rar, zip

subType:

GenericLetterToBank - Письмо свободного формата

Размерность файла - до 50 Мбайт

Форматы файлов - pdf, jpeg, jpg, png, tiff, tif, pcx, txt, doc, docx, rar, zip, xls, xlsx

Загрузка файла в Банк

Загрузка файла по полученной ссылке осуществляется через составной 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} - ссылка, полученная с помощью ресурса /fintech/api/v1/files/upload/.

Запрос ссылки на загрузку файла в Банк

/fintech/api/v1/files/upload

Запрос позволяет получить ссылку для загрузки вашего файла на платформу Банка.

Для получения статуса необходимо отправить POST-запрос /fintech/api/v1/files/upload с токеном доступа (access_token) пользователя в параметре Authorization заголовка и параметрами загружаемого файла в теле.

В параметре scope ссылки авторизации пользователя должен быть указан сервис FILES для получения доступа к этому запросу.

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

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

Request

/fintech/api/v1/files/upload

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
BODY
FileUploadRequest {
digestSignatures	array[Signature]	array		optional	Электронные подписи по дайджесту документа. О подписании дайджеста документа подробно рассказали в соответствующем разделе документации,
subType	string	string	^[a-zA-Z0-9]+$ Актуальные значения доступны по ссылке.	required	Тип передаваемого документа/справочника,
type	string	string		required	Формата документа
}
Signature {
base64Encoded	string	base64	^[a-zA-Z0-9]+$	required	Значение электронной подписи (ЭП), закодированное в Base64,
certificateuuid	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Уникальный идентификатор сертификата ключа проверки электронной подписи
}

POST /fintech/api/v1/files/upload HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
 
{
   "digestSignature":{
      "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
      "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
   },
   "subType":"DebtRegistry",
   "type":"PDF"
}

Responses

200 (OK)

Модель
Пример

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "DESERIALIZATION_FAULT",
    "referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
    "message": "Неверный формат запроса",
    "checks": [
        {
            "level": "ERROR",
            "message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
            "fields": [
                "digestSignatures"
            ]
        }
    ],
    "fieldNames": [
        "digestSignatures"
    ]
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
	Некорректное значение Access Token	Указан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `FILES`. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Получение статуса загрузки файла в Банк

/fintech/api/v1/files/upload/{fileId}/state

Запрос позволяет получить статус загрузки вашего файла на платформу Банка.

Для получения статуса необходимо отправить GET-запрос /fintech/api/v1/files/upload/{fileId}/state с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатором (fileId) документа в path-параметре.

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

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

Request

/fintech/api/v1/files/upload/{fileId}/state

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
PATH PARAMETER
fileId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Идентификатор файла, полученный в рамках запроса `/fintech/api/v1/files/upload`

GET /fintech/api/v1/files/upload/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6/state HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678

Responses

200 (OK)

Модель
Пример

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "DESERIALIZATION_FAULT",
    "referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
    "message": "Неверный формат запроса",
    "checks": [
        {
            "level": "ERROR",
            "message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
            "fields": [
                "digestSignatures"
            ]
        }
    ],
    "fieldNames": [
        "digestSignatures"
    ]
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
	Некорректное значение Access Token	Указан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `FILES`. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Статусы загрузки документа

bankStatus (string)

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

Запрос ссылки на выгрузку файлов

/fintech/api/v1/files/download

Запрос позволяет запустить процесс подготовки ссылки для скачивания ранее загруженного в Банк файла.

Для запуска процесса подготовки ссылки необходимо отправить POST-запрос /fintech/api/v1/files/download с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификаторами файлов (fileId).

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

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

Request

/fintech/api/v1/files/download

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
BODY
FileDownloadRequest {
fileIds	array[string]	array		required	Список идентификаторов файлов
}

POST /fintech/api/v1/files/download HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678

{
  "fileIds": [
    "string"
  ]
}

Responses

200 (OK)

Модель
Пример

Наименование	Тип	Обязательность	Описание
Отсутствует

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "DESERIALIZATION_FAULT",
    "referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
    "message": "Неверный формат запроса",
    "checks": [
        {
            "level": "ERROR",
            "message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
            "fields": [
                "digestSignatures"
            ]
        }
    ],
    "fieldNames": [
        "digestSignatures"
    ]
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
	Некорректное значение Access Token	Указан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `FILES`. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Запрос ссылки на выгрузку файлов

/fintech/api/v1/files/downloadState

Запрос позволяет получить статус о готовности файла для скачивания.

Для получения статуса необходимо отправить POST-запрос /fintech/api/v1/files/downloadState с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификаторами файлов (fileId).

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

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

Request

/fintech/api/v1/files/downloadState

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
BODY
FileDownloadRequest {
fileIds	array[string]	array		required	Список идентификаторов файлов
}

POST /fintech/api/v1/files/download HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678

{
  "fileIds": [
    "string"
  ]
}

Responses

200 (OK)

Модель
Пример

Наименование	Тип	Обязательность	Описание
FileDownloadStateRequest [
FileDownloadStateRequest 1	array[FileDownloadStateRequest 1]	required
]
FileDownloadStateRequest 1 {
bankComment	string	optional	Банковский комментарий к статусу загрузки файла
fileId	string	optional	Идентификатор файла,
status	string	optional	Статус загрузки файла,
url	string	optional	Ссылка для загрузки файла
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[
  {
    "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"
  }
]

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "DESERIALIZATION_FAULT",
    "referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
    "message": "Неверный формат запроса",
    "checks": [
        {
            "level": "ERROR",
            "message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
            "fields": [
                "digestSignatures"
            ]
        }
    ],
    "fieldNames": [
        "digestSignatures"
    ]
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
	Некорректное значение Access Token	Указан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `FILES`. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Статусы формирования ссылки

bankStatus (string)

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

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

/fintech/api/v1/files/tasks-for-download/{taskId}

Запрос позволяет получить ссылку для загрузки печатной формы файла выписки по ранее сформированной задаче.

Для получения ссылки на загрузку необходимо отправить GET-запрос /fintech/api/v1/files/tasks-for-download/{taskId} с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатором задачи (taskId) в path-параметре.

После получения ответа 200 OK со статусом готовности файла к скачиванию EXECUTED, платформа осуществляет скачивание файла по предоставленному URL.

Обратите внимание, что для успешного выполнения этого запроса требуется наличие установленного TLS-сертификата на платформе.

Загруженный файл сохраните в базе данных платформы. Это действие позволит организовать эффективное хранение и управление доступом к файлам.

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

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

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

Request

/fintech/api/v1/files/tasks-for-download/{taskId}

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
PATH PARAMETER
taskId	string	string	^.+$	required	Идентификатор задачи на скачивание. Вы его получаете с помощью запросов `/fintech/api/v1/statement/print` или `/fintech/api/v1/statement/files`

GET /fintech/api/v1/files/tasks-for-download/247258305314631 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678

Responses

200 (OK)

Модель
Пример

Наименование	Тип	Обязательность	Описание
TaskForDownload {
filename	string	optional	Имя файла
id	string	optional	Идентификатор файла,
state	string	optional	Статус загрузки файла,
url	string	optional	Ссылка для загрузки файла
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

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

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "DESERIALIZATION_FAULT",
    "referenceId": "4a0e6754-ad22-4d7d-ac82-810afd08b5b2",
    "message": "Неверный формат запроса",
    "checks": [
        {
            "level": "ERROR",
            "message": "Cannot deserialize instance of `java.util.ArrayList<Signature>` out of START_OBJECT token",
            "fields": [
                "digestSignatures"
            ]
        }
    ],
    "fieldNames": [
        "digestSignatures"
    ]
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
	Некорректное значение Access Token	Указан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `FILES`. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Статусы готовности к загрузке

bankStatus (string)

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

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

Информация о сервисе﻿

Авторизация﻿

Варианты реализации﻿

Доступные форматы файлов для загрузки в Банк﻿

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

Запрос ссылки на загрузку файла в Банк﻿

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

Статусы загрузки документа﻿

Запрос ссылки на выгрузку файлов﻿

Запрос ссылки на выгрузку файлов﻿

Статусы формирования ссылки﻿

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

Статусы готовности к загрузке﻿

Информация о сервисе

Авторизация

Варианты реализации

Доступные форматы файлов для загрузки в Банк

Загрузка файла в Банк

Запрос ссылки на загрузку файла в Банк

Получение статуса загрузки файла в Банк

Статусы загрузки документа

Запрос ссылки на выгрузку файлов

Запрос ссылки на выгрузку файлов

Статусы формирования ссылки

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

Статусы готовности к загрузке