ym88659208ym87991671
Создание документа "Сведения о валютной операции" | Документация для разработчиков

Создание документа "Сведения о валютной операции"

Обновлено 29 ноября 2024
Компаниям
Холдингам

Alt text /fintech/api/v1/currency-operation-details

Запрос позволяет создавать документ «Сведения о валютных операциях» (далее СВО).

Для создания СВО необходимо отправить POST-запрос /fintech/api/v1/currency-operation-details с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами документа в теле.

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

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

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

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

Request

/fintech/api/v1/currency-operation-details
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]{38}$requiredAccess token пользователя, полученный через SSO.
BODY
**CurrencyOperationDetails {**
  accountNumberstringstring^[0-9]{20}$optionalНомер счета,
  addInfostringstring^.{1,2000}$optionalДополнительная информация,
  authPersonNamestringstring^.{1,60}$optionalФИО ответственного лица,
  authPersonTelfaxstringstring^.{1,40}$optionalТелефон ответственного лица,
  bankNonResidentCountryNamestringstring^.{1,255}$

Актуальный список значений можно получить с помощью справочника Country		optionalНаименование страны,
  bankNonResidentCountryNumericCodestringОКСМ^[0-9]{3}$

Актуальный список значений можно получить с помощью справочника Country		requiredЦифровой код страны,
  bfAttachmentsarray[BfAttachment]arrayoptionalПрикрепленные большие файлы,
  correctionbooleanboolean^(true|false)$optionalПризнак корректировки,
  correctionNumberintegerinteger^[0-9]{1,3}$optionalПорядковый номер корректировки,
  currencyDocDatestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$optionalДата валютного документа,
  currencyDocNumberstringstring^[0-9]{1,100}$optionalНомер документа по валютной операций,
  currencyDocTypestringstring^(PayDocCur|PayDocRu|CurrencyNotices)$optionalТип валютного документа.

PayDocCur - Валютное платежное поручение;
 PayDocRu - Рублевое платежное поручение;
* CurrencyNotices - Уведомление о зачислении (поступлении) иностранной валюты на транзитный валютный счет,
  datestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$requiredДата составления документа,
  digestSignaturesarray[Signature]arrayoptionalЭлектронные подписи по дайджесту документа.
- Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
- Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СберБизнес.

О подписании дайджеста документа подробно рассказали в соответствующем разделе документации.
  externalIdstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredИдентификатор документа, который вы присваиваете самостоятельно,
  isAccountInOtherBankbooleanboolean^(true|false)$requiredПризнак счета в другом банке,
  isNumberAbsentbooleanboolean^(true|false)$requiredПризнак отсутствия номера валютного документа,
  linkedDocsarray[LinkedDoc]arrayoptionalCвязанные документы,
  numberstringstring^[0-9]{1,7}$optionalНомер документа,
  operationDatestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$optionalДата операции,
  operationsarray[CurrencyOperationDetailsDoc]arrayrequiredДокументы валютного контроля,
  paymentAmountAmountCurrencyobjectrequiredСумма и валюта платежа,
  paymentDirectionstringstring^(1|2)$requiredНаправление платежа.

1 - зачисление;
 2 - списание,
  senderInnstringstring^([0-9]{5}|[0-9]{10}|[0-9]{12}|0)$requiredИНН резидента, указываемый в документе,
  senderNamestringstring^.{1,1024}$requiredПолное наименование организации, указываемое в документе,
  senderOkpostringstring^([0-9]{8}|[0-9]{10})$requiredОКПО клиента, указываемый в документе
}
BfAttachment {
  fileIdstringstring^[a-zA-Z0-9. \ _ -]+$optionalУникальный идентификатор файла
}
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Уникальный идентификатор сертификата ключа проверки электронной подписи
}
LinkedDoc {
  docExtIdstringUUID^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$requiredИдентификатор документа во внешней системе,
  typestringstring^[a-zA-Z0-9. \ _ -]{1,50}$requiredТип связанного документа
}
CurrencyOperationDetailsDoc {
  additionalInfostringstring^.{1,300}$optionalПримечание,
  amountAmountCurrencyobjectrequiredСумма платежа,
  contractDatestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$optionalДата договора,
  contractNumberstringstring^[0-9]{1,100}$optionalНомер договора.

Указывается обязательно, если contractNumberType = 0 или 1
  contractNumberTypestringstring^(0|1|2)$optionalТип указание номера договора.

0 - Указывается номеру и дата договора;
 1 - Указывается только дата договора;
* 2 - Указывается уникальный номер контракта (кредитного договора),
  creditAmountAmountCurrencyobjectoptionalСумма платежа в валюте цены контракта.

Заполнение блока не требуется, если сумма и валюта договора совпадает с суммой и валютой платежа,
  dataCompositionstringstring^(1|2|3|4|5|6|8)$optionalСостав предоставляемой информации.

1 - Информация об Уникальном номере контракта;
 2 - Документы, связанные с проведением операции (кредитного договора);
3 - Информация о коде вида операции;
 4 - Информация о Коде вида операции + Информация об Уникальном номере контракта;
5 - Документы, связанные с проведением операции + Информация об Уникальном номере контракта;
 6 - Документы, связанные с проведением операции представлены ранее;
* 8 - Сведения Уполномоченного банка о проведении операции с указанием Уникального номера контракта (кредитного договора),
  expectedDatestringISO 8601 YYYY-MM-DD^[0-9]{4}-[0-9]{2}-[0-9]{2}$optionalОжидаемый срок.

Значение должно быть >= contractDate,
  operationCodestringstring^[0-9]{5}$requiredКод вида валютной операции,
  operationCodeDescriptionstringstring^.{1,2000}$requiredОписание валютной операции,
  operationReasonstringstring^(1|2|3|4)$requiredОснование проведения операции.
1 - Контракт (кредитный договор) с нерезидентом, сумма которого ≤ 600 000 рублей РФ;
 2 - Контракт (кредитный договор) с нерезидентом, не требующий постановки на учет, сумма которого > 600 000 рублей РФ;
**3** - Контракт (кредитный договор), поставленный на учет в банке;
 4 - Иные,
  passportNumberstringstring^([0-9]{2}((0[1-9])|(1[0-2]))[0-9]{2}[0-9A-Z]{1}[0-9]{1}/)[0-9]{4}/([G][U][0-9]{2}|[0-9]{4})/([1234569]/)[0-3]$optionalУникальный номер контракта (кредитного договора).

Указывается обязательно, если contractNumberType = 2,
  paymentConditionsstringstring^(1|2)$optionalУсловия расчета.
0 - Аванс;
 1 - По факту,
  serialNumberintegerinteger^[0-9]{1,3}$requiredНомер по порядку
}
AmountCurrency {
  amountnumbernumber^[0-9]{1,16}\.[0-9]{2}$requiredСумма,
  currencyCodestringISO 4217^[0-9]{1,3}$requiredЦифровой код валюты,
  currencyNamestringISO 4217^[A-Z]{3}$requiredБуквенный ISO-код валюты
}

digestSignatures

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

Если в запросе contractNumberType = 2, то в дайджесте необходимо указать passportNumber.

Наименование поляОписание поляПример
accountNumberНомер счета40702810123643875107
addInfoДополнительная информацияДополнительная информация
authPersonNameФИО ответственного лицаИванов Иван Иванович
authPersonTelfaxТелефон ответственного лица+7 123 1456 56 56
bankNonResidentCountryNameНаименование страныСОЕДИНЕННОЕ КОРОЛЕВСТВО
bankNonResidentCountryNumericCodeКод страны826
correctionПризнак корректировкиfalse
correctionNumberНомер корректировки1
currencyDocDateДата валютного документа2019-05-16
currencyDocNumberНомер валютного документа54321
currencyDocTypeТип валютного документаPayDocCur
dateДата документа2019-05-16
externalIdИдентификатор документа в организации-партнере75d8d497-05cc-4cc6-9b78-070ae0a605fd
isAccountInOtherBankПризнак счета в другом банкеfalse
isNumberAbsentПризнак отсутствия номера валютного документаfalse
paymentAmount.amountСумма платежа2.02
paymentAmount.currencyCodeЦифровой код валюты платежа840
paymentAmount.currencyNameISO код валюты платежаUSD
paymentDirectionНаправление платежа1
senderInnИНН клиента7582099944
senderNameПолное наименование клиентаОрганизация NyJurbsIJTXzRTL
senderOkpoОКПО клиента1350995802
TABLESЗначение указывается при наличии UUID-ов больших файлов или Операций
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов08ba3412-118a-4f4d-be23-e93f81d58fdc
#Разделитель строк таблицы
fileIdUUID больших файлов81ff03ad-bceb-4a8a-b5bf-8c8439519bab
#Разделитель строк таблицы
Table=OperationsЗначение указывается при наличии операций
additionalInfoДополнительная информацияПримечание
amount.amountСумма платежа2.02
amount.currencyCodeЦифровой код валюты платежа840
amount.currencyNameISO код валюты платежаUSD
contractDateДата договора2019-05-16
contractNumberНомер договора123
contractNumberTypeТип заполнения номера договора0
creditAmount.amountСумма договора33.33
creditAmount.currencyCodeЦифровой код валюты договора840
creditAmount.currencyNameISO код валюты договораUSD
dataCompositionСостав предоставляемой информации3
expectedDateОжидаемый срок2019-05-16
operationCodeКод вида валютной операции20300
operationCodeDescriptionОписание валютной операцииОплата нерезидента резиденту по договору аренды движимого или недвижимого имущества
operationReasonОснование проведения операции1
passportNumberУникальный номер контракта (кредитного договора)120123A0/1234/GU23/1/2
paymentConditionsУсловия расчета1
serialNumberНомер по порядку0

Responses

201 (Created)
НаименованиеТипОбязательностьОписание
CurrencyOperationDetails {
  acceptDatestringoptionalДата представления в банк,
  accountNumberstringoptionalНомер счета,
  addInfostringoptionalДополнительная информация,
  authPersonNamestringoptionalФИО ответственного лица,
  authPersonTelfaxstringoptionalТелефон ответственного лица,
  bankCommentstringoptionalБанковский комментарий к статусу документа,
  bankNonResidentCountryNamestringoptionalНаименование страны,
  bankNonResidentCountryNumericCodestringrequiredЦифровой код страны,
  bankStatusstringrequiredСтатус документа,
  bfAttachmentsarray[BfAttachment]optionalПрикрепленные большие файлы,
  correctionbooleanoptionalПризнак корректировки,
  correctionNumberintegeroptionalПорядковый номер корректировки,
  currencyDocDatestringoptionalДата валютного документа,
  currencyDocNumberstringoptionalНомер документа по валютной операций,
  currencyDocTypestringoptionalТип валютного документа,
  datestringrequiredДата составления документа,
  digestSignaturesarray[Signature]optionalЭлектронные подписи по дайджесту документа,
  executorEmployeeNamestringoptionalДолжность ответственного лица,
  executorNamestringoptionalПодпись ответственного лица,
  externalIdstringrequiredИдентификатор документа, который вы присваиваете самостоятельно,
  failReasonsarray[FailReason]optionalПричины отказа,
  isAccountInOtherBankbooleanrequiredПризнак счета в другом банке,
  isNumberAbsentbooleanrequiredПризнак отсутствия номера валютного документа,
  linkedDocsarray[LinkedDoc]optionalCвязанные документы,
  numberstringoptionalНомер документа,
  operationDatestringoptionalДата операции,
  operationsarray[CurrencyOperationDetailsDoc]requiredДокументы валютного контроля,
  paymentAmountAmountCurrencyrequiredСумма и валюта платежа,
  paymentDirectionstringrequiredНаправление платежа,
  senderInnstringrequiredИНН резидента, указываемый в документе,
  senderNamestringrequiredПолное наименование организации, указываемое в документе,
  senderOkpostringrequiredОКПО клиента, указываемый в документе,
  valueDatestringoptionalДата принятия/возврата
}
BfAttachment {
  fileIdstringoptionalУникальный идентификатор файла,
  fileNamestringoptionalИмя файла
}
Signature {
  base64EncodedstringrequiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateuuidstringrequiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
FailReason {
  docFieldstringoptionalПоле документа,
  reasonCommentstringoptionalПравило заполнения/замечания,
  reasonIdstringoptionalКод причины отказа,
  returnCommentstringoptionalКомментарий
}
LinkedDoc {
  docExtIdstringrequiredИдентификатор документа во внешней системе,
  typestringrequiredТип связанного документа
}
CurrencyOperationDetailsDoc {
  additionalInfostringoptionalПримечание,
  amountAmountCurrencyrequiredСумма платежа,
  contractDatestringoptionalДата договора,
  contractNumberstringoptionalНомер договора,
  contractNumberTypestringoptionalТип указание номера договора,
  creditAmountAmountCurrencyoptionalСумма платежа в валюте цены контракта,
  dataCompositionstringoptionalСостав предоставляемой информации,
  expectedDatestringoptionalОжидаемый срок,
  operationCodestringrequiredКод вида валютной операции,
  operationCodeDescriptionstringrequiredОписание валютной операции,
  operationReasonstringrequiredОснование проведения операции,
  passportNumberstringoptionalУникальный номер контракта (кредитного договора),
  paymentConditionsstringoptionalУсловия расчета,
  serialNumberintegerrequiredНомер по порядку
}
AmountCurrency {
  amountnumberrequiredСумма,
  currencyCodestringrequiredЦифровой код валюты,
  currencyNamestringrequiredБуквенный ISO-код валюты
}
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, не указана операция CURRENCY_OPERATION_DETAILS. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены 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 в настройках своего браузера.