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

Обновлено 29 февраля 2024

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

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

Ресурс /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 (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 код банка Заполняется, если transferTo = НЕ orgAccount ,
bankSwiftName (string, optional, 160)	SWIFT наименование банка Заполняется, если transferTo = НЕ orgAccount ,
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 {	Блок обязателен к заполнению, если блок transferCurrency не заполнен
accountNum (string, 20)	Счет для зачисления рублей ,
accountType (string)	Тип зачисления = ['orgAccount', 'bankAccount'] stringEnum: "orgAccount", "bankAccount", orgAccount - на наш текущий валютный счет в Сбербанке России, bankAccount - на счет в другом уполномоченном банке
bankBic (string, 9)	БИК банка ,
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",
      "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` или `/v1/crypto/eio)`	22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

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

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

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

При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.

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

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

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

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

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

authPersonName=Петров Петр Иванович
authPersonTelfax=+79263689379
addInfo=АБВ123
bankBic=044525225
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=centralBankRateConditions
voluntarySale.sellAmount.amount=1.01
voluntarySale.sellAmount.currencyName=USD

Ресурс /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://iftfintech.testsbi.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`	Принят ВК
`CHECKERROR`	Ошибка контроля
`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://iftfintech.testsbi.sberbank.ru:9443/fintech/api/fintech/api/v1/orders-mandatory-sale/40663ef5-7975-4016-b0f3-f1d70a4e9c22'

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

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

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

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

Content-Type может содержать одно из двух значений:

application/json – запрос без подписи
application/jose – запрос, подписанный транспортной подписью

Если Content-Type имеет значение application/jose, то запрос должен содержать данные в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из трёх частей:

Заголовок (Header) - определяет алгоритм подписи и тип токена
Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
Электронная подпись (Signature) - вычисляется с использованием приватного ключа клиента

Base64Url(Header) || ’.’ ||  Base64Url(Payload) || ’.’ || Base64Url(Signature)

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg (в нашем случае gost34.10-2012) и вычисляется от исходных данных:

Base64Url(Header) || ‘.’ || Base64Url(Payload).

Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).

При кодировании JWS используется преобразование Base64Url. Преобразование можно представить следующим образом:

Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)

функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x,
функция Replace(x,y) заменяет все вхождения символа x на символ y.

Преобразование Base64Url, отличается от Base64 преобразования:

В Base64Url не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

BASE64URL	BASE64
- (minus)	+
_ (underline)	/

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

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

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

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

Шаги﻿

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

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

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

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

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

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

Шаги﻿

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

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

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

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

Возможные статусы﻿

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

Шаги﻿

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

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

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

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

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

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

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

Шаги

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

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

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

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

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

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

Шаги

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

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

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

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

Возможные статусы

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

Шаги

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

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

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

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

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

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