ym88659208ym87991671
Покупка и конверсия валюты | Документация для разработчиков

Покупка и конверсия валюты

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

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

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

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

Ресурс /v1/curr-buy

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

Шаги

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

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

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

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

5. Получить документ.

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token собственной/дочерней организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Параметры тела запроса
CurrBuy {
addInfo (string, optional)Дополнительная информация ,
authPersonName (string)ФИО ответственного лица ,
authPersonTelfax (string)Телефон ответственного лица ,
bankComment (string, optional, read only)Банковский комментарий к статусу документа ,
bankStatus (string, optional, read only)Статус документа ,
chargeAmount (Amount, optional)Информация о комиссии ,
commissionAccount (string, optional)Счет списания комиссионного вознагражденияю.
В случае указания course=centralBankRateConditions значение обязательное,
commissionBankBic (string, optional)БИК банка списания комиссии.
В случае указания course=centralBankRateConditions значение обязательное ,
course (string)Курс сделки = ['sberbankRateConditions', 'centralBankRateConditions', 'individualRateConditions']
stringEnum: "sberbankRateConditions", "centralBankRateConditions", "individualRateConditions",
creditAmount (number, optional)Сумма зачисления (не заполняется, если заполнено поле debitAmount) ,
date (string)Дата составления документа ,
debitAmount (number, optional)Сумма списания
Поле не заполняется:
- в случае покупки по курсу centralBankRateConditions,
- если заполнено поле creditAmount при покупке по курсу sberbankRateConditions или individualRateConditions ,
digestSignatures (Array[Signature], optional)Электронные подписи по дайджесту документа ,
externalId (string)Идентификатор документа, присвоенный сервисом (UUID) ,
factCreditAmount (Amount, optional)Информация о купленной валюте ,
factDebitAmount (Amount, optional)Информация о проданной валюте ,
factRate (number, optional)Фактический курс сделки ,
individualRate (number, optional)Значение индивидуального курса (заполняется если course=individualRateConditions) ,
number (string, optional)Номер документа ,
payeeAccount (string)Счет зачисления валюты ,
payeeBankBic (string, optional)БИК банка зачисления (не заполняется если указан payeeBankSwiftCode),
payeeBankSwiftCode (string, optional)SWIFT-код банка зачисления валюты ,
payerAccount (string)Счет списания валюты ,
payerBankBic (string)БИК банка списания ,
valueDate (string, optional)Дата валютирования
}Amount{
amount (number, optional)Сумма ,
currencyName (string, optional)Буквенный ISO-код валюты
}Signature{
base64Encoded (string)Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string)Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
"addInfo":"Дополнительная информация",
"authPersonName":"Иванов Иван Иванович",
"authPersonTelfax":"4955005550",
"bankComment":"string",
"bankStatus":"string",
"chargeAmount":{
"amount":1.01,
"currencyName":"USD"
},
"commissionAccount":"40802810600000200000",
"commissionBankBic":"044525225",
"course":"sberbankRateConditions",
"creditAmount":1.01,
"date":"2018-12-31",
"debitAmount":1.01,
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"factCreditAmount":{
"amount":1.01,
"currencyName":"USD"
},
"factDebitAmount":{
"amount":1.01,
"currencyName":"USD"
},
"factRate":1.0001,
"individualRate":5.5678,
"number":"1",
"payeeAccount":"40802840600000200000",
"payeeBankBic":"044525225",
"payeeBankSwiftCode":"SABRRUMM",
"payerAccount":"40802840600000200000",
"payerBankBic":"044525225",
"valueDate":"2018-12-31"
}

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

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

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

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

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

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

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

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

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

Если в параметре course указаны sberbankRateConditions, то поля commissionAccount  и commissionBankBic необходимо исключить из запрос, если в параметре course указывается centralBankRateConditions, то поля commissionAccount  и commissionBankBic необходимо добавить в запрос.

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

Наименование поляОписание поляПример
addInfoДополнительная информацияДополнительная информация тест
authPersonNameФИО ответственного лицаШагов Вадим Юрьевич
authPersonTelfaxТелефон ответственного лица79161965789
commissionAccount (optional)Счет списания комиссионного вознаграждения47405810555555555555
commissionBankBic (optional)БИК банка списания комиссии044525225
courseКурс сделкиsberbankRateConditions
creditAmountСумма зачисления22
dateДата документа2019-05-23
debitAmountСумма списания33
externalIdИдентификатор документа, присвоенный сервисом31663ef5-7975-4016-b0f3-f1d70a4e9c22
individualRateЗначение индивидуального курса5.5678
payeeAccountСчет зачисления валюты88888978655555555555
payeeBankBicБИК банка зачисления044525225
payeeBankSwiftCodeSWIFT-код банка зачисления валютыSUBRBRS10DF
payerAccountСчет списания валюты47405840776676767767
payerBankBicБИК банка списания044525225

Пример:

addInfo=Дополнительная информация тест
authPersonName=Шагов Вадим Юрьевич
authPersonTelfax=79161965789
commissionAccount=47405810555555555555
commissionBankBic=044525225
course=sberbankRateConditions
creditAmount=22
date=2019-05-23
debitAmount=33
externalId=31663ef5-7975-4016-b0f3-f1d70a4e9c22
individualRate=5.5678
payeeAccount=88888978655555555555
payeeBankBic=044525225
payeeBankSwiftCode=SUBRBRS10DF
payerAccount=47405840776676767767
payerBankBic=044525225

Ресурс /v1/curr-buy/{externalId}/state

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

Шаги

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
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/pay-doc-cur
/22a6dd81-103a-4d3a-8e9b0ba4b527f010/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Принят АБС
ACCEPTED_BY_CFEПринят ВК
CARD2Картотека №2
CREATEDСоздан
DELAYEDПриостановлен
DELIVEREDДоставлен
EXPORTEDВыгружен
FRAUDSMSТребуется подтверждение СМС-паролем
FRAUDREVIEWНа проверке у специалиста банка
FRAUDSENTОтправлен во ФРОД
FRAUDALLOWОдобрен ФРОД
PARTSIGNEDЧастично подписан
PROCESSEDОбработан
PROCESSINGВ обработке
RATE_CONFIRMATIONНа подтверждении курса
SIGNEDПодписан
TRIED_BY_CFEПроверяется ВК
Окончательные статусы/Прекратить опрос
CHECKERRORОшибка контроля
CHECKERROR_BANKОшибка контроля, Банк
INVALIDEDSЭП/АСП не верна
FRAUDDENYОтвергнут ФРОД
PROCESSERRORОтказан
REQUISITEERRORОшибка реквизитов
REFUSEDBYBANKОтвергнут Банком
REFUSEDBYABSОтказан АБС
RECALLОтозван
RECALL_BY_BANKОтозван Банком
REFUSED_BY_CFEОтказан ВК
UNABLE_TO_RECEIVEОшибка при приеме
Окончательные(Успешные) статусы/Прекратить опрос
IMPLEMENTEDИсполнен

Ресурс /v1/curr-buy/{externalId}

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

Шаги

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

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

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

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

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

НаименованиеОписание
Параметры заголовка
Authorization (String)Access token, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-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/curr-buy/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6'

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

Соответствует модели запроса и ответа /v1/curr-buy.

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

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

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

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

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

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

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

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

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

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