ym88659208ym87991671
Создание валютного контракта с нерезидентом (ВБК в банк) | Документация для разработчиков

Создание валютного контракта с нерезидентом (ВБК в банк)

Обновлено 19 февраля 2025
Компаниям
Холдингам

Alt text /fintech/api/v1/bank-control-statements/reg-curr-contracts

Запрос позволяет создать заявление на регистрацию валютного контракта (ВК).

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

В параметре scope ссылки авторизации пользователя должен быть указан сервис BANK_CONTROL_STATEMENT для получения доступа к этому запросу.

  • Если в запросе на создание заявления передать ЭП к документу (объект digestSignatures), то Банк сразу начнет обработку документа.
  • Если в запросе не передавать ЭП к документу, то заявление будет создано в статусе черновик. Для начала обработки документа Банком потребуется зайти в интерфейс СберБизнес и подписать его.

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

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

Request

/fintech/api/v1/bank-control-statements/reg-curr-contracts
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]38$requiredAccess token пользователя, полученный через SSO.
BODY
CurrContract {
  amountnumberfloat^[0-9]16\.[0-9]2$optionalСумма платежа,
  bankControlStatementInfoBankControlStatementInfoobjectrequiredИнформация о ведомости банковского контроля,
  contractDatestringISO 8601 YYYY-MM-DD^[0-9]4-[0-9]2-[0-9]2$requiredДата контракта
  contractEndDatestringISO 8601 YYYY-MM-DD^[0-9]4-[0-9]2-[0-9]2$optionalДата окончания обязательств по контракту,
  contractNumberstringstring^.100$optionalНомер контракта,
  contractTypestringstring^(PRODUCT_EXPORT|SERVICE_EXPORT|MULTI_CONTRACT)$optionalКод вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта.

Заполнять обязательно, если creationMode=ICS_CONTRACT_INFORMATION,
  currencyCodestringЦифровой ISO-код валюты^[0-9]3$

Актуальный список значений можно получить с помощью справочника CurDict		optionalКод валюты контракта.

Заполнять обязательно, если creationMode=ICS_CONTRACT_INFORMATION,
  datestringISO 8601 YYYY-MM-DD^[0-9]4-[0-9]2-[0-9]2$requiredДата составления документа,
  digestSignaturesarray[Signature]arrayoptionalЭлектронные подписи по дайджесту документа.
- Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
- Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес.

О подписании дайджеста документа подробно рассказали в соответствующем разделе документации.
  nonResidentsarray[BankControlStatementNonResident]arrayoptionalИнформация о нерезидентах,
  numberstringstring^[a-zA-Z0-9. \ _ -]7$optionalНомер документа,
}
BankControlStatementInfo {
  authPersonNamestringstring^.60$optionalФИО ответственного лица,
  authPersonTelfaxstringstring^.40$optionalТелефон ответственного лица,
  bfAttachmentsarray[BfAttachment]arrayoptionalПрикрепленные большие файлы,
  creationModestringstring^(ICS_CONTRACT_INFORMATION|ICS_CONTRACT_REGISTRATION)$requiredРежим создания ВБК,

ICS_CONTRACT_REGISTRATION - указывается при регистрации контракта, когда необходимо отправить сам контракт во вложении, чтобы поставить его на учет.
ICS_CONTRACT_INFORMATION - заполняется в случае, если необходимо предоставить только информацию о контракте, для отправки СВО, к примеру (см. 181-И).
  currencyNamestringБуквенный ISO-код валюты^[a-zA-Z0-9. \ _ -]3$

Актуальный список значений можно получить с помощью справочника CurDict		optionalКод валюты контракта,
  externalIdstringUUID^[0-9a-f]8-[0-9a-f]4-[0-9a-f]4-[0-9a-f]4-[0-9a-f]12$requiredИдентификатор документа, который вы присваиваете самостоятельно
}
Signature {
  base64Encodedstringbase64^[a-zA-Z0-9]+$requiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateuuidstringUUID^[0-9a-f]8-[0-9a-f]4-[0-9a-f]4-[0-9a-f]4-[0-9a-f]12$requiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
BankControlStatementNonResident {
  countryCodestringОКСМ^[0-9]3$

Актуальный список значений можно получить с помощью справочника Country		requiredЦифровой код страны,
  countryNamestringstring^.255$

Актуальный список значений можно получить с помощью справочника Country		requiredНаименование страны,
  isAffiliatedPersonbooleanboolean^(true|false)$optionalПризнак аффилированного лица,
  namestringstring^.400$requiredНаименование иностранного контрагента
}
BfAttachment {
  fileIdstringstring^[a-zA-Z0-9. \ _ -]+$optionalУникальный идентификатор файла
}

digestSignatures

Формат дайджеста
Наименование поляОписание поляПример
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
#Разделитель нерезидентов

Responses

201 (Created)
НаименованиеТипОбязательностьОписание
CurrContract {
  amountnumberoptionalСумма платежа,
  balancenumberoptionalСальдо расчетов,
  bankCommentstringoptionalБанковский комментарий к статусу документа,
  bankControlStatementInfoBankControlStatementInforequiredИнформация о ведомости банковского контроля,
  bankStatusstringoptionalСтатус документа,
  contractDatestringrequiredДата контракта
  contractEndDatestringoptionalДата окончания обязательств по контракту,
  contractNumberstringoptionalНомер контракта,
  contractTypestringoptionalКод вида контракта, заполняемый для экспортных контрактов при представлении сведений по контракту без контракта,
  currencyCodestringoptionalКод валюты контракта,
  datestringrequiredДата составления документа,
  decNonresToResidentLiabSumnumberoptionalСумма по подтверждающим документам, уменьшающим обязательства нерезидента перед резидентом,
  decResidentToNonresLiabSumnumberoptionalСумма по подтверждающим документам, уменьшающим обязательства резидента перед нерезидентом,
  digestSignaturesarray[Signature]optionalЭлектронные подписи по дайджесту документа,
  finalTransCurrencyCodestringoptionalЦифровой код страны,
  finalTransCurrencyNamestringoptionalБуквенный ISO-код валюты,
  incNonresidLiabilitySumnumberoptionalСумма по подтверждающим документам, увеличивающим обязательства нерезидента,
  incResidentLiabilitySumnumberoptionalСумма по подтверждающим документам, увеличивающим обязательства резидента,
  nonResidentsarray[BankControlStatementNonResident]optionalИнформация о нерезидентах,
  numberstringoptionalНомер документа,
  totalCreditnumberoptionalСумма денежных средств, поступивших по контракту в пользу резидента (всего зачислено),
  totalDebitnumberoptionalСумма денежных средств, переведенных по контракту в пользу нерезидента (всего списано),
  transDatestringoptionalДата расчета,
  xmlBodiesarray[string]optionalСписок кодированных xml-файлов ВБК
}
BankControlStatementInfo {
  authPersonNamestringoptionalФИО ответственного лица,
  authPersonTelfaxstringoptionalТелефон ответственного лица,
  bankCommentAuthorstringoptionalАвтор комментария,
  bankDatestringoptionalДата постановки контракта/договора на учет,
  bfAttachmentsarray[BfAttachment]optionalПрикрепленные большие файлы,
  chainIdstringoptionalId цепочки,
  creationModestringrequiredРежим создания ВБК,
  currencyNamestringoptionalКод валюты контракта,
  externalIdstringrequiredИдентификатор документа, который вы присваиваете самостоятельно
  failReasonsarray[FailReason]optionalПричины отказа,
  isActualbooleanoptionalПризнак актуальности ВБК
}
Signature {
  base64EncodedstringrequiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateuuidstringrequiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
BankControlStatementNonResident {
  countryCodestringrequiredЦифровой код страны,
  countryNamestringrequiredНаименование страны,
  isAffiliatedPersonbooleanoptionalПризнак аффилированного лица,
  namestringrequiredНаименование иностранного контрагента
}
BfAttachment {
  fileIdstringoptionalУникальный идентификатор файла,
  fileNamestringoptionalИмя файла
}
FailReason {
  docFieldstringoptionalПоле документа,
  reasonCommentstringoptionalПравило заполнения/замечания,
  reasonIdstringoptionalКод причины отказа,
  returnCommentstringoptionalКомментарий
}
400 (Bad request)
CauseMessageDescription
DESERIALIZATION_FAULTНеверный формат запросаДанные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
WORKFLOW_FAULTДокумент с такими реквизитами уже существуетВ АС Банка также присутствует проверка на дублирование документов по полям.
Если поля совпадают с уже существующим в банке документом, то такой документ получает статус "bankStatus": "CHECKERROR", а комментарий "bankComment": "Документ с такими реквизитами уже существует."
VALIDATION_FAULTОшибка валидацииДанные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.
НаименованиеТипОбязательностьОписание
ResourceFault {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
  checksarray[Check]optionalСписок проверок, приведших к ошибке,
  fieldNamesarray[string]optionalНазвания полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
  levelstringoptionalУровень результата = ['ERROR', 'WARNING'],
  messagestringoptionalСообщение,
  fieldsarray[string]optionalНазвания полей (при наличии связи с моделью)
}
401 (Unauthorized Error)
CauseMessageDescription
UNAUTHORIZEDaccessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-хУказан просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
Некорректное значение Access TokenУказан некорректный access_token. Используйте refresh_token для обновления access_token и повторите запрос.
НаименованиеТипОбязательностьОписание
Notice {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
}
403 (Forbidden)
CauseMessageDescription
ACTION_ACCESS_EXCEPTIONОперация не может быть выполнена: доступ к ресурсу запрещенИспользуемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API.
В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция BANK_CONTROL_STATEMENT. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
НаименованиеТипОбязательностьОписание
Notice {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
}
429 (Too Many Requests)
CauseMessageDescription
TOO_MANY_REQUESTSПревышен лимит запросов. Повторите операцию позже.Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее
НаименованиеТипОбязательностьОписание
Notice{
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}
500 (Internal Server Error)
CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
}
503 (Service Temporarily Unavailable)
CauseMessageDescription
UNAVAILABLE_RESOURCE_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
  causestringoptionalПричина или основание сообщения,
  referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
  messagestringoptionalСообщение,
}
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.