Инкассовые поручения
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://edupirfintech.sberbank.ru:9443
Промышленный контур
https://fintech.sberbank.ru:9443
Создание поручения
Ресурс /v1/collection-orders
позволяет отправить запрос на создание рублевого инкассового поручения для расчетно-кассового обслуживания.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
3. Получить статус.
Авторизация
Для создания рублевого инкассового поручения необходимо отправить POST-запрос (/v1/collection-orders), в котором передать авторизационный токен собственной организации (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис COLLECTION_ORDERS
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Пример запроса
curl -X POST --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/collection-orders'
Модель ответа
Наименование | Описание |
---|---|
CollectionOrder | |
amount (number) | Сумма платежа , |
balancePayment (number) | Сумма остатка платежа , |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа , |
bankStatus (string, optional, read only) | Статус документа , |
date (string) | Дата составления документа , |
deliveryKind (string, optional) | Вид платежа , |
digestSignatures (Array[Signature], optional) | Электронные подписи по дайджесту документа , |
externalId (string) | Идентификатор документа, присвоенный партнером (UUID) , |
fileDate (string, optional, read only) | Дата помещения в картотеку , |
numPartPayment (string, optional, read only) | Номер частичного платежа , |
numPayOrder (string, optional, read only) | Номер платежного ордера , |
number (string, optional) | Номер документа , |
operationCode (string) | Код операции , |
orderDate (string, optional, read only) | Дата платежного ордера , |
payeeAccount (string) | Счет получателя платежа , |
payeeBankBic (string) | БИК получателя платежа , |
payeeBankCorrAccount (string) | Корсчет банка получателя платежа , |
payeeInn (string) | ИНН получателя платежа , |
payeeKpp (string) | КПП получателя платежа , |
payeeName (string) | Полное наименование получателя платежа , |
payerAccount (string) | Счет плательщика , |
payerBankBic (string) | БИК банка плательщика , |
payerBankCorrAccount (string) | Корсчет банка плательщика , |
payerInn (string) | ИНН плательщика , |
payerKpp (string, optional) | КПП плательщика , |
payerName (string) | Полное наименование плательщика , |
priority (string) | Очередность платежа , |
purpose (string) | Назначение платежа , |
sumPartPayment (number) | Сумма частичного платежа , |
vat (Vat, optional) | Данные НДС , |
voCode (string, optional) | Код вида валютной операции |
Signature | |
base64Encoded (string) | Значение электронной подписи, закодированное в Base64 , |
certificateUuid (string) | Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID) , |
Vat | |
amount (number, optional) | Сумма НДС , |
rate (string, optional) | Ставка НДС , |
type (string) | Способ расчета НДС = [INCLUDED , NO_VAT , MANUAL ] stringEnum: INCLUDED , NO_VAT , MANUAL |
Пример ответа
{
"amount":1.01,
"balancePayment":0,
"bankComment":"string",
"bankStatus":"string",
"date":"2018-12-31",
"deliveryKind":"электронно",
"digestSignatures":[
{
"base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"fileDate":"2020-01-30T13:10:23.694Z",
"numPartPayment":"string",
"numPayOrder":"string",
"number":"1",
"operationCode":"01",
"orderDate":"2020-01-30T13:10:23.694Z",
"payeeAccount":"40802810600000200000",
"payeeBankBic":"044525225",
"payeeBankCorrAccount":"30101810400000000225",
"payeeInn":"7707083893",
"payeeKpp":"222201001",
"payeeName":"Общество с ограниченной ответственностью \"Клиент\"",
"payerAccount":"40802810600000200000",
"payerBankBic":"044525225",
"payerBankCorrAccount":"30101810400000000225",
"payerInn":"7707083893",
"payerKpp":"222201001",
"payerName":"Общество с ограниченной ответственностью \"Клиент\"",
"priority":"5",
"purpose":"Оплата заказа №123. НДС нет.",
"sumPartPayment":0,
"vat":{
"amount":1.01,
"rate":"7",
"type":"NO_VAT"
},
"voCode":"61150"
}
Передача электронной подписи
Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature (все поля обязательны):
Наименование | Описание | Пример |
---|---|---|
base64Encoded (string) | Значение ЭП документа | HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w== |
certificateUuid (string) | Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto) | 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6 |
Можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:
- Если ЭП переданы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
- Если ЭП не были переданы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.
Документ может быть подписан следующими наборами подписей:
одна (единственная) подпись;
первая и вторая подписи.
При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.
Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля, когда пользователь Партнера создается в Банке.
Формат дайджеста
Наименование | Описание | Пример |
---|---|---|
amount | Сумма платежа | 100.00 |
date | Дата составления документа | 2018-12-31 |
deliveryKind | Вид платежа | электронно |
operationCode | Код операции | 01 |
payeeAccount | Номер счета получателя | 40802810600000200000 |
payeeBankBic | БИК получателя | 044525225 |
payeeBankCorrAccount | Корсчет банка получателя | 30101810400000000225 |
payeeInn | ИНН получателя | 7707083893 |
payeeKpp | КПП получателя | 222201001 |
payeeName | Полное наименование получателя платежа | Общество с ограниченной ответственностью \"Клиент\" |
payerAccount | Счет плательщика | 40802810600000200000 |
payerBankBic | БИК плательщика | 044525225 |
payerBankCorrAccount | Корсчет банка плательщика | 30101810400000000225 |
payerInn | ИНН плательщика | 7707083893 |
payerKpp | КПП плательщика | 222201001 |
payerName | Полное наименование плательщика | Общество с ограниченной ответственностью \"Клиент\" |
priority | Очередность платежа | 5 |
purpose | Назначение платежа | Оплата заказа №123. НДС нет. |
voCode | Код вида валютной операции | 61150 |
Пример дайджеста
amount=100.00
date=2018-12-31
deliveryKind=электронно
operationCode=01
payeeAccount=40802810600000200000
payeeBankBic=044525225
payeeBankCorrAccount=30101810400000000225
payeeInn=7707083893
payeeKpp=222201001
payeeName=Общество с ограниченной ответственностью \"Клиент\"
payerAccount=40802810600000200000
payerBankBic=044525225
payerBankCorrAccount=30101810400000000225
payerInn=7707083893
payerKpp=222201001
payerName=Общество с ограниченной ответственностью \"Клиент\"
priority=5
purpose=Оплата заказа №123. НДС нет.
voCode=61150
Получение статуса поручения
Ресурс /v1/collection-orders/{externalId}/state
позволяет получить статус отправленного запроса на создание рублевого инкассового поручения.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Авторизация
Для получения статуса необходимо отправить GET-запрос (/v1/collection-orders/{externalId}/state), в котором передать авторизационный токен собственной организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис COLLECTION_ORDERS
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token полученный через SSO Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1 |
Параметры запроса | |
externalId (String) | Идентификатор документа, присвоенный клиентом |
Пример запроса
curl -X GET --header 'Accept: /' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/collection-orders/{externalId}/state/1550ff04-07d6-427b-8c25-27484e8cc830/state'
Модель ответа
Наименование | Описание |
---|---|
DocState { | |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа, |
bankStatus (string, optional) | Статус документа, |
actualHoldAmount (number, optional) | Cумма забронированных денежных средств (рассчитывается с учетом денежных средств, с которых сняли бронирование) |
} |
Пример ответа
{
"bankStatus": "CREATED",
"bankComment": null,
"actualHoldAmount": null
}
Возможные статусы
Код состояния документа | Наименование статуса | Назначение кода состояния |
---|---|---|
Промежуточные статусы/Продолжать опрашивать | ||
ACCEPTED | Принят | Электронный документ принят на стороне Банка |
ACCEPTED_BY_ABS | Принят АБС | Электронный документ был принят к обработке в АБС Банка |
CARD2 | Картотека 2 | Электронный документ передан в картотеку в ожидании средств на счету клиента |
CHECKERROR_BANK | Ошибка контроля, Банк | ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками. |
CREATED | Создан | Документ записан в БД, проверки не выполнялись |
DELAYED | Приостановлен | Обработка электронного документа была приостановлена |
DELIVERED | Доставлен | Запрос доставлен в ДБО и взят в обработку |
EXPORTED | Выгружен | Электронный документ выгружен Банком в АБС |
FRAUDALLOW | Одобрен ФРОД | Проверка во ФРОДЕ прошла успешно, переход на Принят |
FRAUDDENY | Отвергнут ФРОД | Документ отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком» |
FRAUDREVIEW | На проверке у специалиста Банка | Со стороны ФРОД-анализа получен статус документа «На проверке у специалиста Банка» |
FRAUDSENT | Отправлен во ФРОД | Документ отправлен на проверку в АС Fraud-мониторинг |
FRAUDSMS | Требуется подтверждение sms-паролем | Со стороны ФРОД-анализа получен статус документа «Требуется подтверждение sms-паролем» |
PARTSIGNED | Частично подписан | ЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей. |
PROCESSING | В обработке | Клиент сформировал «Заявление об акцепте/частичном акцепте/отказе от акцепта» |
SIGNED | Подписан | ЭД подписан предусмотренным для него комплектом подписей |
SUBMITTED | Представлен | Электронный документ принят ВК |
Окончательные статусы/Прекратить опрос | ||
CHECKERROR | Ошибка контроля | ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками. |
INVALIDEDS | ЭП/АСП не верна | Проверка ЭП под ЭД на стороне Банка дала отрицательный результат |
RECALL | Отозван | Электронный документ был отозван Клиентом по запросу |
REFUSEDBYABS | Отказан АБС | ЭД не прошел проверки в АБС. |
Окончательные(Успешные) статусы/Прекратить опрос | ||
IMPLEMENTED | Исполнен | Электронный документ исполнен Банком |
Получение отправленного поручения
Ресурс /v1/collection-orders/{externalId}
позволяет получить ранее отправленное рублевое инкассовое поручение.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Авторизация
Для получения документа необходимо отправить GET-запрос (/v1/collection-orders/{externalId}), в котором необходимо передать авторизационный токен к данным собственной организации (Access Token) и внешний идентификатор документа. Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис COLLECTION_ORDERS
.
Модель запроса и ответа
Соответствует модели запроса и ответа /v1/collection-orders
.
Дополнительная информация
Параметры НДС
Для корректной работы необходимо передавать параметры в следующем сочетании :
- Если блок vat не указан, то по умолчанию будут присвоены и придут в ответе на запрос следующие значения :
"vat": {
"type": "NO_VAT",
"rate": "0",
"amount": "0.00"
}
note
В поле "Назначение платежа" необходимо обязательно отправлять "НДС не облагается".
При выбранном "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 | CREATED | Создан (POST-запрос) | |
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
, чтобы сообщить нам о ней