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

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

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

Ресурс /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 Дата составления документа 31.12.2018
deliveryKind Вид платежа электронно
operationCode Код операции 1
payeeAccount Номер счёта получателя 4,08028E+19
payeeBankBic БИК получателя 44525225
payeeBankCorrAccount Корсчёт банка получателя 3,01018E+19
payeeInn ИНН получателя 7707083893
payeeKpp КПП получателя 222201001
payeeName Полное наименование получателя платежа Общество с ограниченной ответственностью "Клиент"
payerAccount Счёт плательщика 4,08028E+19
payerBankBic БИК плательщика 44525225
payerBankCorrAccount Корсчёт банка плательщика 3,01018E+19
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"
    }
    В поле "Назначение платежа" необходимо обязательно отправлять "НДС не облагается".
  • При выбранном "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 преобразования:

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, чтобы сообщить нам о ней