ym88659208ym87991671
Валютный контракт в Банк | Документация SmartMarket
Skip to main content

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

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

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

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

Шаги

  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 заголовка запроса.

danger

ICS_CONTRACT_REGISTRATION - указывается при регистрации контракта, когда необходимо отправить сам контракт во вложении, чтобы поставить его на учет.

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

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

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

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

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

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

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
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"
}

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

danger

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

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

Наименование поляОписание поляПример
bankControlStatementInfo.creationModeРежим создания ВБКICS_CONTRACT_REGISTRATION
bankControlStatementInfo.externalIdИдентификатор документа в организации-партнере16d6a46e-e05f-48eb-ac69-a44980ae64cf
contractDateДата договора2019-09-26
dateДата создания документа по местному времени2019-09-26
TABLESЗначение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов31663ef5-7975-4016-b0f3-f1d70a4e9c22
#Разделитель значений UUID-ов больших файлов
fileIdUUID больших файлов3988b7d9-af97-47e3-90fc-9305ef85bd81
#Разделитель значений 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
#

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

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

НаименованиеОписание
Параметры заголовка
AuthorizationString
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Сумма контракта1.01
bankControlStatementInfo.authPersonNameФИО ответственного лицаПетров Петр Иванович
bankControlStatementInfo.authPersonTelfaxТелефон ответственного лица79263689379
bankControlStatementInfo.creationModeРежим создания ВБКICS_CONTRACT_REGISTRATION
bankControlStatementInfo.currencyNameБуквенный ISO-код валюты договораUSD
bankControlStatementInfo.externalIdИдентификатор документа в организации-партнере550e8400-e29b-41d4-a716-446655440000
contractDateДата договора2019-05-16
contractEndDateДата договора2019-05-16
contractNumberНомер контракта2442
contractTypeКод вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта (Режим создания ВБК)MULTI_CONTRACT
currencyCodeЦифровой код валюты договора840
dateДата создания документа по местному времени2019-05-16
TABLESЗначение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов31663ef5-7975-4016-b0f3-f1d70a4e9c22
#Разделитель значений UUID-ов больших файлов
fileIdUUID больших файлов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
#

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

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

НаименованиеОписание
Параметры заголовка
AuthorizationString
Access token, полученный через SSO.
Пример: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-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 символов,
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
#

Ресурс /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Ожидает досыла документа
Окончательные статусы/Прекратить опрос
CHECKERRORОшибка контроля
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)Дата расчета
xmlBodies (string, optional)BASE64 кодированные xml-файлы ВБК в формате Инструкции (в кодировке win1251) ,
}BankControlStatementInfo {
authPersonName (string, optional)ФИО ответственного лица ,
authPersonTelfax (string, optional)Телефон ответственного лица ,
bankCommentAuthor (string, optional, read only)Автор комментария ,
bankDate (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)Комментарий

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

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

Ресурс /v1/bank-control-statements/reg-curr-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"
}

danger

Выполнить досыл контракта возможно только для контрактов в статусе 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, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

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

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

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

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

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

Наименование поляОписание поляПример
bankControlStatementInfoSend.authPersonNameФИО ответственного лицаПетров Петр Иванович
bankControlStatementInfoSend.authPersonTelfaxТелефон ответственного лица79263689379
bankControlStatementInfoSend.chainIdID цепочки контрактов1,23457E+12
bankControlStatementInfoSend.externalIdИдентификатор документа в организации-партнере550e8400-e29b-41d4-a716-446655440000
dateДата создания документа по местному времени16.05.2019
TABLESЗначение указывается при наличии UUID-ов больших файлов или данных о нерезидентах
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов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
#

Ресурс /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Ожидает досыла документа
Окончательные статусы/Прекратить опрос
CHECKERRORОшибка контроля
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)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

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

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

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 преобразования:

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

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

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

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

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

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