Валютный контракт в Банк

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

Шаги:

  1. Получить AccessToken.
  2. Сформировать ЭП
  3. Отправить запрос, соответствующий бизнес-кейсу:

    3.1 Заявление на регистрацию валютного контракта без указания информации о контракте

    3.2 Заявление на регистрацию валютного контракта с указанием информации о контракте

    3.3 Предоставление информации об экспортном контракте

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

Ресурс /v1/bank-control-statements/reg-curr-contracts

Ресурс позволяет создать заявление на регистрацию валютного контракта (ВК). Для создания запроса на регистрацию валютного контракта необходимо отправить POST-запрос (/v1/bank-control-statements/reg-curr-contracts), в котором передать авторизационный токен к данным клиента (Access Token) и реквизиты запроса на регистрацию валютного контракта. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

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

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

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

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

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

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

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

ICS_CONTRACT_REGISTRATION - указывается при регистрации контракта, когда необходимо отправить сам контракт во вложении, чтобы поставить его на учет. ICS_CONTRACT_INFORMATION - заполняется в случае, если необходимо предоставить только информацию о контракте, для отправки СВО, к примеру (см. 181-И). Далее по истечению определенного срока (указано в 181-И) необходимо предоставить и сам контракт, используя метод досыла контракта - Ресурс /v1/bank-control-statements/send-curr-contracts.

Заявление на регистрацию валютного контракта без указания информации о контракте

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
CurrContract {
bankControlStatementInfo (BankControlStatementInfo) Информация о ведомости банковского контроля (ВБК в банк),
contractDate (string) Дата контракта,
date (string) Дата составления документа. Формат YYYY-MM-DD,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа. Для заполнения использовать справочник (Справочник стран Country),
number (string, optional) Номер документа, 7 символов,
}BankControlStatementInfo {
bankCommentAuthor (string, optional, read only) Автор комментария,
bfAttachments (Array[BfAttachment], optional) Прикрепленные большие файлы. Заполняется обязательно, если creationMode=ICS_CONTRACT_REGISTRATION,
creationMode (string) Режим создания ВБК = [ICS_CONTRACT_INFORMATION, ICS_CONTRACT_REGISTRATION]
stringEnum: "ICS_CONTRACT_INFORMATION", "ICS_CONTRACT_REGISTRATION",
externalId (string) Идентификатор документа в организации-партнере,
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID),
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла,
fileName (string, optional, read only) Имя файла

Пример

{
   "bankControlStatementInfo":{
      "bfAttachments":[
         {
            "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
            "fileName":"SB_7718830000_40702810038290010000_T18.txt"
         }
      ],
      "creationMode":"ICS_CONTRACT_REGISTRATION",
      "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
   },
   "contractDate":"2018-12-31",
   "date":"2018-12-31",
   "number":"123"
}

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

Теги дайджеста должны быть отсортированы по алфавиту. В таблице bfAttachments UUID-ы сортируются по возрастанию.
В дайджесте не указываются значения Number и блок linkedDocs.

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

Наименование поля Описание поля Пример
bankControlStatementInfo.creationMode Режим создания ВБК ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.externalId Идентификатор документа в организации-партнере 550e8400-e29b-41d4-a716-446655440000
contractDate Дата договора 16.05.2019
date Дата создания документа по местному времени 16.05.2019
TABLES Значение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachments Значение указывается при наличии UUID-ов больших файлов
fileId UUID больших файлов 31663ef5-7975-4016-b0f3-f1d70a4e9c22
# Разделитель значений UUID-ов больших файлов
fileId UUID больших файлов 51663ef5-7975-4016-b0f3-f1d70a4e9c22
# Разделитель значений UUID-ов больших файлов

Пример

bankControlStatementInfo.creationMode=ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.externalId=16d6a46e-e05f-48eb-ac69-a44980ae64cf
contractDate=2019-09-26
date=2019-09-26
TABLES
Table=BfAttachments
fileId=3988b7d9-af97-47e3-90fc-9305ef85bd81
#

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

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

Заявление на регистрацию валютного контракта с указанием информации о контракте

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
CurrContract {
amount (number (18, 2), optional) Сумма контракта.
bankControlStatementInfo (BankControlStatementInfo) Информация о ведомости банковского контроля (ВБК в банк),
contractDate (string) Дата контракта, YYYY-MM-DD
contractEndDate (string, optional) Дата окончания обязательств по контракту. Формат YYYY-MM-DD.
Заполняется при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION)
contractNumber (string, optional) Номер контракта, 100 символов
contractType (string, optional) Код вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК)= [PRODUCT_EXPORT, SERVICE_EXPORT, MULTI_CONTRACT]
stringEnum: "PRODUCT_EXPORT", "SERVICE_EXPORT", "MULTI_CONTRACT".
Заполнять обязательно, если creationMode=ICS_CONTRACT_INFORMATION,
currencyCode (string, optional) Цифровой код валюты контракта,
Заполняется обязательно при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Для заполнения использовать справочник (Справочник валют - CurDict)
date (string) Дата составления документа. Формат YYYY-MM-DD
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
nonResidents (Array[BankControlStatementNonResident], optional) Информация о нерезидентах. Заполняется при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Для заполнения использовать справочник (Справочник стран Country)
number (string, optional) Номер документа, 7 символов
}BankControlStatementInfo {
authPersonName (string, optional) ФИО ответственного лица. Ограничение 60 символов.
authPersonTelfax (string, optional) Телефон ответственного лица. Ограничение 40 символов.
bfAttachments (Array[BfAttachment], optional) Прикрепленные большие файлы. Заполняется обязательно, если creationMode=ICS_CONTRACT_REGISTRATION,
creationMode (string) Режим создания ВБК = [ICS_CONTRACT_INFORMATION, ICS_CONTRACT_REGISTRATION]
stringEnum: "ICS_CONTRACT_INFORMATION", "ICS_CONTRACT_REGISTRATION",
currencyName (string, optional) Буквенный ISO-код валюты контракта. Заполняется при предоставлении информации по контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Формат ^[A-Z]{3}$.
Для заполнения использовать справочник (Справочник валют - CurDict),
externalId (string) Идентификатор документа в организации-партнере
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}BankControlStatementNonResident {
countryCode (string) Цифровой код страны, 3 символа
countryName (string) Наименование страны. 255 символов
name (string) Наименование иностранного контрагента, 400 символов
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла,
fileName (string, optional, read only) Имя файла

Пример

{
   "amount":1.01,
   "date":"2019-11-21",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "bankControlStatementInfo":{
      "authPersonName":"Иванов Иван Иванович",
      "authPersonTelfax":"4955005550",
      "bfAttachments":[
         {
            "fileId":"8e9d6ce6-d5d7-4d81-96b8-9af0e7e17694"
         }
      ],
      "creationMode":"ICS_CONTRACT_REGISTRATION",
      "currencyName":"USD",
      "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
   },
   "contractDate":"2018-12-31",
   "contractEndDate":"2018-12-31",
   "contractNumber":"123АБВ",
   "contractType":"MULTI_CONTRACT",
   "currencyCode":"840",
   "nonResidents":[
      {
         "countryCode":"643",
         "countryName":"РОССИЯ",
         "name":"Kazan"
      }
   ],
   "number":"1"
}

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

Теги дайджеста должны быть отсортированы по алфавиту. В таблице bfAttachments UUID-ы сортируются по возрастанию.
В таблице NonResidents данные сортируются аналогично сортировке в исходном документе. В дайджесте не указываются значения Number и блок linkedDocs.

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

Наименование поля Описание поля Пример
amount Сумма контракта 01.янв
bankControlStatementInfo.authPersonName ФИО ответственного лица Петров Петр Иванович
bankControlStatementInfo.authPersonTelfax Телефон ответственного лица 79263689379
bankControlStatementInfo.creationMode Режим создания ВБК ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.currencyName Буквенный ISO-код валюты договора USD
bankControlStatementInfo.externalId Идентификатор документа в организации-партнере 550e8400-e29b-41d4-a716-446655440000
contractDate Дата договора 16.05.2019
contractEndDate Дата договора 16.05.2019
contractNumber Номер контракта 2442
contractType Код вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК) MULTI_CONTRACT
currencyCode Цифровой код валюты договора 840
date Дата создания документа по местному времени 16.05.2019
TABLES Значение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachments Значение указывается при наличии UUID-ов больших файлов
fileId UUID больших файлов 31663ef5-7975-4016-b0f3-f1d70a4e9c22
# Разделитель значений UUID-ов больших файлов
fileId UUID больших файлов 51663ef5-7975-4016-b0f3-f1d70a4e9c22
# Разделитель значений UUID-ов больших файлов
Table=NonResidents
countryCode Цифровой код страны иностранного контрагента 38
countryName Наименование страны иностранного контрагента Казахстан
name Наименование иностранного контрагента Kazan
# Разделитель нерезидентов

Пример

amount=1.01
bankControlStatementInfo.authPersonName=Иванов Иван Иванович
bankControlStatementInfo.authPersonTelfax=4955005550
bankControlStatementInfo.creationMode=ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.currencyName=USD
bankControlStatementInfo.externalId=16d6a46e-e05f-48eb-ac69-a44980ae64cf
contractDate=2019-09-26
contractEndDate=2019-09-26
contractNumber=123АБВ
contractType=MULTI_CONTRACT
currencyCode=840
date=2019-09-26
TABLES
Table=NonResidents
countryCode=038
countryName=Казахстан
name=Kazan
#

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

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

Предоставление информации об экспортном контракте

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-1
Параметры запроса
Body
:--- ---
CurrContract {
amount (number (18, 2), optional) Сумма контракта.
bankControlStatementInfo (BankControlStatementInfo) Информация о ведомости банковского контроля (ВБК в банк),
contractDate (string) Дата контракта, YYYY-MM-DD
contractEndDate (string, optional) Дата окончания обязательств по контракту.
Формат YYYY-MM-DD.
Заполняется при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION)
contractNumber (string, optional) Номер контракта, 100 символов
contractType (string, optional) Код вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК)= [PRODUCT_EXPORT, SERVICE_EXPORT, MULTI_CONTRACT] stringEnum: "PRODUCT_EXPORT", "SERVICE_EXPORT", "MULTI_CONTRACT".
Заполнять обязательно, если creationMode=ICS_CONTRACT_INFORMATION,
currencyCode (string, optional) Цифровой код валюты контракта, Заполняется обязательно при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Для заполнения использовать справочник (Справочник валют - CurDict)
date (string) Дата составления документа. Формат YYYY-MM-DD
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
nonResidents (Array[BankControlStatementNonResident], optional) Информация о нерезидентах. Заполняется при предоставлении информации по экспортному контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Для заполнения использовать справочник (Справочник стран Country)
number (string, optional) Номер документа, 7 символов
}BankControlStatementInfo {
authPersonName (string, optional) ФИО ответственного лица. Ограничение 60 символов,
authPersonTelfax (string, optional) Телефон ответственного лица. Ограничение 40 символов,
creationMode (string) Режим создания ВБК = [ICS_CONTRACT_INFORMATION, ICS_CONTRACT_REGISTRATION]
stringEnum: "ICS_CONTRACT_INFORMATION", "ICS_CONTRACT_REGISTRATION",
currencyName (string, optional) Буквенный ISO-код валюты контракта.
Заполняется при предоставлении информации по контракту без контракта (creationMode=ICS_CONTRACT_INFORMATION).
Формат ^[A-Z]{3}$.
Для заполнения использовать справочник (Справочник валют - CurDict),
externalId (string) Идентификатор документа в организации-партнере,
failReasons (Array[FailReason], optional, read only) Причины отказа
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}BankControlStatementNonResident {
countryCode (string) Цифровой код страны, 3 символа
countryName (string) Наименование страны. 255 символов
name (string) Наименование иностранного контрагента, 400 символов

Пример

{
   "amount":1.01,
   "bankComment":"string",
   "bankControlStatementInfo":{
      "authPersonName":"Иванов Иван Иванович",
      "authPersonTelfax":"4955005550",
      "bankCommentAuthor":"Иванов Иван Иванович",
      "creationMode":"ICS_CONTRACT_INFORMATION",
      "currencyName":"USD",
      "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "failReasons":[
         {
            "docField":"Номер контракта",
            "reasonComment":"Указан неверно",
            "reasonId":"PS_REST_REJ_PART_2-9",
            "returnComment":"Отказ проверки"
         }
      ]
   },
   "bankStatus":"string",
   "contractDate":"2018-12-31",
   "contractEndDate":"2018-12-31",
   "contractNumber":"123АБВ",
   "contractType":"MULTI_CONTRACT",
   "currencyCode":"840",
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "nonResidents":[
      {
         "countryCode":"643",
         "countryName":"РОССИЯ",
         "name":"Kazan"
      }
   ],
   "number":"1"
}

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

Теги дайджеста должны быть отсортированы по алфавиту. В таблице bfAttachments UUID-ы сортируются по возрастанию.
В таблице NonResidents данные сортируются аналогично сортировке в исходном документе. В дайджесте не указываются значения Number и блок linkedDocs.

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

Наименование поля Описание поля Пример
amount Сумма контракта 01.янв
bankControlStatementInfo.authPersonName ФИО ответственного лица Петров Петр Иванович
bankControlStatementInfo.authPersonTelfax Телефон ответственного лица 79263689379
bankControlStatementInfo.creationMode Режим создания ВБК ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.currencyName Буквенный ISO-код валюты договора USD
bankControlStatementInfo.externalId Идентификатор документа в организации-партнере 550e8400-e29b-41d4-a716-446655440000
contractDate Дата договора 16.05.2019
contractEndDate Дата окончания обязательств по контракту 16.05.2019
contractNumber Номер контракта 2442
contractType Код вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК) MULTI_CONTRACT
currencyCode Цифровой код валюты договора 840
date Дата создания документа по местному времени 16.05.2019
number Номер сформированного документа на стороне клиента 13323
TABLES Значение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=NonResidents
countryCode Цифровой код страны иностранного контрагента 38
countryName Наименование страны иностранного контрагента Казахстан
name Наименование иностранного контрагента Kazan
# Разделитель нерезидентов

Пример

amount=1.01
bankControlStatementInfo.authPersonName=Иванов Иван Иванович
bankControlStatementInfo.authPersonTelfax=4955005550
bankControlStatementInfo.creationMode=ICS_CONTRACT_REGISTRATION
bankControlStatementInfo.currencyName=USD
bankControlStatementInfo.externalId=16d6a46e-e05f-48eb-ac69-a44980ae64cf
contractDate=2019-09-26
contractEndDate=2019-09-26
contractNumber=123АБВ
contractType=MULTI_CONTRACT
currencyCode=840
date=2019-09-26
TABLES
Table=NonResidents
countryCode=038
countryName=Казахстан
name=Kazan
#

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

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

Ресурс /v1/bank-control-statements/{externalId}/state

Ресурс позволяет получить статус по отправленному в банк документу.

Шаги:

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

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

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

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

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

Наименование Описание
Параметры заголовка
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/bank-control-statements
/22a6dd81-103a-4d3a-8e9b-0ba4b527f010/state'

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

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

Пример

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

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

Код состояние документа Наименование статуса
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят
ACCEPTED_BY_ABS Принят АБС
CREATED Создан
DELIVERED Доставлен
EXPORTED Выгружен
TRIED_BY_CFE Проверяется ВК
WAITSENDDOCUMENT Ожидает досыла документа
Окончательные статусы/Прекратить опрос
INVALIDEDS ЭП/АСП не верна
REQUISITEERROR Ошибка реквизитов
REFUSEDBYABS Отказан АБС
REFUSED_BY_CFE Отказан ВК
Окончательные(Успешные) статусы/Прекратить опрос
ACCEPTED_BY_CFE Принят ВК

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

Ресурс /v1/bank-control-statements/reg-curr-contracts/{externalId}

Ресурс позволяет создать запрос на получение ранее отправленного заявления на регистрацию валютного контракта.

Шаги:

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

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

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

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId String
Идентификатор документа, присвоенный клиентом

Пример

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/bank-control-statements/
reg-curr-contracts/22a6dd81-103a-4d3a-8e9b0ba4b527f5f6'

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

Наименование Описание
CurrContract {
amount (number, optional) Сумма контракта ,
balance (number, optional, read only) Сальдо расчетов ,
bankComment (string, optional, read only) Банковский комментарий к статусу документа ,
bankControlStatementInfo (BankControlStatementInfo) Информация о ведомости банковского контроля ,
bankStatus (string, optional, read only) Статус документа ,
contractDate (string) Дата контракта ,
contractEndDate (string, optional) Дата окончания обязательств по контракту ,
contractNumber (string, optional) Номер контракта ,
contractType (string, optional) Код вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК) = [PRODUCT_EXPORT, SERVICE_EXPORT, MULTI_CONTRACT]
stringEnum: "PRODUCT_EXPORT", "SERVICE_EXPORT", "MULTI_CONTRACT",
currencyCode (string, optional) Цифровой код валюты контракта ,
date (string) Дата составления документа ,
decNonresToResidentLiabSum (number, optional, read only) Сумма по подтверждающим документам, уменьшающим обязательства нерезидента перед резидентом ,
decResidentToNonresLiabSum (number, optional, read only) Сумма по подтверждающим документам, уменьшающим обязательства резидента перед нерезидентом ,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа ,
finalTransCurrencyCode (string, optional, read only) Цифровой код страны ,
finalTransCurrencyName (string, optional, read only) Буквенный ISO-код валюты ,
incNonresidLiabilitySum (number, optional, read only) Сумма по подтверждающим документам, увеличивающим обязательства нерезидента ,
incResidentLiabilitySum (number, optional, read only) Сумма по подтверждающим документам, увеличивающим обязательства резидента ,
nonResidents (Array[BankControlStatementNonResident], optional) Информация о нерезидентах ,
number (string, optional) Номер документа ,
totalCredit (number, optional, read only) Сумма денежных средств, поступивших по контракту в пользу резидента (всего зачислено) ,
totalDebit (number, optional, read only) Сумма денежных средств, переведенных по контракту в пользу нерезидента (всего списано) ,
transDate (string, optional, read only) Дата расчета
}BankControlStatementInfo {
authPersonName (string, optional) ФИО ответственного лица ,
authPersonTelfax (string, optional) Телефон ответственного лица ,
bankCommentAuthor (string, optional, read only) Автор комментария ,
bfAttachments (Array[BfAttachment], optional) Прикрепленные большие файлы ,
chainId (string, optional, read only) Id цепочки ,
creationMode (string) Режим создания ВБК = [ICS_CONTRACT_INFORMATION, ICS_CONTRACT_REGISTRATION, ICS_CREDIT_REGISTRATION]
stringEnum: "ICS_CONTRACT_INFORMATION", "ICS_CONTRACT_REGISTRATION", "ICS_CREDIT_REGISTRATION",
currencyName (string, optional) Буквенный ISO-код валюты контракта ,
externalId (string) Идентификатор документа в организации-партнере ,
failReasons (Array[FailReason], optional, read only) Причины отказа ,
isActual (boolean, optional, read only) Признак актуальности ВБК ,
unk (string, optional, read only) Уникальный номер контракта, заполняемый банком
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}BankControlStatementNonResident {
countryCode (string) Цифровой код страны ,
countryName (string) Наименование страны ,
name (string) Наименование иностранного контрагента
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла ,
fileName (string, optional, read only) Имя файла
}FailReason {
docField (string, optional) Поле документа ,
reasonComment (string, optional) Правило заполнения/замечания ,
reasonId (string, optional) Код причины отказа ,
returnComment (string, optional) Комментарий

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

Ресурс /v1/bank-control-statements/reg-curr-cred-contracts/list

Ресурс позволяет получить UUID Валютных контрактов, зарегистрированных в Банке.

Шаги

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

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

Для получения UUID Валютных контрактов необходимо отправить GET-запрос (/v1/bank-control-statements/reg-curr-contracts/list), в котором передать авторизационный токен к данным собственной/дочерней организации (Access Token) и реквизиты запроса. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
date Date
Дата создания документа по местному времени (yyyy-MM-dd)
isActual String
Признак актуальности ВБК
false - возвращаются актуальные и архивные идентификаторы ВБК
true - возвращаются актуальные идентификаторы ВБК
page Number
Номер страницы

Пример

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
/reg-curr-contracts/list?date=2019-11-25&isActual=false&page=1" 

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

Наименование Описание
_links (Array[Link], optional) Ссылки на связанные ресурсы,
externalId (Array[string], optional) ВБК
}Link {
href (string) Абсолютный или относительный адрес,
rel (string) Отношение ссылки к текущей сущности (next, prev)

Пример

{
   "_links":[
      {
         "href":"? date=2018-03-15&isActual=false&page=3",
         "rel":"next"
      }
   ],
   "externalId":[
      "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "26a6dd81-103a-4d3a-8e9b-0ba4b527f5f8",
      "12a6dd31-103a-4d3a-8e9b-0ba4b527f5f4"
   ]
}

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

Ресурс /v1/bank-control-statements/send-curr-contracts

Ресурс позволяет дослать в Банк валютный контракт, как вложение, для ранее отправленного заявления о регистрации банковской ведомости, имеющей статус в АБС Банка "Ожидает досыла контракта".

Шаги:

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

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

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

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

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

Для создания запроса на досыл валютного контракта необходимо отправить POST-запрос (/v1/bank-control-statements/send-curr-contracts), в котором передать авторизационный токен к данным собственной/дочерней (Access Token) и реквизиты запроса досыла валютного контракта. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token собственной/дочерней организации, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
BankControlStatementInfoSendDoc {
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankControlStatementInfoSend (BankControlStatementInfoSend) Досыл валютного контракта,
bankStatus (string, optional, read only) Статус документа,
date (string) Дата составления документа,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
number (string, optional) Номер документа
}BankControlStatementInfoSend {
authPersonName (string, optional) ФИО ответственного лица,
authPersonTelfax (string, optional) Телефон ответственного лица,
bankCommentAuthor (string, optional, read only) Автор комментария,
bfAttachments (Array[BfAttachment], optional) Прикрепленные большие файлы,
chainId (string) Id цепочки,
externalId (string) Идентификатор документа в организации-партнере,
failReasons (Array[FailReason], optional, read only) Причины отказа
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла,
fileName (string, optional, read only) Имя файла
}FailReason {
docField (string, optional) Поле документа,
reasonComment (string, optional) Правило заполнения/замечания,
reasonId (string, optional) Код причины отказа,
returnComment (string, optional) Комментарий

Пример

{
   "bankComment":"Отклонено",
   "bankControlStatementInfoSend":{
      "authPersonName":"Иванов Иван Иванович",
      "authPersonTelfax":"4955005550",
      "bankCommentAuthor":"Иванов Иван Иванович",
      "bfAttachments":[
         {
            "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
            "fileName":"SB_7718830000_40702810038290010000_T18.txt"
         }
      ],
      "chainId":"1234567890123",
      "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "failReasons":[
         {
            "docField":"Номер контракта",
            "reasonComment":"Указан неверно",
            "reasonId":"PS_REST_REJ_PART_2-9",
            "returnComment":"Отказ проверки"
         }
      ]
   },
   "bankStatus":"string",
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "number":"1"
}
Выполнить досыл контракта возможно только для контрактов в статусе WAITSENDDOCUMENT ("Ожидает досыла контракта")

Для получения значения параметра chainId необходимо выполнить запрос актуальной ВБК из Банка, используя ресурс /v1/bank-control-statements/reg-curr-contracts/{externalId} Документ должен содержать уникальный идентификатор файла (fileId)

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

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

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

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

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

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

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

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

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

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

Наименование поля Описание поля Пример
bankControlStatementInfoSend.authPersonName ФИО ответственного лица Петров Петр Иванович
bankControlStatementInfoSend.authPersonTelfax Телефон ответственного лица 79263689379
bankControlStatementInfoSend.chainId ID цепочки контрактов 1,23457E+12
bankControlStatementInfoSend.externalId Идентификатор документа в организации-партнере 550e8400-e29b-41d4-a716-446655440000
date Дата создания документа по местному времени 16.05.2019
TABLES Значение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachments Значение указывается при наличии UUID-ов больших файлов
fileId UUID больших файлов 51663ef5-7975-4016-b0f3-f1d70a4e9c22
# Разделитель значений UUID-ов больших файлов

Пример

bankControlStatementInfoSend.authPersonName=Иванов Иван Иванович
bankControlStatementInfoSend.authPersonTelfax=4955005550
bankControlStatementInfoSend.chainId=1234567890123
bankControlStatementInfoSend.externalId=16d6a46e-e05f-48eb-ac69-a44980ae64cf
date=2019-05-16
TABLES
Table=BfAttachments
fileId=3988b7d9-af97-47e3-90fc-9305ef85bd81
#

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

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

Ресурс /v1/bank-control-statements/{externalId}/state

Ресурс позволяет получить статус по отправленному в банк документу.

Шаги:

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

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

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

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId String Идентификатор документа, присвоенный клиентом

Пример

curl -X GET --header "Accept: /" --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/
bank-control-statements/ffffffff-fffa-458e-ad92-fff9497303ba/state'

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

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

Пример

{
    "bankStatus": "CREATED",
    "bankComment": null,
    "channelInfo": null,
}

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

Код состояние документа Наименование статуса
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят
ACCEPTED_BY_ABS Принят АБС
CREATED Создан
DELIVERED Доставлен
EXPORTED Выгружен
TRIED_BY_CFE Проверяется ВК
WAITSENDDOCUMENT Ожидает досыла документа
Окончательные статусы/Прекратить опрос
INVALIDEDS ЭП/АСП не верна
REQUISITEERROR Ошибка реквизитов
REFUSEDBYABS Отказан АБС
REFUSED_BY_CFE Отказан ВК
Окончательные(Успешные) статусы/Прекратить опрос
ACCEPTED_BY_CFE Принят ВК

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

Ресурс /v1/bank-control-statements/send-curr-contracts/{externalId}

Ресурс позволяет получить атрибуты ранее отправленного документа.

Шаги:

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

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

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

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId String Идентификатор документа, присвоенный клиентом

Пример

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/
send-curr-contracts//ffffffff-fffa-458e-ad92-fff9497303ba/state'

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

Соответствует модели запроса на досыл контракта Ресурс--v1-bank-control-statements--externalId--state

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

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

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

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, чтобы сообщить нам о ней