Документы для валютного контроля

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

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

Ресурс /v1/curr-control-messages/to-bank

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

Шаги

1. Получить AccessToken.

2. Сформировать ЭП.

3. Отправить запрос.

4. Получить статус.

Для создания письма для целей ВК (в банк) необходимо отправить POST-запрос (/v1/curr-control-messages/to-bank), в котором передать авторизационный токен к данным (Access Token) и реквизиты данного документа. Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_CONTROL_MESSAGE_TO_BANK.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token собственной/дочерней организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
CurrControlMessageToBank {
authPersonName (string, optional) ФИО ответственного лица,
authPersonTelfax (string, optional) Телефон ответственного лица,
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional, read only) Статус документа,
bfAttachments (Array[BfAttachment], optional) Данные о файлах, связанных с письмом для целей ВК,
date (string) Дата составления документа,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
externalId (string) Идентификатор документа в организации-партнере,
number (string, optional) Номер документа,
orgName (string) Наименование организации клиента,
refDocument (LinkedDoc, optional) Документ ВК, по которому ведется переписка,
rootMessage (LinkedDoc, optional) Письмо ВК, на которое данное письмо является ответом,
subject (string) Тема письма,
text (string) Текст письма
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла,
fileName (string, optional, read only) Имя файла
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}LinkedDoc {
docExtId (string) Идентификатор документа во внешней системе (UUID),
type (string) Тип связанного документа

Пример запроса

{
   "authPersonName":"Иванов Иван Иванович",
   "authPersonTelfax":"4955005550",
   "bankComment":"string",
   "bankStatus":"string",
   "bfAttachments":[
      {
         "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "fileName":"SB_7718830000_40702810038290010000_T18.txt"
      }
   ],
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "number":"1",
   "orgName":"ООО \"ТЕСТ\"",
   "refDocument":{
      "docExtId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "type":"PayDocCur"
   },
   "rootMessage":{
      "docExtId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
      "type":"PayDocCur"
   },
   "subject":"Досыл документа.",
   "text":"Добрый день. Документ отправлен."
}

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

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

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

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

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

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

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

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

Формирование электронной подписи (ГОСТ 2012)

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

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

Пример дайджеста

authPersonName=Иванов Алексей Сергеевич
authPersonTelfax=8(495)1234567
date=2019-04-16
externalId=31663ef5-7975-4016-b0f3-f1d70a4e9c22
orgName=ООО"Риэль"
orgTaxNumber=7730677091
subject=ТЕМА ПИСЬМА
text=ТЕКСТ ПИСЬМА
TABLES
Table=BfAttachments
fileId=31663ef5-7975-4016-b0f3-f1d70a4e9c22
#
fileId=51663ef5-7975-4016-b0f3-f1d70a4e9c22
#

Ресурс /v1/curr-control-messages/to-bank/{externalId}/state

Ресурс позволяет получить статус по отправленному в банк документу.

Шаги

1. Получить AccessToken.

2. Отправить запрос

Для создания запроса на получения статуса запроса «Письмо для целей ВК (в банк)», необходимо отправить GET-запрос (/v1/curr-control-messages/to-bank/{externalId}/state), в котором передать авторизационный токен к данным клиента (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_CONTROL_MESSAGE_TO_BANK.

Модель запроса

Наименование Описание
Параметры заголовка
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'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/curr-control
messages/to-bank/ffffffff-fffa-458e-ad92-fff9497303ba/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 Выгружен Электронный документ выгружен Банком в АБС
PARTSIGNED Частично подписан ЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей. Документ не отправлен в банк, требуется подпись
SIGNED Подписан ЭД подписан предусмотренным для него комплектом подписей. Документ не отправлен в банк, требуется отправить
Документ с этим статусом может быть отправлен для исполнения в банк либо с документа может быть снята подпись (ЭД возвращается к статусу «Частично подписан»)
SUBMITTED Представлен Документ находится в обработке на стороне банка
TRIED_BY_CFE Проверяется ВК Документ проверяется ВК
Окончательные статусы/Прекратить опрос
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
INVALIDEDS ЭП/АСП не верна Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
REFUSED_BY_CFE Отказан ВК Документ отказан валютным контролем
REFUSEDBYABS Отказан АБС Документ отказан АБС
REQUISITEERROR Ошибка реквизитов ЭД не прошел проверки при приеме на стороне Банка
Окончательные(Успешные) статусы/Прекратить опрос
ACCEPTED_BY_CFE Принят ВК Документ принят валютным контролем

Ресурс /v1/curr-control-messages/from-bank

Ресурс позволяет получить письмо для целей ВК (из банка) по собственной/дочерней организации.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения входящих писем ВК необходимо отправить GET-запрос (/curr-control-messages/from-bank), в котором передать ключ доступа к собственной организации/дочерней организации (Access Token), дату за которую необходимо получить письмо (messageDate) и номер запрашиваемой страницы (page=1). Ключ безопасности передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_CONTROL_MESSAGE_FROM_BANK.

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

Наименование Описание
Параметры заголовка
Authorization (String) Access token, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
messageDate (String) Дата письма
page (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
/curr-control-messages/from-bank?messageDate=2019-10-10&page=1'

Модель ответа

Наименование Описание
CurrControlMessagesFromBank {
_links (Array[Link], optional) Ссылки на связанные ресурсы,
messages (Array[CurrControlMessageFromBank], optional) Письма для целей ВК (из банка)
}Link {
href (string) Абсолютный или относительный адрес,
rel (string) Отношение ссылки к текущей сущности (next, prev)
}CurrControlMessageFromBank {
attachments (Array[Attachment], optional)
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional, read only) Статус документа,
bfAttachments (Array[BfAttachment], optional) Данные о файлах, связанных с письмом для целей ВК,
date (string) Дата составления документа,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
externalId (string) Идентификатор документа в организации-партнере,
number (string, optional) Номер документа,
refDocument (LinkedDoc, optional) Документ ВК, по которому ведется переписка,
rootMessage (LinkedDoc, optional) Письмо ВК, на которое данное письмо является ответом,
subject (string) Тема письма,
text (string) Текст письма
}Attachment {
content (Array[string], optional) Вложение закодированное в Base64,
mimeType (string, optional) Тип формат файла,
name (string, optional) Имя файла
}BfAttachment {
fileId (string, optional) Уникальный идентификатор файла,
fileName (string, optional, read only) Имя файла
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}LinkedDoc {
docExtId (string) Идентификатор документа во внешней системе (UUID),
type (string) Тип связанного документа

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

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "messages":[
      {
         "attachments":[
            {
               "content":"dGVzdA==",
               "mimeType":"image/jpeg",
               "name":"тест.jpg"
            }
         ],
         "bankComment":"string",
         "bankStatus":"string",
         "bfAttachments":[
            {
               "fileId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
               "fileName":"SB_7718830000_40702810038290010000_T18.txt"
            }
         ],
         "date":"2018-12-31",
         "digestSignatures":[
            {
               "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
               "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
            }
         ],
         "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "number":"1",
         "refDocument":{
            "docExtId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
            "type":"PayDocCur"
         },
         "rootMessage":{
            "docExtId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
            "type":"PayDocCur"
         },
         "subject":"Досыл документа.",
         "text":"Добрый день. Документ отправлен."
      }
   ]
}
Необходимо запрашивать постранично входящие данные, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить href c признаком "rel": "next", что будет означать, что следующей страницы нет. На запрос первой страницы в ответе вернется письмо (Если существуют входящее письмо за выбранную дату) и контейнер links с параметром (href) на следующую страницу и признаком "rel": "next". На запрос второй страницы в ответе вернется письмо из банка и контейнер links с параметром (href) на следующую и предыдущую страницы и признаками: "rel": "prev", "rel": "next". Получение последующих страниц производится по аналогии.

Ресурс /v1/currency-notices

Ресурс позволяет получить документы по счетам организации за выбранную дату.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения документов необходимо отправить GET-запрос (/v1/currency-notices), в котором передать авторизационный токен организации (Access Token), номер счета (accountNumber), дату выписки (Date) и номер запрашиваемой страницы (Page=1). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURRENCY_NOTICES.

Модель запроса

Наименование Описание
Параметры заголовка
Authorization (String) Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
accountNumber (Date) Номер транзитного счета
noticesDate (String) Дата уведомления (yyyy-mm-dd)
page (Number) Номер страницы
По умолчанию 100 уведомлений на странице

Пример запроса

curl -X GET --header 'Accept: application/json' --header 
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/currency-notices?
accountNumber=40702810340399653236¬icesDate=2019-06-26&page=1'
Необходимо запрашивать постранично данные операции, начиная с первой страницы и опрашивать следующую до того момента, как в полученном ответе перестанет приходить href c признаком "rel": "next", что будет означать, что следующей страницы нет. На запрос первой страницы в ответе вернется список операций (Если существуют операции за выбранную дату и счет) и контейнер links с параметром (href) на следующую страницу и признаком "rel": "next". На запрос второй страницы в ответе вернется список операций и контейнер links с параметром (href) на следующую и предыдущую страницы и признаками: "rel": "prev", "rel": "next". Получение последующих страниц производится по аналогии.

Модель ответа

Наименование Описание
CurrencyNotices {
_links (Array[Link], optional) Ссылки на связанные ресурсы,
notices (Array[CurrencyNotice], optional) Уведомления о поступлении денежных средств на транзитный валютный счет
}Link {
href (string) Абсолютный или относительный адрес,
rel (string) Отношение ссылки к текущей сущности (next, prev)
}CurrencyNotice {
bankName (string, optional, read only)
bic (string, optional) БИК,
branchName (string, optional) Подразделение банка,
currencyName (string, optional) Буквенный ISO-код валюты,
date (string, optional) Дата документа,
dateReceipt (string, optional) Срок предоставления СВО и подтверждающих документов,
docSum (number, optional) Сумма,
externalId (string, optional) Идентификатор документа,
number (string, optional) Номер документа,
transferDate (string, optional) Дата зачисления,
transitAccountNumber (string, optional) Номер транзитного счета

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

{
   "_links":[
      {
         "href":"?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
         "rel":"next"
      }
   ],
   "notices":[
      {
         "bankName":"ПАО СБЕРБАНК",
         "bic":"044525225",
         "branchName":"ДО №1654 Московского банка ПАО Сбербанк",
         "currencyName":"USD",
         "date":"2018-12-31",
         "dateReceipt":"2018-12-31",
         "docSum":1.01,
         "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
         "number":"21053520",
         "transferDate":"2018-12-31",
         "transitAccountNumber":"40802840600000200000"
      }
   ]
}

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

Справочник типов документов

Тип документа Наименование документа
401060 Платежное поручение
PayDocCur Поручение на перевод валюты
MandatorySale Распоряжение об осуществлении обязательной продажи
ConfDocInq_138I Справка о подтверждающих документах по 181-И
CurrencyNotices Уведомление о зачислении (поступлении) иностранной валюты на транзитный валютный счет
CurrControlInfoReq Запрос информации ВК
CurrencyOperationDetails Сведения о валютной операции
ContractChangeApplication Заявление о внесении изменений в I раздел ВБК
InternalControlStatement Ведомость банковского контроля

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

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

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

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

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

Код возврата Описание кода возврата Причина возникновения
200 (GET-запрос) ОК
201 (POST-запрос) CREATED
Создан
400 DESERIALIZATION_FAULT
Неверный формат запроса Неверный формат запроса
WORKFLOW_FAULT
Для внешнего сервиса недоступны операции по счету: 40702810ХХХХХХХХХХХХ Для внешнего сервиса недоступны операции по счету:

счет не добавлен в список разрешенных в оферте;
внешний сервис заблокирован в СББОЛ;
счет указан неверно.

Отсутствует доступный открытый рублевый расчетный счет у организации плательщика
Документ с такими реквизитами уже существует Документ с такими реквизитами уже существует. Проверка по номер документа в течении года.
Не указан идентификатор сертификата подписи Не указан идентификатор сертификата подписи(параметр kid заголовка JWS)
Некорректный формат параметра kid заголовка JWS Некорректный формат параметра kid заголовка JWS(ожидается UUID)
VALIDATION_FAULT
Ошибка валидации Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определенным в модели.
SIGN_CHECK_EXCEPTION
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным Ошибка возникает, если не удалось установить подлинность подписи
401 UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан некорректный или просроченный access_token.
403 ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещен У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI, доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен Проводятся технические работы