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

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

Отправка реестра в банк

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

Шаги

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

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

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

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

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

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

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

Header Parameters
Authorization String Access token организации, полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Access token организации, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Body
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) 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.

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

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

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

ccurl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-1'

'https://edupirfintech.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.

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

Header Parameters
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"
}

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

Для передачи ЭП под документом используется массив 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.

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

Header Parameteres
Authorization String Access token организации полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
FileUploadState {
fileIds (Array[string]): Список идентификаторов файлов
}

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

{
   "fileIds":[
      "TwyoRxWisy_YQI6hBHGKZSOAYrzV-LTz0I_Jy5eTMEpTJW4_R_W8y9_2StuKtv8p"
   ]
}

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

Модель ответа соответствует модели ответа /v1/files/upload.

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

Код статуса Наименование Состояние
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 преобразования:

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

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

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

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

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

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