Реестр платежей

Обновлено 29 февраля 2024

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

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

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

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

Шаги

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

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

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

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token организации полученный через SSO Пример: `Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
Параметры тела запроса
FileDownloadStateRequest {
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"
   }
]

Статусы обработки

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

Получение реестра платежей

Ресурс /v1/payments-registry позволяет получить реестр платежей, с целью выявления контрагентов имеющих задолженность.

Реестр платежей — информация о платежах физических лиц, принятых и перечисленных банком на ваш расчётный счёт. Подробнее о реестре платедей рассказали на сайте Банка

Шаги

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

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

Для создания запроса реестра платежей необходимо отправить GET-запрос (/v1/payments-registry), в заголовке запроса необходимо передать авторизационный токен пользователя (Access Token).

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token пользователя, полученный через SSO Пример: `Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1`
Параметры запроса
datetimeLastRequest	String (optional) Дата и время последнего запроса реестров платежей
dateSince	String (optional) Дата начала периода
dateUntil	String (optional) Дата окончания периода
state	String (optional) Статус документа ACCEPTED (если требуется получить документы в статусе Принят) PROCESSED (если требуется получить документы в статусе Обработан)
page	Number (optional) Номер запрашиваемой страницы

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

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/payments-registry
datetimeLastRequest=2019.10.10'T'16%3A00%3A00&dateSince=2019.09.20&
dateUntil=2019.11.20&state=ACCEPTED&page=1'

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

Наименование	Описание
PaymentsRegistryInfo {
_links (Array[Link], optional)	Ссылки на связанные ресурсы,
paymentsRegistry (Array[PaymentsRegistry], optional)	Документы "Реестр платежей"
}Link {
href (string)	Абсолютный или относительный адрес,
rel (string)	Отношение ссылки к текущей сущности (next, prev)
}PaymentsRegistry {
account (string, optional)	Расчетный счет,
bankComment (string, optional)	Атрибуты реестра,
bankStatus (string, optional)	Статус документа,
bfAttachments (Array[BfAttachment], optional)	Данные о файлах, связанных с реестром платежей,
date (string, optional)	Дата создания документа,
externalId (string, optional)	Идентификатор документа,
number (string, optional)	Номер документа,
paymentsRegistry (Array[PaymentsRegistryItem], optional)	Реестры платежей
}BfAttachment {
fileId (string, optional)	Уникальный идентификатор файла,
fileName (string, optional, read only)	Имя файла
}PaymentsRegistryItem {
amount (number, optional)	Сумма,
amountBring (number, optional)	Сумма с комиссией,
dateBegin (string, optional)	Дата начала периода,
dateEnd (string, optional)	Дата окончания периода,
dateLoad (string, optional)	Дата выгрузки реестра,
registryName (string, optional)	Наименование реестра,
uploadedRecords (integer, optional)	Количество платежей
}

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

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "paymentsRegistry":[
      {
         "account":"40802810600000200000",
         "bankComment":"string",
         "bankStatus":"ACCEPTED",
         "bfAttachments":[
            {
               "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
               "fileName":"SB_7718830000_40702810038290010000_T18.txt"
            }
         ],
         "date":"2018-12-31",
         "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "number":"5",
         "paymentsRegistry":[
            {
               "amount":2000.15,
               "amountBring":2100.35,
               "dateBegin":"2018-12-31",
               "dateEnd":"2018-12-31",
               "dateLoad":"2018-12-31",
               "registryName":"EPS39291510642_5018141474.txt",
               "uploadedRecords":10
            }
         ]
      }
   ]
}

Изменение статуса реестра

Ресурс /v1/payments-registry/{externalId}/change-state позволяет изменить статус реестра платежей.

Шаги

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

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

Для изменения статуса реестра платежей необходимо отправить PUT-запрос (/v1/payments-registry/{externalId}/change-state), в заголовке запроса необходимо передать авторизационный токен пользователя (Access Token).

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token пользователя, полученный через SSO Пример: `Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1`
Path Parameters
externalId (String)	Идентификатор документа

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

curl -X POST --header 'Content-Type: application/json' --header '
Accept: application/json'--header 'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1' '
https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/payments-registry/
22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6/change-state'

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

Наименование	Описание
DocState {
bankComment (string, optional, read only)	Банковский комментарий к статусу документа ,
bankStatus (string, optional)	Статус документа ,
channelInfo (string, optional, read only)	Комментарий, специфичный для документа,
полученного по данному каналу
}

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

{
   "bankComment":"Имя реестра: \\EPS30250251003_21052019_623.txt\\r\nДата выгрузки реестра: \"21.05.2019\"\r\nИНН: \"7718837831\"\r\nРасчетный счет: \"40702810038290012055\"\r\nКоличество записей: \"1\"\r\nСумма реестра:\"1000\"\r\nДата начала периода совершения платежей: \"14.07.2017\"\r\nДата окончания периода совершения платежей: \"14.07.2017\"\r\nНомер платежного поручения: \"3682\"\r\n-------------------------------\r\n",
   "bankStatus":"PROCESSED",
   "channelInfo":"string"
}

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

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

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

Реестр платежей

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

Шаги﻿

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

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

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

Шаги﻿

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

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

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

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

Статусы обработки﻿

Получение реестра платежей﻿

Шаги﻿

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

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

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

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

Изменение статуса реестра﻿

Шаги﻿

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

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

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

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

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

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

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

Шаги

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

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

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

Шаги

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

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

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

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

Статусы обработки

Получение реестра платежей

Шаги

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

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

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

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

Изменение статуса реестра

Шаги

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

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

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

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

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

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