Сервис самоинкассации

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

Создание заявления

Ресурс /v1/self-encashers-requests позволяет создавать заявления на добавление нового вносителя самоинкассации.

Шаги:

  1. Получить AccessToken.
  2. Сформировать ЭП
  3. Отправить запрос
  4. Получить статус
  5. Получить документ

Авторизация

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

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

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

Наименование Описание
Параметры заголовка
Authorization (String)
Access token собственной организации, полученный через SSO
Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1
SelfEncasherRequest
externalId (string) Идентификатор документа, присвоенный сервисом (UUID)
date (string) Дата составления документа
surname (string) Фамилия
name (string) Имя
patronymic (string, optional) Отчество
gender (string) Пол (M - мужской, F - женский)
phone (string) Номер мобильного телефона
birthDate (string) Дата рождения
birthPlace (string) Место рождения
citizenshipCountryCode (string) Цифровой код страны гражданства в формате ISO 3166-1 numeric
identityDoc
typeCode (string) Код типа документа, удостоверяющий личность. Тип документа должен соответствовать стране гражданства, указанной ранее. Доступные коды:
21 - Паспорт гражданина Российской Федерации
01 - Паспорт гражданина СССР
07 - Военный билет
08 - Временное удостоверение, выданное взамен военного билета
10 - Паспорт иностранного гражданина
11 - Свидетельство о рассмотрении ходатайства о признании лица беженцем на территории Российской Федерации по существу
serial (string, optional) Серия документа, удостоверяющего личность. Для паспорта гражданина Российской Федерации поле обязательно к заполнению и должно состоять из 4 цифр
number (string) Номер документа, удостоверяющего личность. Для паспорта гражданина Российской Федерации поле должно состоять из 6 цифр
issueDate (string) Дата выдачи документа, удостоверяющего личность
issuer (string) Наименование органа, выдавшего документ, удостоверяющий личность
issuerCode (string, optional) Код подразделения, выдавшего документ, удостоверяющий личность
regAddress
countryCode (string) Цифровой код страны адреса регистрации в формате ISO 3166-1 numeric
state (string) Регион адреса регистрации
district (string, optional) Район адреса регистрации
city (string, optional) Город адреса регистрации. Поле обязательно к заполнению, если не заполнено поле «Населенный пункт»
settlement (string, optional) Населенный пункт адреса регистрации. Поле обязательно к заполнению, если не заполнено поле «Город»
postalCode (string, optional) Индекс адреса регистрации
street (string) Улица адреса регистрации
house (string) Номер дома адреса регистрации
building (string, optional) Номер корпуса дома адреса регистрации
flat (string, optional) Квартира адреса регистрации
insuranceNumber (string, optional) СНИЛС. Если заполнено, поле должно состоять из 11 цифр
taxNumber (string, optional) ИНН. Если заполнено, поле должно состоять из 12 цифр
empowermentStart (string) Дата начала наделения полномочиями. Не может быть меньше даты отправки запроса
empowermentEnd (string, optional) Дата окончания наделения полномочиями
byAttorney (boolean) Признак наделения полномочиями по доверенности
attorneyNumber (string, optional) Номер доверенности. Поле обязательно к заполнению, если установлен признак наделения полномочиями по доверенности
persInfoConsent (boolean) Признак подтверждения клиентом согласия вносителя на обработку его персональных данных банком
agreedAdmOperation (boolean) Признак подтверждения клиентом согласия с условиями предоставления услуги
templates (array) Массив наименований шаблонов внесения денежных средств
digestSignatures (Array[Signature], optional)
base64Encoded (string) Значение электронной подписи, закодированное в Base64
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)

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

      "settlement":"",
      "postalCode":"",
      "street":"Кутузовский проспект",
      "house":"1",
      "building":"",
      "flat":""
   },
   "insuranceNumber":"11111111111",
   "taxNumber":"123456789011",
   "empowermentStart":"2020-03-30",
   "empowermentEnd":"2021-03-30",
   "byAttorney":false,
   "attorneyNumber":"",
   "persInfoConsent":true,
   "agreedAdmOperation":true,
   "templates":[
      "НаименованиеШаблона"
   ],
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ]
}

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

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

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

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

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

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

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

Формат дайджеста заявления

Наименование Описание Пример
birthDate Сумма платежа 2000-12-11
birthPlace Место рождения вносителя Москва
date Дата составления документа 2020-03-30
empowermentEnd Дата окончания наделения полномочиями 2021-03-30
empowermentStart Дата начала наделения полномочиями 2020-03-30
externalId Идентификатор документа, присвоенный сервисом a0000000-0000-0000-0000-000000000001
identityDoc.issueDate Дата выдачи документа, удостоверяющего личность 2014-12-11
identityDoc.issuer Наименование органа, выдавшего документ, удостоверяющий личность ОВД г. Москвы
identityDoc.typeCode Код типа документа, удостоверяющий личность 21
name Имя вносителя Иван
phone Номер мобильного телефон вносителя 79261111111
regAddress.countryCode Цифровой код страны адреса регистрации 643
regAddress.house Номер дома адреса регистрации 1
regAddress.state Регион адреса регистрации Москва
regAddress.street Улица адреса регистрации Кутузовский проспект
surname Фамилия вносителя Иванов

Пример дайджеста заявления

birthDate=2000-12-11
birthPlace=Москва
date=2020-03-30
empowermentEnd=2021-03-30
empowermentStart=2020-03-30
externalId=128ba52c-2eef-4070-b551-04539de3f215
identityDoc.issueDate=2014-12-11
identityDoc.issuer=ОВД Москвы
identityDoc.typeCode=21
name=Иван
phone=79261111111
regAddress.countryCode=643
regAddress.house=1
regAddress.state=Москва
regAddress.street=Кутузовский проспект
surname=Ивановов

Получение статуса заявления

Ресурс /v1/self-encashers-requests/{externalId}/state позволяет получить статус заявления на добавление вносителя самоинкассации.

Шаги:

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

Авторизация

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

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

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

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

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

curl -X GET --header `Accept: /` --header 
`Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
`https://edupirfintech.sberbank.ru:9443/fintech/api/v1/self-encashers-requests/ffffffff-fffa-458e-ad92-fff9497303ba/state`

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

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

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

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

Получение атрибутов заявления

Ресурс /v1/self-encashers-requests/{externalId} позволяет получить атрибуты ранее отправленного заявления на добавление вносителя самоинкассации.

Шаги:

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

Авторизация

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

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

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

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

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

curl -X GET --header `Accept: /` --header 
`Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1`
`https://edupirfintech.sberbank.ru:9443/fintech/api/v1/self-encashers-requests/ffffffff-fffa-458e-ad92-fff9497303ba`

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

Наименование Описание
number (string) Номер документа
date (string) Дата составления документа
bankStatus (string) Статус документа
bankComment (string, optional) Банковский комментарий к статусу документа
externalId (string) Идентификатор документа, присвоенный сервисом
empowermentStart (string) Дата начала наделения полномочиями
empowermentEnd (string) Дата окончания наделения полномочиями
byAttorney (boolean) Признак наделения полномочиями по доверенности
attorneyNumber (string, optional) Номер доверенности
login (string, optional) Логин вносителя. Поле заполнено, если на основании заявления успешно добавлен вноситель самоинкассации

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

{
   "number":"18",
   "date":"2020-03-17",
   "bankStatus":"IMPLEMENTED",
   "bankComment":null,
   "externalId":"128ba52c-2eef-4070-b551-04539de3f215",
   "empowermentStart":"2020-03-17",
   "empowermentEnd":"2020-12-20",
   "byAttorney":false,
   "attorneyNumber":null,
   "login":"11001100"
}

Блокировка вносителя самоинкассации

Ресурс /v1/self-encashers/block позволяет блокировать вносителя самоинкассации.

Шаги:

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

Авторизация

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

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

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

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

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

curl -X POST --header 'Content-Type: application/jose' --header
Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1' -d '138155209'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/self-encashers/block'

Создание нового пароля

Ресурс /v1/self-encashers/new-password позволяет создать новый пароль вносителя самоинкассации.

Шаги:

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

Для создания нового пароля вносителя самоинкассации необходимо отправить POST-запрос (/v1/self-encashers/new-password), в котором нужно передать авторизационный токен к данным собственной организации (Access Token) и login вносителя. Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

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

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

curl -X POST --header 'Content-Type: application/jose' --header
Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1' -d '138155209'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/self-encashers/block'

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

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

Content-Type может содержать одно из двух значений:

  1. application/json – запрос без подписи.
  2. application/jose – запрос, подписанный транспортной подписью.

Если Content-Type имеет значение application/jose, то запрос должен содержать данные (реквизитный состав платежного документа) в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).

JWS состоит из:

  • заголовка (Header),
  • JSON-документа с реквизитным составом платежного поручения (Payload),
  • подписи запроса (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.

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

Код возврата Описание кода возврата Причина возникновения
200 (GET-запроса) OK
Запрос успешно выполнен
201 (POST-запрос) CREATED
Создан
400 DESERIALIZATION_FAULT
Неверный формат запроса
Неверный формат запроса
VALIDATION_FAULT
Ошибка валидации
Ошибка валидации данных запроса с указанием некорректных значений. Значения полей модели или параметров запроса не соответствуют допустимым и определённым в модели.
SIGN_CHECK_EXCEPTION
Подлинность подписи не установлена/Сертификат не обнаружен или не является активным
Ошибка возникает, если не удалось установить подлинность подписи
401 UNAUTHORIZED
accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х
Указан некорректный или просроченный access_token.
403 ACTION_ACCESS_EXCEPTION
Операция не может быть выполнена: доступ к ресурсу запрещён
У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope;
У пользователя отсутствует оферта с внешним сервисом.
404 NOT_FOUND
По указанному externalId не найдено заявление
Заявление не существует или заявление не относится к организации клиента
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен
Проводятся технические работы

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

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