ym88659208ym87991671
Справка о подтверждающих документах | Документация для разработчиков

Справка о подтверждающих документах

Обновлено 17 июня 2024

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

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

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

Ресурс /v1/confirmatory-documents-inquiries

Ресурс позволяет создавать документ «Справка о подтверждающих документах» (далее СПД).

Шаги

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

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

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

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

5. Получить документ.

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

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

Модель запроса и ответа

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
ConfirmatoryDocumentsInquiry
acceptDate (string, optional, read only)Дата представления в банк
authPersonName (string, optional)ФИО ответственного лица
authPersonTelfax (string, optional)Телефон ответственного лица
bankComment (string, optional, read only)Банковский комментарий к статусу документа
bankStatus (string, optional, read only)Статус документа
bfAttachments (Array[BfAttachment], optional)Приложенные к документу: отсканированные образы-вложения - для АС БФ
customerBankBIC (string, optional)БИК банка клиента
customerINN (string)ИНН резидента
customerName (string)Наименование резидента
customerOKPO (string)ОКПО резидента
date (string)Дата составления документа
dealDate (string)Дата справки
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа
docs (Array[ConfirmatoryDocumentsInquiryDoc], optional)Документы, включенные в справку
executorEmployeeName (string, optional, read only)Должность ответственного лица
executorName (string, optional, read only)Подпись ответственного лица
externalId (string)Идентификатор документа, присвоенный партнером (UUID)
failReasons (Array[FailReason], optional, read only)Причины отказа
number (string, optional)Номер документа
psNumber (string, optional)Уникальный номер контракта (кредитного договора)
returnReason1 (boolean, optional, read only)Флаг причины возврата 16.1.1
returnReason1Comment (string, optional, read only)Комментарий причины возврата 16.1.1
returnReason2 (boolean, optional, read only)Флаг причины возврата 16.1.3
returnReason2Comment (string, optional, read only)Комментарий причины возврата 16.1.3
returnReason3 (boolean, optional, read only)Флаг причины возврата 16.1.4
returnReason3Comment (string, optional, read only)Комментарий причины возврата 16.1.4
returnReason4 (boolean, optional, read only)Флаг причины возврата 16.1.5
returnReason4Comment (string, optional, read only)Комментарий причины возврата 16.1.5
valueDate (string, optional, read only)Дата принятия/возврата
BfAttachment
fileId (string, optional)Уникальный идентификатор файла
fileName (string, optional, read only)Имя файла
Signature
base64Encoded (string)Значение электронной подписи, закодированное в Base64
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
ConfirmatoryDocumentsInquiryDoc
addInfo (string, optional)Дополнительная информация
confDocDate (string, optional)Дата подтверждающего документа
confDocNumber (string, optional)Номер подтверждающего документа
contractSum (AmountCurrency, optional)Сумма и валюта контракта
contractSumDel (number, optional)Сумма, соответствующая признаку поставки 2 или 3, в валюте цены контракта (кредитного договора)
correctionDate (string, optional)Дата корректировки
correctionNumber (integer, optional)Номер корректировки
countryCode (string, optional)Код страны грузополучателя (грузоотправителя)
countryName (string, optional)Наименование страны грузополучателя (грузоотправителя)
docCode (string)Код вида документа
docName (string)Наименование вида документа
docSum (AmountCurrency)Сумма и валюта документа
docSumDel (number, optional)Сумма, соответствующая признаку поставки 2 или 3, в валюте документа
expectedLife (string, optional)Ожидаемый срок
hasConfDocNumber (boolean)Признак присутствия номера подтверждающего документа
ordinalNumber (integer)Порядковый номер строки в справке
supplyFeature (string, optional)Признак поставки = ['1', '2', '3', '4']stringEnum
FailReason
docField (string, optional)Поле документа
reasonComment (string, optional)Правило заполнения/замечания
reasonId (string, optional)Код причины отказа
returnComment (string, optional)Комментарий
AmountCurrency
amount (number)Сумма
currencyCode (string)Цифровой код валюты
currencyName (string)Буквенный ISO-код валюты

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

{
"acceptDate":"2018-12-31",
"authPersonName":"Иванов Иван Иванович",
"authPersonTelfax":"4955005550",
"bankComment":"string",
"bankStatus":"string",
"bfAttachments":[
{
"fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileName":"SB_7718830000_40702810038290010000_T18.txt"
}
],
"customerBankBIC":"044525225",
"customerINN":"7707083893",
"customerName":"Общество с ограниченной ответственностью \"Клиент\"",
"customerOKPO":"222221001",
"date":"2018-12-31",
"dealDate":"2018-12-31",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"docs":[
{
"addInfo":"Дополнительная информация",
"confDocDate":"2018-12-31",
"confDocNumber":"123",
"contractSum":{
"amount":1.01,
"currencyCode":"840",
"currencyName":"USD"
},
"contractSumDel":1.01,
"correctionDate":"2018-12-31",
"correctionNumber":1,
"countryCode":"643",
"countryName":"РОССИЯ",
"docCode":"03_3",
"docName":"03_3 О передаче резидентом на территории Российской Федерации товаров и оказании услуг нерезиденту по контрактам, указанным в подпункте 5.1.2 пункта 5.1 настоящей Инструкции",
"docSum":{
"amount":1.01,
"currencyCode":"840",
"currencyName":"USD"
},
"docSumDel":1.01,
"expectedLife":"2018-12-31",
"hasConfDocNumber":false,
"ordinalNumber":1,
"supplyFeature":"1"
}
],
"executorEmployeeName":"Ответственный исполнитель банка",
"executorName":"Иванов Иван Иванович",
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"failReasons":[
{
"docField":"Номер контракта",
"reasonComment":"Указан неверно",
"reasonId":"PS_REST_REJ_PART_2-9",
"returnComment":"Отказ проверки"
}
],
"number":"1",
"psNumber":"120123A0/1234/GU23/1/2",
"returnReason1":false,
"returnReason1Comment":"Ошибка",
"returnReason2":false,
"returnReason2Comment":"Ошибка",
"returnReason3":false,
"returnReason3Comment":"Ошибка",
"returnReason4":false,
"returnReason4Comment":"Ошибка",
"valueDate":"2018-12-31"
}

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

Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:

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

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

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

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

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

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

Подробнее о работе с ЭЦП в Sber API можно ознакомиться в соответствующем разделе документации.

Алгоритм сортировки дайджеста

Теги дайджеста должны быть отсортированы по алфавиту, в формировании дайджеста не участвует поле number. В таблице BfAttachments строки сортируются во возрастанию поля fileId. В таблице Docs строки сортируются по возрастанию поля ordinalNumber.

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

Наименование поляОписание поляПример
authPersonNameФИО уполномоченного сотрудника организации клиентаИванов Иван Иванович
authPersonTelfaxНомер телефона, факса уполномоченного сотрудника организации клиента4955005550
customerBankBicБИК банка клиента44525225
customerINNИНН клиента2406877205
customerNameНаименование резидентаОбщество с ограниченной ответственностью "Клиент"
customerOKPOОКПО клиента3698203661
dateДата документа20.05.2019
dealDateСправка от (дата справки)20.05.2019
externalIdИдентификатор документа в организации-партнере14d62475-e8da-4f24-bcc7-68e4add64131
psNumberУникальный номер контракта (Кредитного договора)11111111/0011/0000/1
TABLES
Table=Docs
addInfoПримечания по данной строкеДополнительная информация
confDocDateДата подтверждающего документа20.05.2019
confDocNumberНомер подтверждающего документа123
contractSumDelСумма, соответствующая признаку поставки 2 или 3, в валюте цены контракта (кредитного договора)01.янв
correctionDateДата корректируемой СПД20.05.2019
correctionNumberНомер корректировки1
countryCodeКод страны826
countryNameНаименование страныСОЕДИНЕННОЕ КОРОЛЕВСТВО
docCodeКод вида документа03_3
docNameНаименование вида документаО передаче резидентом на территории Российской Федерации товаров и оказании услуг нерезиденту по контрактам, указанным в подпункте 5.1.2 пункта 5.1 настоящей Инструкции
docSum.amountСумма04.март
docSum.currencyCodeЦифровой код валюты840
docSum.currencyNameТрехбуквенный код валюты ISO-код валютыUSD
docSumDelСумма, соответствующая признаку поставки 2 или 3, в валюте документа02.февр
expectedLifeОжидаемый срок20.05.2019
hasConfDocNumberПризнак номера документа:true
true - документ имеет номер;
false - документ без номера
ordinalNumberПорядковый номер строки в справке15
supplyFeatureПризнак поставки2
contractSum.amountСумма04.март
contractSum.currencyCodeЦифровой код валюты840
contractSum.currencyNameТрехбуквенный код валюты ISO-код валютыUSD
#Разделитель строк таблицы
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов08ba3412-118a-4f4d-be23-e93f81d58fdc
#Разделитель строк таблицы

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

authPersonName=Иванов Иван Иванович
authPersonTelfax=4955005550
customerBankBic=044525225
customerBankName=ПАО "СБЕРБАНК"
customerINN=2406877205
customerName=Общество с ограниченной ответственностью "Клиент"
customerOKPO=3698203661
date=2019-05-20
dealDate=2019-05-20
externalId=14d62475-e8da-4f24-bcc7-68e4add64131
psNumber=11111111/0011/0000/1
TABLES
Table=Docs
addInfo=Примечание
confDocDate=2019-05-20
confDocNumber=123
contractSum.amount=4.03
contractSum.currencyCode=840
contractSum.currencyName=USD
contractSumDel=1.01
correctionDate=2019-05-20
countryCode=826
countryName=СОЕДИНЕННОЕ КОРОЛЕВСТВО
docCode=03_3
docName=О передаче резидентом на территории Российской Федерации товаров и оказании услуг нерезиденту по контрактам,
указанным в подпункте 5.1.2 пункта 5.1 настоящей Инструкции
docSum.amount=4.03
docSum.currencyCode=840
docSum.currencyName=USD
docSumDel=2.02
expectedLife=2019-05-20
hasConfDocNumber=1
ordinalNumber=0
supplyFeature=2
#
addInfo=Примечание
confDocDate=2019-05-20
confDocNumber=135
contractSum.amount=4.03
contractSum.currencyCode=840
contractSum.currencyName=USD
contractSumDel=2.02
correctionDate=2019-05-20
correctionNumber=1
countryCode=826
countryName=СОЕДИНЕННОЕ КОРОЛЕВСТВО
docCode=03_3
docName=О передаче резидентом на территории Российской Федерации товаров и оказании услуг нерезиденту по контрактам,
docSum.amount=8.08
docSum.currencyCode=840
docSum.currencyName=USD
docSumDel=2.02
expectedLife=2019-05-20
hasConfDocNumber=true
ordinalNumber=2
supplyFeature=3
#Table=BfAttachments
fileId=3e7333db-dbb4-4bc1-a2e2-49cbc5ab834d
#
fileId=e0687514-2c3d-471d-917c-f3e8f9fde1e0
#

Ресурс /v1/confirmatory-documents-inquiries/{externalId}/state

Ресурс позволяет получить статус ранее отправленного электронного документа СПД.

Шаги

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

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/confirmatory-documents-inquiries/
22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6/state'

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

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

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

{
"bankStatus": "DELIVERED",
"bankComment": null,
"channelInfo": "string"
}

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

СтатусЗначениеСостояние
ACCEPTEDПринятПромежуточный / Продолжать опрашивать
CHECKERRORОшибка контроляКонечный / Прекратить опрос
CREATEDСозданДокумент не отправлен в банк, требуется подпись
PARTSIGNEDЧастично подписанДокумент не отправлен в банк, требуется подпись
SIGNEDПодписанДокумент не отправлен в банк, требуется отправка
DELIVEREDДоставленПромежуточный / Продолжать опрашивать
PROCESSINGВ обработкеПромежуточный / Продолжать опрашивать
TRIED_BY_CFEПроверяется ВКПромежуточный / Продолжать опрашивать
ACCEPTED_BY_CFEПринят ВККонечный / Прекратить опрос
RECALLОтозванКонечный / Прекратить опрос
INVALIDEDSЭП/АСП не вернаКонечный / Прекратить опрос
REQUISITEERRORОшибка реквизитовКонечный / Прекратить опрос
REFUSEDBYBANKОтвергнут БанкомКонечный / Прекратить опрос
REFUSEDBYABSОтказан АБСКонечный / Прекратить опрос
REFUSED_BY_CFEОтказан ВККонечный / Прекратить опрос
EXPORTEDВыгруженПромежуточный / Продолжать опрашивать
ACCEPTED_BY_ABSПринят АБСПромежуточный / Продолжать опрашивать

Ресурс /v1/confirmatory-documents-inquiries/{externalId}

Ресурс позволяет получить ранее отправленный электронный документ СПД с информацией о причинах возврата\отказа.

Шаги

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

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

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

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

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

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

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

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/confirmatory-documents-inquiries/
22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6'

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

Модель ответа соответствует модели запроса и ответа /v1/confirmatory-documents-inquiries.

Ресурс /v1/bank-control-statements/{externalId}/linked-docs-list

Ресурс позволяет получить, связанные с валютным контрактом (кредитным контрактом), СПД по собственной/дочерней организации.

Шаги

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

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

Для получения документа необходимо отправить GET-запрос (/v1/bank-control-statements/{externalId}/linked-docs-list), в котором необходимо передать авторизационный токен к данным собственной/дочерней организации (Access Token) и внешний идентификатор документа (externalId) и тип возвращаемых документов docType (СПД). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token организации полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId (String)Идентификатор документа, присвоенный сервисом
docType (String)Тип требуемого к возврату валютного документа
ConfDocInq_138I - СПД

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

curl -X GET --header 'Accept: /' --header 'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/bank-control-statements/69ec14cf-48bf-4119-804b49bedc72047d/linked-docs-list?docType=ConfDocInq_138I'

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

externalId

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

[
"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"26a6dd81-103a-4d3a-8e9b-0ba4b527f5f8",
"12a6dd31-103a-4d3a-8e9b-0ba4b527f5f4"
]

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

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

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

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

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

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

  1. Заголовок (Header) - определяет алгоритм подписи и тип токена
  2. Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
  3. Электронная подпись (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 преобразования:

BASE64URLBASE64
- (minus)+
_ (underline)/

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

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