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

Создание письма для целей ВК (в банк)

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

Alt text /fintech/api/v1/curr-control-messages/to-bank

Запрос позволяет создавать документ «Письмо для целей ВК (в Банк)».

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

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

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

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

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

Request

/fintech/api/v1/curr-control-messages/to-bank
НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^[a-zA-Z0-9]{38}$requiredAccess token пользователя, полученный через SSO.
BODY
ConfirmatoryDocumentsInquiry {
  authPersonNamestringstring^.{1,60}$optionalФИО ответственного лица,
  authPersonTelfaxstringstring^.{1,40}$optionalТелефон ответственного лица,
  bfAttachmentsarray[BfAttachment]arrayoptionalПрикрепленные большие файлы,
  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Идентификатор документа, который вы присваиваете самостоятельно,
  numberstringstring???optionalНомер документа,
  orgNamestringstring???requiredНаименование организации клиента,
  refDocumentLinkedDocobjectoptionalДокумент ВК, по которому ведется переписка,
  rootMessageLinkedDocobjectoptionalПисьмо ВК, на которое данное письмо является ответом.
Объект заполняется полученными данными из ответа на запрос /fintech/api/v1/curr-control-messages/from-bank,
  subjectstringstring???requiredТема письма,
  textstringstring???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^(ConfDocInq_138I|CurrencyOperationDetails|InternalControlStatement|CCMessageFromBank)$requiredТип связанного документа.

ConfDocInq_138I - справка о подтверждающих документах (СПД);
 CurrencyOperationDetails - сведения о валютной операции (СВО);
InternalControlStatement - ведомость банковского контроля (ВБК);
 CCMessageFromBank - письмо от ВК
}

digestSignatures

Формат дайджеста
Наименование поляОписание поляПример
authPersonNameФИО ответственного лицаПетров Петр Иванович
authPersonTelfaxТелефон ответственного лица79263689379
dateДата документа28.02.2019
externalIdИдентификатор документа в организации-партнере550e8400-e29b-41d4-a716-446655440000
orgNameНаименование организации клиентаООО "ТЕСТ"
subjectТема письмаДоговор ВК
textТекс письмаДобрый день!
TABLESЗначение указывается при наличии UUID-ов больших файлов
Table=BfAttachmentsЗначение указывается при наличии UUID-ов больших файлов
fileIdUUID больших файлов31663ef5-7975-4016-b0f3-f1d70a4e9c22
#Разделитель значений UUID-ов больших файлов
fileIdUUID больших файлов51663ef5-7975-4016-b0f3-f1d70a4e9c22
#Разделитель значений UUID-ов больших файлов

Responses

201 (Created)
НаименованиеТипОбязательностьОписание
ConfirmatoryDocumentsInquiry {
  authPersonNamestringoptionalФИО ответственного лица,
  authPersonTelfaxstringoptionalТелефон ответственного лица,
  bankCommentstringoptionalБанковский комментарий к статусу документа,
  bankStatusstringoptionalСтатус документа,
  bfAttachmentsarray[BfAttachment]optionalПрикрепленные большие файлы,
  datestringrequiredДата составления документа,
  digestSignaturesarray[Signature]optionalЭлектронные подписи по дайджесту документа,
  externalIdstringrequiredИдентификатор документа, который вы присваиваете самостоятельно,
  numberstringoptionalНомер документа,
  orgNamestringrequiredНаименование организации клиента,
  refDocumentLinkedDocoptionalДокумент ВК, по которому ведется переписка,
  rootMessageLinkedDocoptionalПисьмо ВК, на которое данное письмо является ответом,
  subjectstringrequiredТема письма,
  textstringrequiredТекст письма
}
BfAttachment {
  fileIdstringoptionalУникальный идентификатор файла,
  fileNamestringoptionalИмя файла
}
Signature {
  base64EncodedstringrequiredЗначение электронной подписи (ЭП), закодированное в Base64,
  certificateuuidstringrequiredУникальный идентификатор сертификата ключа проверки электронной подписи
}
LinkedDoc {
  docExtIdstringrequiredИдентификатор документа во внешней системе,
  typestringrequiredТип связанного документа
}
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, не указана операция CURR_CONTROL_MESSAGE_TO_BANK. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены 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 в настройках своего браузера.