Подписки

Сценарий подписок

Сценарий

  1. Получить AccessToken
  2. Получить сведения о клиентах подключенных к подпискам и пакетам услуг
  3. Отправить информацию по тарифу за используемый клиентом сервис (опционально)
  4. Реализовать один из вариантов списаний с клиента: 4.1 Платежное требование с электронной подписью 4.2 Начисления

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

Клиенты с подключенными подписками

Ресурс /v1/partner-info/advance-acceptances позволяет Партнеру получить сведения о клиентах, подключенных к подпискам и пакетам услуг. Полученную информацию можно анализировать и использовать для выставления платежных требований в адрес клиентов сервиса. В ответе возвращается информация за один запрашиваемый день. Для поддержания актуальной информации и изменений на своей стороне необходимо осуществлять ежедневный запрос информации.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения информации о клиентах, подключенных к подпискам и пакетам услуг, необходимо отправить GET-запрос (/v1/partner-info/advance-acceptances), в котором необходимо передать авторизационный токен (Access Token), полученный для собственной организации, дату, за которую запрашивается информация (date). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Header Parameters
Authorization String Access token организации-клиента, полученный через SSO. Пример: Bearer 5c2f4c8d-4c8a-4301-8df7-195354932b19-1
Query Parametrs
date date-time
Дата (подключения или отключения)
Формат: yyyy-MM-dd
clientId String
Идентификатор сервиса

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

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 5c2f4c8d-4c8a-4301-8df7-195354932b19-1'

'http://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/advance-acceptances?date=2019-10-24'

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

AdvanceAcceptance [
AdvanceAcceptance 1
] AdvanceAcceptance 1{
active (boolean, optional) Признак активности ЗДА ,
bundles (Array[AdvanceAcceptanceBundle], optional) Информация о пакете услуг,
payerAccount (string, optional) Счёт плательщика ,
payerBankBic (string, optional) БИК банка плательщика ,
payerBankCorrAccount (string, optional) Корсчёт банка плательщика ,
payerInn (string, optional) ИНН плательщика ,
payerName (string, optional) Наименование плательщика ,
payerOrgIdHash (string, optional) Идентификатор организации плательщика ,
purpose (string, optional) Назначение платежа ,
sinceDate (string, optional) Дата начала действия заранее данного акцепта ,
untilDate (string, optional) Дата окончания действия заранее данного акцепта
}AdvanceAcceptanceBundle {
code (string, optional) Код пакета услуг ,
name (string, optional) Наименование пакета услуг,
sinceDate (string, optional) Дата подключения пакета услуг ,
untilDate (string, optional) Дата отключения пакета услуг,
currentState (String, optional) Статус пакета услуг в настоящее время.
Возможные варианты: ACTIVE, NOT_PAID, DEACTIVATED
}

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

{
   "active":false,
   "bundles":[
      {
         "code":"POLNHODB",
         "name":"Полным ходом",
         "sinceDate":"2018-12-31",
         "untilDate":"2018-12-31",
         "currentState":"ACTIVE"
      }
   ],
   "payerAccount":"40802810600000200000",
   "payerBankBic":"044525225",
   "payerBankCorrAccount":"40802810600000200000",
   "payerInn":"7707083893",
   "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "payerOrgIdHash":"ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5",
   "purpose":"Оплата заказа №123. НДС нет.",
   "sinceDate":"2018-12-31",
   "untilDate":"2018-12-31"
}

Клиенты с небанковскими сервисами

Ресурс /v1/partner-info/package-of-services позволяет Партнеру получить сведения о клиентах, подключенных к пакетам услуг с небанковскими сервисами.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения документа необходимо отправить GET-запрос (/v1/partner-info/package-of-services), в котором передать авторизационный токен (Access Token) и дату (подключения/отключения/изменения статуса ПУ). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

Header Parameters
Authorization String Access token полученный через SSO. Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
Query Parametrs
date date-time
Дата (подключения или отключения)
Формат: yyyy-MM-dd
clientId String
Идентификатор сервиса

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/package-of-services?date=2018-09-12'

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

subscribes {
Inn (String) ИНН плательщика,
orgName (String) Наименование организации,
orgIdHash (String) Хэш от идентификатора организации клиента,
bundles (Array[AdvanceAcceptanceBundle]) {
code (String) Код пакета услуг.
Возможные варианты: LIGHTSTB, ONBORTB, POLNHODB
name (String) Наименование пакета услуг
sinceDate (String) Дата подключения
untilDate (String) Дата отключения
currentState (String, optional) Статус пакета услуг в настоящее время.
Возможные варианты: INITIATED, ACTIVE, NOT_PAID, DEACTIVATED
}

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

{
   "Inn":"7733812920",
   "orgName":"Общество с ограниченной ответственностью Ромашка",
   "orgIdHash":"31256b9025db931f02f2353213061d46f309ba09fc5464cb4c14c2f69abf7024",
   "bundles":[
      {
         "code":"POLNHODB",
         "name":"Полным ходом",
         "sinceDate":"2018-12-31",
         "untilDate":"2019-12-31",
         "currentState":"ACTIVE"
      }
   ]
}

Информация по тарифам сервисов

Ресурс /v1/client-tariffs позволяет Партнеру передать в банк информацию по тарифу за использование сервиса/услуги клиентом.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для передачи информации по тарифу  необходимо отправить PUT-запрос (/v1/client-tariffs), в заголовке передать авторизационный токен к данным клиента (Access Token) и информацию по тарифу в теле запроса. авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Header Parameters
Authorization String Access token организации клиента, полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-tariffs'

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

ClientTariff {
activationDate (string, optional) Дата активации тарифа ,
code (string) Код тарифа ,
description (string, optional) Описание тарифа ,
expireDate (string, optional) Дата окончания тарифа ,
expireTrialModeDate (string, optional) Дата завершения триального периода ,
name (string) Наименование тарифа ,
plannedPaymentDate (string, optional) Плановая дата списания денежных средств за сервис ,
rateAmount (number) Стоимость ,
ratePeriodMonths (integer) Периодичность оплаты в месяцах ,
tokenUrl (string, optional) Ссылка на страницу управления тарифом для токен клиентов ,
trialMode (boolean, optional),
url (string, optional) Ссылка на страницу управления тарифом,
useAdditionalTariff (boolean, optional) Использовать несколько тарифов
}

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

{
   "activationDate":"2018-12-31",
   "code":"N",
   "description":"Описание тарифа N",
   "expireDate":"2018-12-31",
   "expireTrialModeDate":"2018-12-31",
   "name":"Тариф N",
   "plannedPaymentDate":"2018-12-31",
   "rateAmount":1.01,
   "ratePeriodMonths":12,
   "tokenUrl":"https://www.partner.ru/tariffs",
   "trialMode":true,
   "url":"https://www.partner.ru/tariffs",
   "useAdditionalTariff":true
}

Если billing выполняется по каждому пользователю, то в поле rateAmount необходимо указывать общую сумму списания в рамках организации.

Информация по офертам клиента

Ресурс /v1/partner-info/offers позволяет Партнеру получить информацию по офертам клиента, которые были заключены пользователями этого клиента.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

Для получения информации по офертам клиента, которые были заключены пользователями этого клиента с Партнером, необходимо отправить GET-запрос (/v1/partner-info/offers), в котором необходимо передать авторизационный токен (Access Token), полученный для собственной организации, хэш от идентификатора организации клиента (client), и статус запрашиваемых оферт (status). Авторизационный токен передается в параметре Authorization заголовка запроса. Хэш от идентификатора организации клиента можно узнать из запроса Получение информации о клиенте (т.е. из запроса user-info (значение атрибута HashOrgId в ответе на запрос user-info) по данному клиенту). Информацию необходимо хранить на своей стороне для последующего использования.

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

Header Parameters
Authorization String Access token полученный через SSO. Пример: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1
Query Parametrs
client String
Хэш от идентификатора организации. Значение атрибута HashOrgId в ответе на запрос user-info
status String
Статус оферт
clientId String
Идентификатор сервиса

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

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/partner-info/offers?client=66e018dc56ac32363f3afdc92e86c092943bba97c16986327ab2f4f6b6ce1435'

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

PartnerOfferInfo {
clientId (string, optional) Идентификатор сервиса,
inn (string, optional) ИНН организации,
orgName (string, optional) Название организации,
users (Array[UserOffers], optional) Список пользователей с офертами
}UserOffers {
accountList (Array[string], optional) Список счетов,
sinceDate (string, optional) Дата начала действия оферты,
status (string, optional) Статус оферты,
sub (string, optional) Хэш идентификатора пользователя,
untilDate (string, optional) Дата завершения действия оферты,
userName (string, optional) Наименование пользователя
}

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

{
   "clientId":"1005",
   "inn":"7707083893",
   "orgName":"OrgName",
   "users":[
      {
         "accountList":[
            "string"
         ],
         "sinceDate":"2018-12-31",
         "status":"PUBLIC",
         "sub":"026f8e459c8f89ef75fa7a78265a0025",
         "untilDate":"2018-12-31",
         "userName":"Name"
      }
   ]
}

Таблица допустимых значений параметра status:

Значение параметра Описание
public Возвращает данные по клиентам, с активными офертами
private Возвращает данные по клиентам, с неактивными офертами, которые отозвал клиент
revoke Возвращает данные по клиентам, с неактивными офертами, которые отозвал Банк

Если параметр status не указан в запросе, то предполагается что запрос выполняется по всем допустимым значениям параметра status.

Создание платежных требований

Ресурс /v1/payment-requests/outgoing позволяет Партнеру создавать исходящие платёжные требования, где получателем средств является организация, предоставляющая сервис.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

3. Получить статус.

Для создания рублёвого платёжного требования Партнеру необходимо отправить POST-запрос (/v1/payment-requests/outgoing), в котором необходимо передать авторизационный токен (Access Token), полученный по собственной организации и реквизиты платёжного требования. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Header Parameters
Authorization String Access token собственной организации, полученный через SSO. Пример: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1

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

curl -X GET --header 'Accept: application/json' --header

'Authorization: Bearer c5e7110b-394a-45eb-9a4b-d8759cf6f9eb-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing'

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

PaymentRequestOut {
acceptanceTerm (string, optional) Срок для акцепта (поле 36). Указывается количество дней для получения акцепта плательщика,
amount (number) Сумма платежа,
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional, read only) Статус документа,
crucialFieldsHash (string, optional) Hash от ключевых полей документа,
date (string) Дата составления документа,
deliveryKind (string, optional) Вид платежа,
digestSignatures (Array[Signature], optional) Электронные подписи по дайджесту документа,
externalId (string) Идентификатор документа, присвоенный партнёром (UUID),
number (string, optional) Номер документа,
operationCode (string) Код операции,
payeeAccount (string, optional) Счёт получателя платежа,
payeeBankBic (string) БИК получателя платежа,
payeeBankCorrAccount (string, optional) Корсчёт банка получателя платежа,
payeeInn (string, optional) ИНН получателя платежа,
payeeName (string) Полное наименование получателя платежа,
payerAccount (string) Счёт плательщика,
payerBankBic (string) БИК банка плательщика,
payerBankCorrAccount (string) Корсчёт банка плательщика,
payerInn (string) ИНН плательщика,
payerName (string) Полное наименование плательщика,
paymentCondition (string) Условие оплаты (поле 35).
Указывается цифра "1" - заранее данный акцепт плательщика или
цифра "2" - требуется получение акцепта плательщика,
priority (string) Очерёдность платежа,
purpose (string) Назначение платежа,
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"
}

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

{
   "acceptanceTerm":"string",
   "amount":1.01,
   "bankComment":"string",
   "bankStatus":"string",
   "crucialFieldsHash":"string",
   "date":"2018-12-31",
   "deliveryKind":"электронно",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "number":"1",
   "operationCode":"01",
   "payeeAccount":"40802810600000200000",
   "payeeBankBic":"044525225",
   "payeeBankCorrAccount":"30101810400000000225",
   "payeeInn":"7707083893",
   "payeeName":"Общество с ограниченной ответственностью \"Клиент\"",
   "payerAccount":"40802810600000200000",
   "payerBankBic":"044525225",
   "payerBankCorrAccount":"30101810400000000225",
   "payerInn":"7707083893",
   "payerName":"Общество с ограниченной ответственностью \"Клиент\"",
   "paymentCondition":"string",
   "priority":"5",
   "purpose":"Оплата заказа №123. НДС нет.",
   "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, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись;
  • первая и вторая подписи.

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля, когда пользователь Партнера создается в Банке.

Формат дайджеста платёжного требования

Наименование поля Описание поля Пример
acceptanceTerm Срок акцепта 5
amount Сумма платежа 100.01
date Дата составления документа 31.12.2018
externalId Идентификатор документа, присвоенный сервисом 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
operationCode Код операции 02
payeeAccount Номер счета получателя 40802810600000200000
payeeBankBic БИК получателя 044525225
payeeBankCorrAccount Корсчет банка получателя 30101810400000000225
payeeInn Инн получателя 0
payeeName Полное наименование получателя платежа Общество с ограниченной ответственностью "Получатель"
payerAccount Счет плательщика 40802810600000200000
payerBankBic БИК плательщика 044525225
payerBankCorrAccount Корсчет банка плательщика 30101810400000000225
payerInn ИНН плательщика 0
payerName Полное наименование плательщика Общество с ограниченной ответственностью "Клиент"
paymentCondition Условие оплаты (1/2) 1
priority Очередность платежа 5
purpose Назначение платежа Оплата товара по договору №123 от 01.08.2018. НДС не облагается

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

acceptanceTerm=5
amount=100.01
date=2018-12-31
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
operationCode=02
payeeAccount=40802810600000200000
payeeBankBic=044525225
payeeBankCorrAccount=30101810400000000225
payeeInn=0
payeeName=Общество с ограниченной ответственностью "Получатель"
payerAccount=40802810600000200000
payerBankBic=044525225
payerBankCorrAccount=30101810400000000225
payerInn=0
payerName=Общество с ограниченной ответственностью "Клиент"
paymentCondition=1
priority=5
purpose=Назначение платежа

Процесс обработки платежного требования

Обработка платежного требования (ПТ)

Выгрузка ПТ из СББОЛ осуществляется каждые 5 минут в период с 9:00 – 16:30

Если плательщик в Сбербанке

При поступлении платежного требования на стороне Банка выполняются следующие проверки:

  1. Логические проверки плательщика/получателя ПТ. ПТ не исполняется и возвращается ошибка, если не прошли проверки
  2. Проверка на наличие заранее данного акцепта(ЗДА), выданного клиентом в Партнеру

    2.1 Если ЗДА есть:

        2.1.1  Проверка реквизитов ЗДА
    
             2.1.1.1 Если проверка пройдена, выполняется проверка на ограничение по счету:
    
                  2.1.1.1.1 Если есть полные ограничения на списание денежных средств по счету, платежный документ помещается бессрочно в Картотеку 1
    
                  2.1.1.1.2  Если есть частичные ограничения, проверяется достаточность средств для списания (остаток от блокировки)
    
             2.1.1.2 Выполняется проверка наличия денежных средств на счете:
    
                  2.1.1.2.1  Если денежных средств достаточно на полную оплату требования (с учетом всех действующих частичных блокировок средств), сразу выполняется списание и перечисление
    
                  2.1.1.2.2 Если денежных средств недостаточно (доступна не полная сумма), документ помещается в Картотеку 1 без срока и оплачивается из нее на сумму свободных средств
    
                  2.1.1.2.3 Если денежных средств на счете нет, вся сумма помещается в Картотеку 1/ Картотеку 2
    
                  2.1.1.2.4  Если выявлено неполное соответствие ЗДА (например, не сходится одна цифра в дате или регистр в номере договора (русские/англ.буквы), документ передается на ручную обработку в операционный центр

    2.2 Если ЗДА нет или реквизиты ЗДА полностью не соответствуют реквизитам из ПТ, то платежное требование помещается на 5 рабочих дней (не считая дня поступления) в Картотеку 1 для ручного акцепта клиента

Если получатель Внешний плательщик

ПТ сформированное в СББОЛ уходит в Банк России, далее Банк России отправляет в банк получателя

Частичная оплата со стороны клиента, периодичность обработки вновь появившихся денежных средств на счете клиента

Ручной акцепт:

          Акцепт ПТ клиент может выполнить в СберБизнес. Есть возможность акцептовать как полную сумму, так и частично. После акцепта формируется документ на оплату

          При частичном акцепте суммы, оставшаяся сумма остается в картотеке до конца срока нахождения проводки в Картотеке либо на оставшуюся сумму можно сформировать отказ

Списание денежных средств по проводке в бессрочной Картотеке 2 (при наличии ЗДА):

          Списание выполняются с 9 до 22 часов каждые 2-2,5 часа. Перебираются все счета  с Картотекой 2 и Картотекой 1 без срока, определяется платежеспособность счета (рассчитывается остаток свободных средств >0) и запускается процесс списания. Если до полного списания средств недостаточно, то выполняется частичное списание

Отзыв платежного документа из Картотеки:

         ИПТ в Картотека 1 (на ручном акцепте клиента) может быть отозвано плательщиком (отказ от акцепта)

         Если ИПТ находится бессрочно в Картотека 1 или 2, отозвать ИПТ в СберБизнес нельзя

Действие ЗДА:

         ЗДА начинает действовать со дня следующего за днем поступления в Банк

         Если ПТ отправить в день создания ЗДА, платежный документ попадет в Картотеку 1 (на ручной акцепт клиенту)

Закрытие счета:

          При закрытии счета все документы в картотеке  аннулируются (возвращаются составителям без исполнения) без списания

Статус SEND_TO_PAYER

          Если платежный документ помещается в Картотеку 1 или Картотеку 2, то в статус документа переводится в ``SEND_TO_PAYER``

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

Ресурс /v1/payment-requests/outgoing/{externalId}/state позволяет Партнеру получить статус ранее отправленного платёжного требования.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

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

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

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

Header Parameters
Authorization String Access token собственной организации, полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Query Parametrs
externalId String
Идентификатор документа, присвоенный клиентом

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

curl -X GET --header "Accept: /" --header

"Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1"

"https://edupirfintech.sberbank.ru:9443/fintech/api/v1/payment-requests/outgoing/ffffffff-fffa-458e-ad92-fff9497303ba/state"

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

PaymentDocState {
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional) Статус документа,
channelInfo (string, optional, read only) Комментарий, специфичный для документа, полученного по данному каналу,
}

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

{

"bankStatus": "CREATED",

"bankComment": null,

"channelInfo": null

}

Статусы обработки платежных документов

Код состояние документа Наименование статуса Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
ACCEPTED Принят Электронный документ принят на стороне Банка
ACCEPTED_BY_ABS Принят АБС Электронный документ был принят к обработке в АБС Банка
CARD2 Картотека 2 Электронный документ передан в картотеку в ожидание средств на счету клиента
CREATED Создан Документ записан в БД, проверки не выполнялись
DELAYED Приостановлен Обработка электронного документа была приостановлена
DELIVERED Доставлен Запрос доставлен в ДБО и взят в обработку
EXPORTED Выгружен Электронный документ выгружен Банком в АБС
FRAUDALLOW Одобрен ФРОД Проверка во ФРОДЕ прошла успешно, переход на «Принят»
FRAUDDENY Отвергнут ФРОД Документ отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком»
FRAUDREVIEW На проверке у специалиста Банка Со стороны ФРОД-анализа получен статус документа «На проверке у специалиста Банка»
FRAUDSENT Отправлен во ФРОД Документ отправлен на проверку в АС Fraud-мониторинг
FRAUDSMS Требуется подтверждение sms-паролем Со стороны ФРОД-анализа получен статус документа «Требуется подтверждение sms-паролем»
PARTSIGNED Частично подписан ЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей.
PROCESSING В обработке Клиент сформировал «Заявление об акцепте/частичном акцепте/отказе от акцепта»
REQUESTED_RECALL Запрошен отзыв Документ отозван
SIGNED Подписан ЭД подписан предусмотренным для него комплектом подписей.
SUBMITTED Представлен Электронный документ принят ВК
Окончательные статусы/Прекратить опрос
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
CHECKERROR_BANK Ошибка контроля, Банк ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
INVALIDEDS ЭПАСП не верна Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
RECALL Отозван Электронный документ был отозван Клиентом по запросу
REFUSED_BY_RZK Отказан контролирующей организацией ЭД не прошел проверки контролирующей организацией
REQUISITEERROR Ошибка реквизитов В ЭД указаны ошибочные реквизиты
REFUSEDBYABS Отказан АБС ЭД не прошел проверки в АБС.
Окончательные(Успешные) статусы/Прекратить опрос
IMPLEMENTED Исполнен Электронный документ исполнен Банком

Списание платы за использование сервиса

Ресурс /v1/client-accruals позволяет Партнеру отправлять в банк запрос на списание платы за использование клиентом сервиса. Изначально списание происходит на счет банка, в дальнейшем банк переводит деньги Партнеру.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

3. Получить документ.

Для создания начисления необходимо отправить POST-запрос (/v1/client-accruals), в котором передать авторизационный токен собственной организации (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Header Parameters
Authorization String Access token собственной организации, полученный через SSO. Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
Body
ClientAccrual {
account (string, optional) Счёт клиента для списания комиссии ,
amount (number, optional) Сумма начисления без НДС ,
amountDebt (number, optional, read only) Остаток задолженности ,
amountVat (number, optional) Сумма НДС ,
bankComment (string, optional, read only) Банковский комментарий к статусу ,
bankStatus (string, optional, read only) Статус списания денежных средств за
начисление = [ANNULLED, CANCELED, CHECKERROR,
CHECKERRORABS, CREATED, DELIVERED, NOT_PROCESSED,
NOTPAID, PAID, PARTPAID, REFUSED_BY_LIMIT,
REQUISITEERROR, EXPORTED, SENDED, UPLOADERROR,
WAITING]
stringEnum ANNULLED, CANCELED, CHECKERROR,
CHECKERRORABS, CREATED, DELIVERED, NOT_PROCESSED,
NOTPAID, PAID, PARTPAID, REFUSED_BY_LIMIT,
REQUISITEERROR, EXPORTED, SENDED, UPLOADERROR,
WAITING
clientId (integer, optional) Идентификатор сервиса ,
client (string) Идентификатор организации ,
countServiceFact (integer, optional) Количество фактов потребления услуги за период ,
dateExpiration (string, optional) Дата начала взимания пени при просрочке платежа ,
dateSince (string) Дата начала периода списания ,
dateUntil (string) Дата окончания периода списания ,
datetimeStatusChange (string, optional, read only) Дата и время исполнения документа ,
digestSignatures (Array[Signature]) Подписи начисления ,
externalId (string) Идентификатор начисления, присвоенный партнёром (UUID) ,
purpose (string, optional) Назначение платежа
}Signature {
base64Encoded (string) Значение электронной подписи, закодированное в Base64 ,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}

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

{
   "account":"40802810600000200000",
   "amount":1.01,
   "amountDebt":1.01,
   "amountVat":1.01,
   "bankComment":"string",
   "bankStatus":"ANNULLED",
   "clientId":1005,
   "client":"ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5",
   "countServiceFact":20,
   "dateExpiration":"2018-12-31",
   "dateSince":"2018-12-31",
   "dateUntil":"2018-12-31",
   "datetimeStatusChange":"2018-12-31T23:59:59",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "purpose":"Оплата заказа №123. НДС нет."
}

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

Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature (все поля обязательны):

Наименования поля Описания поля Пример
base64Encoded (string) Значение ЭП документа HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==
certificateUuid (string) Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto) 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6

Для начислений, создаваемых по собственным счетам можно передать одну или две электронных подписей (или не передавать при отсутствии ЭП) вместе с реквизитами создаваемого документа.
Если ЭП передана/ы в API, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу.
Если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

Документ может быть подписан следующими наборами подписей:

  • одна (единственная) подпись;
  • первая и вторая подписи.

При этом подписант, обладающий полномочием единственной подписи, не может «сочетаться» с подписантом, владеющим первой или второй подписью.

Очередность наложения ЭП при наложении первой и второй подписей не имеет значения, состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля, когда пользователь Партнера создается в Банке.

Формат дайджеста платёжного требования

| Наименование поля | Описание поля | | ----------------- | ------------- || | client | Идентификатор организации | | clientId | Идентификатор сервиса | | externalId | Идентификатор начисления, присвоенный партнёром (UUID) | | account | Счёт клиента для списания комиссии | | dateSince | Дата начала периода списания | | dateUntil | Дата окончания периода списания | | countServiceFact | Количество фактов потребления услуги за период | | amount | Сумма начисления без НДС | | amountVat | Сумма НДС | | purpose | Назначение платежа | | dateExpiration | Дата начала взимания пени при просрочке платежа |

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

client=ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5
clientId=1005
externalId=22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6
account=40802810600000200000
dateSince=2018-12-31
dateUntil=2018-12-31
countServiceFact=20
amount=1.01
amountVat=1.01
purpose=Оплата заказа №123. НДС нет.
dateExpiration=2018-12-31

Получение документа по списанию средств

Ресурс /v1/client-accruals/{externalId} позволяет Партнеру получить документ по списанию банком денежных средств с клиента за пользование сервисом.

Шаги

1. Получить AccessToken.

2. Отправить запрос.

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

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

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

Header Parameters
Authorization String Access token полученный через SSO. Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
Query Parametrs
externalId String
Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: application/json' --header

'Authorization:  Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'

'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/client-accruals/22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6'

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

Соответствует модели запроса v1/client-accruals.

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

Код состояние документа Наименование статуса Назначение кода состояния
Промежуточные статусы/Продолжать опрашивать
CREATED Создан факт потребления
DELIVERED Доставлено в ЕКС
EXPORTED Сформирован файл с начислениями
NOT_PROCESSED Не обработано
NOTPAID Не оплачено
PARTPAID Частично оплачено
PROCESSING В обработке
SENDED Отправлено в ЕКС
WAITING Ожидается проводка
Окончательные статусы/Прекратить опрос
ANNULLED Аннулировано
CHECKERROR Ошибка контроля ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
CANCELED Отменено на стороне СББОЛ
CHECKERRORABS Ошибка валидации ЭЦП ЕКС
DECLINED Отказано
REFUSED_BY_LIMIT Отказано по лимиту суммы
REQUISITEERROR Ошибка реквизитов
Окончательные(Успешные) статусы/Прекратить опрос
PAID Оплачено

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

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

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

  • Если блок 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 (POST-запрос) CREATED
Создан Операция не завершена полностью Документ создан, сохранён но не подписан Банком
202 (POST-запрос) SC_ACEPTED
Операция не завершена полностью Документ создан, сохранён но не подписан Банком
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; У пользователя отсутствует оферта с внешним сервисом.
404 DATA_NOT_FOUND_EXCEPTION
Платежный документ не найден Неверное значение externalId
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен Проводятся технические работы

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

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