Инкассовые поручения

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

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

Обновлено 20 апреля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Популярные

Популярные

Инкассовые поручения

Создание поручения

Шаги

Авторизация

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

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

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

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

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

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

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

Получение статуса поручения

Шаги

Авторизация

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

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

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

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

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

Получение отправленного поручения

Шаги

Авторизация

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

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

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

note

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

Формирование компактной сериализации JWS

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