ym88659208ym87991671
Инкассовые поручения | Документация SmartMarket
Skip to main content

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

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

  • Тестовый контур 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 преобразования:

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

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

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

Код возвратаОписание кода возвратаПричина возникновения
200ОК(GET-запрос)
201CREATEDСоздан (POST-запрос)
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
Сервис временно недоступенПроводятся технические работы
Обновлено 20 апреля 2022

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

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