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

Обновлено 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.

Пример отправляемого файла реестра задолженности - DEBTREGISTRY_EXAMPLE.txt.

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

Наименование	Описание
Параметры заголовка
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+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "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` или `/v1/crypto/eio)`	22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

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

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

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

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

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

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

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

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)	Идентификатор документа, присвоенный пользователем

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

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

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

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

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

application/json – запрос без подписи
application/jose – запрос, подписанный транспортной подписью

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

JWS состоит из трёх частей:

Заголовок (Header) - определяет алгоритм подписи и тип токена
Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
Электронная подпись (Signature) - вычисляется с использованием приватного ключа клиента

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

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

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

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

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

При кодировании JWS используется преобразование Base64Url. Преобразование можно представить следующим образом:

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

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

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

В Base64Url не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

BASE64URL	BASE64
- (minus)	+
_ (underline)	/

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

Код возврата	Описание кода возврата	Причина возникновения
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`
	Сервис временно недоступен	Проводятся технические работы

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

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

Шаги﻿

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

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

Передача электронной подписи﻿

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

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

Получение статуса реестра задолженности﻿

Шаги﻿

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

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

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

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

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

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

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

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

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

Шаги

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

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

Передача электронной подписи

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

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

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

Шаги

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

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

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

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

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

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

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

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