Продажа валюты
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443
Промышленный контур
https://fintech.sberbank.ru:9443
Ресурс /v1/curr-sell
Ресурс позволяет создавать документ Продажа валюты.
Шаги
1. Получить AccessToken.
2. Сформировать ЭП.
3. Отправить запрос.
4. Получить статус.
5. Получить документ.
Для создания документа необходимо отправить POST-запрос (/v1/curr-sell), в котором передать авторизационный токен организации (Access Token) и реквизиты документа. Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_SELL
.
Модель запроса и ответа
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token собственной/дочерней организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Параметры запроса | |
CurrSell { | |
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) | Сумма списания (не заполняется, если заполнено поле creditAmount). В случае указания course=sberbankRateConditions, значение обязательное , |
digestSignatures (Array[Signature], optional) | Электронные подписи по дайджесту документа , |
externalId (string) | Идентификатор документа, присвоенный сервисом (UUID) , |
factCreditAmount (Amount, optional, read only) | Информация о купленной валюте , |
factDebitAmount (Amount, optional, read only) | Информация о проданной валюте , |
factRate (number, optional) | Фактический курс сделки , |
individualRate (number, optional) | Значение индивидуального курса , |
number (string, optional) | Номер документа , |
payeeAccount (string) | Счет зачисления валюты , |
payeeBankBic (string) | БИК банка зачисления , |
payeeBankCorrAccount (string, optional) | Корр. счет банка счета зачисления валюты, |
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",
"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",
"number":"1",
"payeeAccount":"40802840600000200000",
"payeeBankBic":"044525225",
"payeeBankCorrAccount":"30101810400000000225",
"payerAccount":"40802840600000200000",
"payerBankBic":"044525225"
}
Передача электронной подписи вместе с документом
Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:
Наименование поля | Описание поля | Пример |
---|---|---|
base64Encoded (string) | Значение ЭП документа | HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w== |
certificateUuid (string) | Идентификатор сертификата, использованного при создании ЭП (можно узнать, обратившись к ресурсу /v1/crypto или /v1/crypto/eio) | 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6 |
В документе можно передать одну или две электронных подписи вместе с реквизитами создаваемого документа. Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл. Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.
Документ может быть подписан следующими наборами подписей:
- одна (единственная) подпись;
- первая и вторая подписи.
При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.
Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.
Теги дайджеста должны быть отсортированы по алфавиту. В дайджесте не указываются значения number и блок linkedDocs.
Формат дайджеста
Наименование поля | Описание поля | Пример |
---|---|---|
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 | 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-sell/{externalId}/state
Ресурс позволяет получить статус ранее отправленного электронного документа.
Шаги
1. Получить AccessToken.
2. Отправить запрос
Для получения статуса документа необходимо отправить GET-запрос (/v1/curr-sell/{externalId}/state),в котором передать авторизационный токен организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_SELL
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
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/curr-sell/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6/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-sell/{externalId}
Ресурс позволяет получить по ранее отправленному электронному документу Продажа валюты информацию о комиссии, проданной валюте, дате валютирования, фактическом курсе сделки.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения реквизитов необходимо отправить GET-запрос (/v1/curr-sell/{externalId}), в котором передать авторизационный токен организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис CURR_SELL
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
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/curr-sell/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6'
Модель ответа
Соответствует модели запроса и ответа /v1/curr-sell.
Дополнительная информация
Параметры НДС
Для корректной работы необходимо передавать параметры в следующем сочетании:
- Если блок 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 состоит из трёх частей:
- Заголовок (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 | ||
Сервис временно недоступен | Проводятся технические работы |