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

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

  • Тестовый контур https://edupirfintech.sberbank.ru:9443
  • Промышленный контур https://fintech.sberbank.ru:9443

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

Ресурс /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 {
agreedAdmOperation (boolean) Признак подтверждения согласия с условиями,
attorneyNumber (string, optional) Номер доверенности. Поле обязательно к заполнению, если установлен признак наделения полномочиями по доверенности,
bankComment (string, optional, read only) Банковский комментарий к статусу документа,
bankStatus (string, optional, read only) Статус документа,
birthDate (string) Дата рождения,
birthPlace (string) Место рождения,
byAttorney (boolean, optional) Признак наделения полномочиями по доверенности,
citizenshipCountryCode (string) Цифровой код страны гражданства в формате ISO 3166-1 numeric,
date (string) Дата составления документа,
digestSignatures (Array[Signature], optional) {
base64Encoded (string) Значение электронной подписи, закодированное в Base64,
certificateUuid (string) Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
},
empowermentEnd (string) Дата окончания наделения полномочиями,
empowermentStart (string) Дата начала наделения полномочиями. Не может быть меньше даты отправки запроса,
externalId (string) Идентификатор документа, присвоенный сервисом (UUID),
gender (string, optional) Пол (M - мужской, F - женский),
identityDoc {
issueDate (string) Дата выдачи документа, удостоверяющего личность,
issuer(string) Наименование органа, выдавшего документ, удостоверяющий личность,
issuerCode (string, optional) Код подразделения, выдавшего документ, удостоверяющий личность,
number (string) Номер документа, удостоверяющего личность. Для паспорта гражданина Российской Федерации поле должно состоять из 6 цифр,
serial (string, optional) Серия документа, удостоверяющего личность. Для паспорта гражданина Российской Федерации поле обязательно к заполнению и должно состоять из 4 цифр,
typeCode (string) Код типа документа, удостоверяющий личность.
Тип документа должен соответствовать стране гражданства, указанной ранее.
Доступные коды:
21 - Паспорт гражданина Российской Федерации,
01 - Паспорт гражданина СССР,
07 - Военный билет,
08 - Временное удостоверение, выданное взамен военного билета,
10 - Паспорт иностранного гражданина,
11 - Свидетельство о рассмотрении ходатайства о признании лица беженцем на территории Российской Федерации по существу
},
insuranceNumber (string, optional) СНИЛС. Если заполнено, поле должно состоять из 11 цифр,
login (string, optional) Имя пользователя,
name (string) Имя,
number (string, optional) Номер документа,
patronymic (string, optional) Отчество,
persInfoConsent (boolean) Признак подтверждения клиентом согласия вносителя на обработку его персональных данных банком,
phone (string) Номер мобильного телефона,
regAddress {
building (string, optional) Номер корпуса дома адреса регистрации,
city (string, optional) Город адреса регистрации. Поле обязательно к заполнению, если не заполнено поле "Населенный пункт",
countryCode (string) Цифровой код страны адреса регистрации в формате ISO 3166-1 numeric,
district (string, optional) Район адреса регистрации,
flat (string, optional) Квартира адреса регистрации,
house (string) Номер дома адреса регистрации,
postalCode (string, optional) Индекс адреса регистрации,
settlement (string, optional) Населенный пункт адреса регистрации. Поле обязательно к заполнению, если не заполнено поле "Город",
state (string) Регион адреса регистрации,
street (string) Улица адреса регистрации
},
surname (string) Фамилия,
taxNumber (string, optional) ИНН. Если заполнено, поле должно состоять из 12 цифр,
templates (array) Массив наименований шаблонов внесения денежных средств,
}

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

{
  "agreedAdmOperation": false,
  "attorneyNumber": "51 А А 0001904",
  "bankComment": "string",
  "bankStatus": "string",
  "birthDate": "2018-12-31",
  "birthPlace": "Москва",
  "byAttorney": false,
  "citizenshipCountryCode": "643",
  "date": "2018-12-31",
  "digestSignatures": [
    {
      "base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
      "certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
    }
  ],
  "empowermentEnd": "2018-12-31",
  "empowermentStart": "2018-12-31",
  "externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
  "gender": "F",
  "identityDoc": {
    "issueDate": "2018-12-31",
    "issuer": "ОВД г. Москвы",
    "issuerCode": "222-222",
    "number": "111222",
    "serial": "1111",
    "typeCode": "21"
  },
  "insuranceNumber": "11111111111",
  "login": "username",
  "name": "Дмитрий",
  "number": "1",
  "patronymic": "Сергеевич",
  "persInfoConsent": false,
  "phone": "79269999999",
  "regAddress": {
    "building": "1",
    "city": "Александров",
    "countryCode": "643",
    "district": "Александровский",
    "flat": "1",
    "house": "1",
    "postalCode": "601650",
    "settlement": "село Андреевское",
    "state": "Владимирская область",
    "street": "Институтская"
  },
  "surname": "Петров",
  "taxNumber": "7707083893",
  "templates": [
    "string"
  ]
}

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

Для передачи ЭП в теле запроса используется массив 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
Сервис временно недоступен
Проводятся технические работы