ym88659208ym87991671
Реестр задолженности | Документация для разработчиков

Реестр задолженности

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

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

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443

  • Промышленный контур https://fintech.sberbank.ru:9443

Отправка реестра задолженности

Ресурс /v1/debt-registries позволяет отправить реестр задолженности в банк.

Шаги

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

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

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

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

Авторизация

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
DebtRegistry
bankComment (string, optional, read only)Банковский комментарий к статусу документа
bankStatus (string, optional, read only)Статус документа
bfAttachments (Array[BfAttachment], optional)Данные о файлах, связанных с реестром задолженности
date (string)Дата составления документа
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа
externalId (string)Идентификатор документа, присвоенный сервисом (UUID)
number (string, optional)Номер документа
orgName (string)Наименование организации пользователя (сокращенное)
orgTaxNumber (string)ИНН организации пользователя
recordNum (string, optional)Количество записей
BfAttachment
fileId (string, optional)Уникальный идентификатор файла
fileName (string, optional, read only)Имя файла
Signature
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

{
"bankComment":"string",
"bankStatus":"string",
"bfAttachments":[
{
"fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileName":"SB_7718830000_40702810038290010000_T18.txt"
}
],
"date":"2018-12-31",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+1TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"number":"1",
"orgName":"ООО \"Клиент\"",
"orgTaxNumber":"7707083893",
"recordNum":"100"
}

Электронная подпись (ЭП)

Передача ЭП с документом

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

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

Для платежных поручений, создаваемым по собственным счетам можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

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

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

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

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

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

Формат дайджеста

НаименованиеОписание
1externalIdИдентификатор документа, присвоенный сервисом (UUID)
2dateДата составления документа
3recordNumКоличество записей
4fileIdУникальный идентификатор файла
5orgNameНаименование организации пользователя (сокращенное)
6orgTaxNumberИНН пользователя

Пример дайджеста

externalId=7beb4b73-ba9d-49e9-9b6d-d9a169ad2638
date=2018-02-20
recordNum=2
fileId=020b7237-f874-42ce-89bb-02d39d400bcd
orgName=ООО Ромашка
orgTaxNumber=7707012345

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

Ресурс /v1/debt-registries/{externalId}/state позволяет получить статус ранее отправленного реестра задолженности.

Шаги

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

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

Авторизация

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

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

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

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

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

ccurl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/debt-registries/c76fb018-27c9-43f7-a751-62646eda7e1a-1/state'

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

НаименованиеОписание
DocState
bankComment (string, optional, read only)Банковский комментарий к статусу документа
bankStatus (string, optional)Статус документа
receiptStatus (string)Статус регистрации дохода самозанятого в ФНС (чек)

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

{
"bankStatus": "CREATED",
"bankComment": null,
"receiptStatus": "FINISHED"
}

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

СтатусЗначениеСостояние
CREATEDСозданПромежуточный / Продолжать опрашивать
DELETEDУдаленКонечный / Прекратить опрос
PARTSIGNEDЧастично подписанПромежуточный / Продолжать опрашивать
SIGNEDПодписанПромежуточный / Продолжать опрашивать
INVALIDEDSЭП/АСП не вернаКонечный / Прекратить опрос
REFUSEDBYBANKОтвергнут БанкомКонечный / Прекратить опрос
EXPORTEDВыгруженПромежуточный / Продолжать опрашивать
IMPLEMENTEDИсполненКонечный / Прекратить опрос
REFUSEDBYABSОтказан АБСКонечный / Прекратить опрос
DELIVEREDДоставленПромежуточный / Продолжать опрашивать
PARTIALLY_DOWNLOADEDЧастично загруженПромежуточный / Продолжать опрашивать

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

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

Сценарий:

  1. Получение ссылки с помощью ресурса /v1/files/upload.
  2. Загрузка файла по полученной ссылке (В АС пользователю необходимо выбрать файл для загрузки (см. https://www.php.net/manual/ru/features.file-upload.post-method.php), далее АС отправляет POST-запрос на адрес, полученный в /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+kJ2IQrcxVdvDTep6xjsm1TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
},
"subType":"DebtRegistry",
"type":"DOC"
}

Электронная подпись (ЭП)

Передача ЭП с документом

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

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

Подписание запроса транспортной подписью

Content-Type может содержать одно из двух значений:

1. application/json – запрос без подписи.

2. application/jose – запрос, подписанный транспортной подписью.

если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

  • Заголовка (Header),

  • JSON-документа с реквизитным составом платежного поручения (Payload),

  • Подписи запроса (Signature),

Формирование компактной сериализации JWS.

JWS формируется из трех составляющих:

Base64Url(Header) || ’.’ || Base64Url(Payload) || ’.’ || Base64Url(Signature)

Signature - это подпись данных приватной частью ключевой пары пользователя (используется приватный ключ парный сертификату пользователя с UUID, указанному в Заголовке (Header) в параметре kid). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg, в данном случае gost34.10-2012, и вычисляется от исходных данных: Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

Следует отметить, что при кодировании JWS используется преобразование Base64Url, отличающееся от Base64 преобразования.
Условно это преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование BASE64URL, отличается от BASE64 преобразования:

BASE64URLBASE64
- (minus)+
_ (underline)/
  • В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

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

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