Покупка и конверсия валюты
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
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 |
payeeBankSwiftCode | SWIFT-код банка зачисления валюты | 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 преобразования:
- Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.
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 | ||
Сервис временно недоступен | Проводятся технические работы |