Распоряжение на перевод с транзитного счета

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

Ресурс /v1/orders-mandatory-sale

Ресурс позволяет создать распоряжения на перевод с транзитного счета по собственной/дочерней организации.

Шаги:

1. Получить AccessToken

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

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

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

Для создания распоряжения на перевод с транзитного счета необходимо отправить POST-запрос (/v1/orders-mandatory-sale), в котором передать авторизационный токен к данным собственной/дочерней организации (Access Token) и реквизиты документа. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token собственной/дочерней организации, полученный через SSO.
Пример: Bearer 8190f687-c916-453b-9d68-0ce22f4f3f9d-1
Параметры запроса
OrderMandatorySale {
addInfo (string, optional) Примечание ,
authPersonName (string, 60) ФИО ответственного лица ,
authPersonTelfax (string, 40) Телефон ответственного лица ,
bankBic (string, 9) БИК банка ,
bankName (string) Наименование банка ,
comment (string, optional, read only) Комментарий ,
customerInn (string, ^([0-9]{10}|[0-9]{12}|0)$) ИНН клиента ,
customerName (string, 350) Полное наименование организации клиента ,
customerOkpo (string, optional, ^[0-9]{8,10}) ОКПО клиента ,
date (string, YYYY-MM-DD) Дата составления документа ,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа ,
docAccount (string, 20) Транзитный валютный счет ,
employee (string, optional, read only) Исполнитель ,
externalId (string) Идентификатор документа, присвоенный партнером (UUID) ,
linkedDocs (Array[LinkedDoc], optional) Связанные документы ,
noticeDocDate (string, optional, YYYY-MM-DD) Дата уведомления о поступлении денежных средств на транзитный счет ,
noticeDocNum (string, optional, 15) Номер уведомления о поступлении денежных средств на транзитный счет ,
noticeDocSum (AmountCurrency, optional) Сумма и валюта поступивших средств. Информация из уведомления ,
number (string, optional, 6) Номер документа ,
receiptDate (string, optional, read only) Дата поступления документа в банк ,
transferCurrency (MandatorySaleTransf, optional) Зачисление ,
voluntarySale (VoluntarySale, optional) Необязательная продажа
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}LinkedDoc {
docExtId (string) Идентификатор документа во внешней системе (UUID) ,
type (string) Тип связанного документа ( СВО - CurrencyOperationDetails, СПД - ConfDocInq_138I, Уведомления о поступлении денежных средств на транзитный валютный счет - CurrencyNotices)
}AmountCurrency {
amount (number (18,2)) Сумма ,
currencyCode (string, 3) Цифровой код валюты ,
currencyName (string, 3) Буквенный ISO-код валюты,
}MandatorySaleTransf {
accountNum (string, 20) Счет для зачисления валюты ,
bankSwiftCode (string, optional, 11) SWIFT код банка ,
bankSwiftName (string, optional, 160) SWIFT наименование банка ,
chargedCur (Amount, optional, read only) Списано валюты при переводе средств ,
commission (Amount, optional, read only) Комиссия при переводе средств ,
transferAmount (Amount) Сумма зачисления ,
transferTo (string) Тип зачисления валютного перевода = ['orgAccount', 'bankAccount', 'prcomAccount']
stringEnum: "orgAccount", "bankAccount", "prcomAccount"
orgAccount - на наш текущий валютный счет в Сбербанке России; bankAccount - на счет в другом уполномоченном банке; prcomAccount - на счет принципала и комитента
valueDate (string, optional, read only) Дата валютирования перевода средств
}VoluntarySale {
accountNum (string, 20) Счет для зачисления рублей ,
accountType (string) Тип зачисления = ['orgAccount', 'bankAccount'] stringEnum: "orgAccount", "bankAccount", 
orgAccount - на наш текущий валютный счет в Сбербанке России, bankAccount - на счет в другом уполномоченном банке
bankBic (string, 9) БИК банка ,
bankCorrAccount (string, optional) Корр. счет банка счета зачисления валюты,
bankName (string, 160) Наименование банка счета, куда перечисляются рублевые средства от необязательной продажи валюты ,
chargedCur (Amount, optional, read only) Списано валюты при необязательной продаже ,
comissionAccount (string, optional, 20) Счет для списания комиссии (рублевый). Параметр заполняется, если dealType=centralBankRateConditions ,
comissionBankBic (string, optional, 9) БИК банка, в котором открыт счет для списания комиссий. Параметр заполняетя, если dealType=centralBankRateConditions,
comissionBankName (string, optional, 160) Наименование банка, в котором открыт счет для списания комиссий ,
commission (Amount, optional, read only) Комиссия при необязательной продаже ,
dealType (string) Выбор курса продажи = ['sberbankRateConditions', 'centralBankRateConditions']
stringEnum: "sberbankRateConditions", "centralBankRateConditions",
sberbankRateConditions - Сделка по курсу Сбербанка; centralBankRateConditions - Сделка по курсу Банка России с взиманием комиссионного вознаграждения
enrolledRub (number, optional, read only) Зачислено рублей при необязательной продаже,
rate (number, optional, read only) Курс необязательной продажи ,
sellAmount (Amount) Сумма необязательной продажи,
valueDate (string, optional, read only) Дата валютирования необязательной продажи
}Amount {
amount (number(18,2), optional) Сумма,
currencyName (string, optional, 3) Буквенный ISO-код валюты
}

Пример:

{
   "number":"644",
   "date":"2019-11-25",
   "externalId":"1fdc2990-ab07-4239-ac79-683e6b9c529b",
   "authPersonName":"Романенко Иван",
   "authPersonTelfax":"79161234567",
   "addInfo":"Распоряжение на перевод с транзитного счета",
   "customerInn":"7723879499",
   "customerOkpo":"17939827",
   "customerName":"ООО 'ВЖИК'",
   "docAccount":"40702840538001001754",
   "bankBic":"044525225",
   "bankName":"ПАО СБЕРБАНК",
   "noticeDocNum":"04093707",
   "noticeDocDate":"2019-09-11",
   "noticeDocSum":{
      "amount":35,
      "currencyCode":"840",
      "currencyName":"USD"
   },
   "voluntarySale":{
      "dealType":"centralBankRateConditions",
      "sellAmount":{
         "amount":15,
         "currencyName":"USD"
      },
      "accountNum":"40702810538000006159",
      "accountType":"orgAccount",
      "bankBic":"044525225",
      "bankCorrAccount":"30101810400000000225",
      "bankName":"ОАО \"СБЕРБАНК РОССИИ\"",
      "comissionAccount":"40802810600000200000",
      "comissionBankBic":"044525225",
      "comissionBankName":"ОАО \"СБЕРБАНК РОССИИ\""
   },
   "transferCurrency":{
      "transferTo":"orgAccount",
      "accountNum":"40702840238000001754",
      "bankSwiftCode":"044525225",
      "bankSwiftName":"ОАО \"СБЕРБАНК РОССИИ\"",
      "transferAmount":{
         "amount":20.00,
         "currencyName":"USD"
      }
   }
}

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

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

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

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

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

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

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

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

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

Если какой-либо из необязательных параметров не передается, то в формировании дайджеста он также не участвует. Теги дайджеста должны быть отсортированы по алфавиту. В дайджесте не указываются значения number и блок linkedDocs.

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

Наименование поля Описание поля Пример
authPersonName ФИО ответственного лица Петров Петр Иванович
authPersonTelfax Телефон ответственного лица 79263689379
addInfo Дополнительная информация АБВ123
bankBic Бик Банка 44525225
bankName Наименование банка ПАО Сбербанк 1469
customerInn ИНН организации партнера 2,22201E+11
customerName Полное наименование организации клиента Организация
customerOkpo ОКПО Клиента 222221001
date Дата создания документа по местному времени в формате YYYY-MM-DD 16.05.2019
docAccount Номер транзитного валютного счета 4,08028E+19
externalId Идентификатор документа, присвоенный партнером (UUID) 75d8d497-05cc-4cc6-9b78-070ae0a605fd
noticeDocDate Дата уведомления о поступлении денежных средств на транзитный счет , YYYY-MM-DD 17.05.2019
noticeDocNum Номер уведомления о поступлении денежных средств на транзитный счет 13242
noticeDocSum.amount Сумма поступивших средств. Информация из уведомления. 01.янв
noticeDocSum.currencyCode Цифровой код валюты. Информация из уведомления. 840
noticeDocSum.currencyName ISO-код валюты договора. Информация из уведомления. USD
transferCurrency.accountNum Счет для зачисления валюты 4,08028E+19
transferCurrency.bankSwiftCode Swift код банка SABRRUMM
transferCurrency.bankSwiftName SWIFT наименование банка SBERBANK
transferCurrency.transferAmount.amount сумма зачисления 456.333
transferCurrency.transferAmount.currencyName ISO-код валюты зачисления USD
transferCurrency.transferTo Тип зачисления валютного перевода orgAccount
voluntarySale.accountNum Счет для зачисления рублей 4,08028E+19
voluntarySale.accountType Тип зачисления orgAccount
voluntarySale.bankBic БИК банка 44525225
voluntarySale.bankName Наименование банка счета, куда перечисляются рублевые средства от необязательной продажи валюты Отделение №1469 ПАО ВТБ
voluntarySale.comissionAccount Счет для списания комиссии (рублевый) 4,08028E+19
voluntarySale.comissionBankBic БИК банка, в котором открыт счет для списания комиссий 44525225
voluntarySale.comissionBankName Наименование банка, в котором открыт счет для списания комиссий Отделение №1469 ПАО ВТБ
voluntarySale.dealType Выбор курса продажи 2
voluntarySale.sellAmount.amount Сумма необязательной продажи 01.янв
voluntarySale.sellAmount.currencyName ISO-код валюты необязательной продажи USD

Пример:

authPersonName=Петров Петр Иванович
authPersonTelfax=+79263689379
addInfo=АБВ123
bankBic=44525225
bankName= ПАО Сбербанк 1469
customerInn=222201236445
customerOkpo=222221001
customerName=Организация
date=2019-05-16
docAccount=40802810600000200000
externalId=75d8d497-05cc-4cc6-9b78-070ae0a605fd
noticeDocDate=2019-05-17
noticeDocNum=13242
noticeDocSum.amount=1.01
noticeDocSum.currencyCode=840
noticeDocSum.currencyName=USD
transferCurrency.accountNum=40802840600000200000
transferCurrency.bankSwiftCode=SABRRUMM
transferCurrency.bankSwiftName=SBERBANK
transferCurrency.transferAmount.amount=456.333
transferCurrency.transferAmount.currencyName=USD
transferCurrency.transferTo=orgAccount
voluntarySale.accountNum =40802840600000200000
voluntarySale.accountType=orgAccount
voluntarySale.bankBic=044525225
voluntarySale.bankName=Отделение №1469 ПАО ВТБ
voluntarySale.comissionAccount=40802840600000200000
voluntarySale.comissionBankBic=044525225
voluntarySale.comissionBankName=Отделение №1469 ПАО ВТБ
voluntarySale.dealType=2
voluntarySale.sellAmount.amount=1.01
voluntarySale.sellAmount.currencyName=USD

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

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

Ресурс /v1/orders-mandatory-sale/{externalId}/state

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

Шаги:

1. Получить AccessToken

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

Для получения статуса документа необходимо отправить GET-запрос (/v1/orders-mandatory-sale/{externalId}/state), в котором передать авторизационный токен к данным собственной/дочерней организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
Параметры запроса
externalId String Идентификатор документа, присвоенный клиентом

Пример:

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/orders-mandatory
sale/22a6dd81-123a-4d3a-8e9b-0ba4b527f010/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 Подписан
Окончательные статусы/Прекратить опрос
ACCEPTED_BY_CFE Принят ВК
INVALIDEDS ЭП/АСП не верна
REQUISITEERROR Ошибка реквизитов
REFUSEDBYABS Отказан АБС
REFUSED_BY_CFE Отказан ВК
UNABLE_TO_SEND_ATT Ошибка выгрузки в ЕСМ
Окончательные(Успешные) статусы/Прекратить опрос
IMPLEMENTED Исполнен

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

Ресурс /v1/orders-mandatory-sale/{externalId}

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

Шаги:

1. Получить AccessToken

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

Для получения документа необходимо отправить GET-запрос (/v1/orders-mandatory-sale/{externalId}), в котором передать авторизационный токен к данным собственной/дочерней организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование Описание
Параметры заголовка
Authorization String
Access token, полученный через SSO.
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры запроса
externalId String
Идентификатор документа, присвоенный сервисом

Пример:

curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/fintech/api/v1/orders-mandatory-sale/40663ef5-7975-4016-b0f3-f1d70a4e9c22'

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

Соответствует модели запроса и ответа /v1/orders-mandatory-sale

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

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

Параметры НДС

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

  • Если блок vat не указан, то по умолчанию будут присвоены и придут в ответе на запрос следующие значения:
"vat": {
"type": "NO_VAT",
"rate": "0",
"amount": "0.00"
}
В поле "Назначение платежа" необходимо обязательно отправлять "НДС не облагается".
  • При выбранном "type":"INCLUDED" (НДС включен в сумму платежа) в атрибуте "amount" необходимо указать сумму НДС.
    Атрибут "rate" должен принимать только значения 10, 20.
    В поле "Назначение платежа" необходимо обязательно указать посчитанное значение НДС.
    Пример ПРАВИЛЬНОГО заполнения:
    НДС_10_%_-_100.63 рублей (нижнее подчеркивание является признаком пробела, символ проставлять не нужно).
    Если процентное значение не указано, то дефис перед суммой указывать не нужно: НДС_100.63 рублей.
  • При выбранном "type":"MANUAL" (Ручной ввод НДС) атрибут "amount" указывать не обязательно, но в этом случае по умолчанию сумма НДС примет значение 0 рублей.
    Если же атрибут "amount" указывается в запросе, то в нем нужно указать желаемое значение НДС, соответствующее формату.
    Если процентное значение не указано, то дефис перед суммой указывать не нужно:
    НДС_100.63 рублей.

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

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
Сервис временно недоступен Проводятся технические работы

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней