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

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

• Тестовый контур 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.

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

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

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'

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

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

{
   "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 (все поля обязательны):

Можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа:

• Если ЭП переданы в 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

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

Ресурс /v1/collection-orders/{externalId}/state позволяет получить статус отправленного запроса на создание рублевого инкассового поручения.

Шаги:

1. Получить AccessToken.
2. Отправить запрос.

Авторизация

Для получения статуса необходимо отправить GET-запрос (/v1/collection-orders/{externalId}/state), в котором передать авторизационный токен собственной организации (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.

Чтобы получить доступ к ресурсу, необходимо передать в scope сервис COLLECTION_ORDERS.

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

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

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"

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

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

{
    "bankStatus": "CREATED",
    "bankComment": null,
    "actualHoldAmount": null
}

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

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

Ресурс /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 преобразования:

• Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.

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

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

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