Получение документа валютный контракт с нерезидентом (ВБК в банк)

Обновлено 19 февраля 2025

/fintech/api/v1/bank-control-statements/reg-curr-contracts/\{externalId\}

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

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

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

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

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

Request

/fintech/api/v1/bank-control-statements/reg-curr-contracts/{externalId}

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]38$	required	Access token пользователя, полученный через SSO.
PATH PARAMETER
externalId	string	UUID	^[0-9a-f]8-[0-9a-f]4-[0-9a-f]4-[0-9a-f]4-[0-9a-f]12$	required	Идентификатор документа, присвоенный вами при его создании

GET /fintech/api/v1/bank-control-statements/reg-curr-contracts/6a54593d-464b-4c8e-a7e2-742a05e5c241 HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*

Responses

200 (OK)

Модель
Пример

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "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": "РОССИЯ",
      "isAffiliatedPerson": false,
      "name": "Kazan"
    }
  ],
  "number": "1",
  "totalCredit": 1.01,
  "totalDebit": 1.01,
  "transDate": "2018-12-31",
  "xmlBodies": [
    "string"
  ]
}

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
  
{
    "cause": "VALIDATION_FAULT",
    "referenceId": "0d6a80ba-7d35-4858-8443-9a77039ad9f1",
    "message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
    "checks": [],
    "fieldNames": null
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция `BANK_CONTROL_STATEMENT`. Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

404 (Not found)

Cause	Message	Description
NOT_FOUND	Документ с указанным ID не найден

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
  
{
    "cause": "NOT_FOUND",
    "referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
    "message": "Документ с указанным ID не найден"
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}