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

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

Ресурс /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) ИНН резидента
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) 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

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

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

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

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

Формирование электронной подписи (ГОСТ 2012)

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

Теги дайджеста должны быть отсортированы по алфавиту, в формировании дайджеста не участвует поле 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-ов больших файлов
fileId UUID больших файлов 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
#

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

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

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

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

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