Удаленное подключение зарплатного проекта

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

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

Создание заявки на подключение проекта

Ресурс /v1/salary-agreement-requests позволяет создавать заявку на удаленное подключение зарплатного проекта.

Шаги

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

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

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

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

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

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

Наименование	Описание
Параметры заголовка
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/salary-agreement-requests'

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

Наименование	Описание
SalaryAgreementRequest {
account (string)	Номер счета пользователя,
admissionType (string)	Тип зачисления,
amount (number)	Месячный фонд оплаты труда,
authPersonName (string)	ФИО уполномоченного сотрудника организации пользователя,
authPersonTel (string)	Номер телефона уполномоченного сотрудника организации пользователя,
bankComment (string, optional, read only)	Банковский комментарий к статусу документа,
bankStatus (string, optional, read only)	Статус документа,
bic (string)	БИК банка пользователя,
date (string)	Дата составления документа,
digestSignatures (Array[Signature], optional)	Электронные подписи по дайджесту документа,
employeesNumber (integer)	Количество сотрудников,
externalId (string)	Идентификатор документа, присвоенный сервисом (UUID),
identityDoc (SalaryAgreementRequestIdentityDoc)	Сведения ДУЛ,
number (string, optional)	Номер документа,
offerAgree (boolean, optional)	Согласие с Условиями предоставления услуг и Тарифами,
orgName (string)	Наименование организации пользователя,
orgTaxNumber (string)	ИНН пользователя
}Signature {
base64Encoded (string)	Значение электронной подписи, закодированное в Base64,
certificateUuid (string)	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID)
}SalaryAgreementRequestIdentityDoc {
birthDate (string)	Дата рождения,
birthPlace (string)	Место рождения,
firstName (string)	Имя,
issueDate (string)	Дата выдачи ДУЛ,
issuer (string)	Кем выдан ДУЛ,
lastName (string)	Фамилия,
middleName (string)	Отчество,
number (string)	Номер ДУЛ,
serial (string)	Серия ДУЛ,
typeCode (string)	Код вида ДУЛ,
typeName (string)	Наименование ДУЛ
}

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

{
   "account":"40802810600000200000",
   "admissionType":"2",
   "amount":1.01,
   "authPersonName":"Иванов Алексей Сергеевич",
   "authPersonTel":"8(495)1234567",
   "bankComment":"string",
   "bankStatus":"string",
   "bic":"044525225",
   "date":"2018-12-31",
   "digestSignatures":[
      {
         "base64Encoded":"HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
         "certificateUuid":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
      }
   ],
   "employeesNumber":254,
   "externalId":"22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
   "identityDoc":{
      "birthDate":"2018-12-31",
      "birthPlace":"г. Москва",
      "firstName":"Иван",
      "issueDate":"2018-12-31",
      "issuer":"ОВД г.Москва",
      "lastName":"Иванов",
      "middleName":"Иванович",
      "number":"123456",
      "serial":"1234",
      "typeCode":"21",
      "typeName":"Паспорт гражданина Российской Федерации"
   },
   "number":"1",
   "offerAgree":false,
   "orgName":"Общество с ограниченной ответственностью \"Клиент\"",
   "orgTaxNumber":"7707083893"
}

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

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

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

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

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

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

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

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

Формирование ЭП

Из документа формируется строковая последовательность (ключевой буфер или дайджест), включающая все значимые данные документа.
Затем от дайджеста вычисляется хеш по стандарту ГОСТ 34.11-94 с параметрами GostR3411-94-CryptoProParamSet.
Полученное значение хеш-функции подписывается по стандарту ГОСТ 34.10-2001 с параметрами GostR3410-2001-CryptoPro-B-ParamSet.
64 байта, полученные в результате шага 3 и представленные в виде, описанном в пункте 3.1 RFC 4490 и есть сформированная электронная подпись.

Дайджест имеет текстовый формат, поэтому в значении полей могут быть переданы любые символы.

Формат дайджеста

Наименование поля	Описание поля	Пример
externalId	Идентификатор документа, присвоенный сервисом (UUID)	550e8400-e29b-41d4-a716-446655440000
date	Дата составления документа	2019-02-20
number	Номер документа	111
orgTaxNumber	ИНН пользователя	7733812920
orgName	Наименование организации пользователя	Общество с ограниченной ответственностью "Клиент"
account	Номер счета пользователя	40802810600000200000
bic	БИК банка пользователя	044525225
admissionType	Тип зачисления	2
authPersonName	ФИО уполномоченного сотрудника организации пользователя	Иванов Алексей Сергеевич
authPersonTel	Номер телефона уполномоченного сотрудника организации пользователя	+74951234567
employeesNumber	Количество сотрудников	10
amount	Месячный фонд оплаты труда	10000
offerAgree	Согласие с Условиями предоставления услуг и Тарифами	true
entrepreneur	Признак является ли организация ИП	0
identityDoc.firstName	Имя	Иван
identityDoc.lastName	Фамилия	Иванов
identityDoc.middleName	Отчество	Иванович
identityDoc.typeCode	Код вида ДУЛ	21
identityDoc.typeName	Наименование ДУЛ	Паспорт гражданина Российской Федерации
identityDoc.serial	Серия ДУЛ	1111
identityDoc.number	Номер ДУЛ	111111
identityDoc.issueDate	Дата выдачи ДУЛ	2019-02-20
identityDoc.issuer	Кем выдан ДУЛ	ОВД г.Москва
identityDoc.birthDate	Дата рождения	2000-02-20
identityDoc.birthPlace	Место рождения	г. Москва

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

externalId=550e8400-e29b-41d4-a716-446655440000
date=2019-02-20
number=111
orgTaxNumber=7733812920
orgName=Общество с ограниченной ответственностью "Клиент"
account=40802810600000200000
bic=044525225
admissionType=2
authPersonName=Иванов Алексей Сергеевич
authPersonTel=+74951234567
employeesNumber=10
amount=10000
offerAgree=true
entrepreneur=0
firstName=Иван
lastName=Иванов
middleName=Иванович
typeCode=21
typeName=Паспорт гражданина Российской Федерации
serial=1111
number=111111
issueDate=2019-02-20
issuer=ОВД г.Москва
birthDate=2000-02-20
birthPlace=г.Москва

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

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

Шаги

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

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

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

Авторизационный токен передается в параметре Authorization заголовка запроса.

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

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

Наименование	Описание
Параметры заголовка
Authorization (String)	Access token полученный через SSO Пример: `Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1`
Параметры запроса
externalId (String)	Идентификатор документа, присвоенный клиентом

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

curl -X GET --header 'Accept: /' --header 
'Authorization: Bearer c76fb018-27c9-43f7-a751-62646eda7e1a-1'
'https://edupirfintech.sberbank.ru:9443/fintech/api/v1/salary-agreement-requests/22a6dd81-103a-4d3a-8e9b0ba4b5211002/state'

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

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

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

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

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

Код состояния документа	Наименование статуса	Назначение кода состояния
	Промежуточные статусы/Продолжать опрашивать
`ACCEPTED`	Принят	Электронный документ принят на стороне Банка
`ACCEPTED_BY_CRM`	Принят CRM	Электронный документ был передан менеджеру
`CREATED`	Создан	Документ записан в БД, проверки не выполнялись
`DELIVERED`	Доставлен	Запрос доставлен в ДБО и взят в обработку
`EXPORTED`	Выгружен	Электронный документ выгружен Банком в АБС
`SIGNED`	Подписан	ЭД подписан предусмотренным для него комплектом подписей
	Окончательные статусы/Прекратить опрос
`CHECKERROR`	Ошибка контроля	ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками.
`INVALIDEDS`	ЭП/АСП не верна	Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
`REQUISITEERROR`	Ошибка выгрузки в CRM	Ошибка выгрузки в CRM
`UNABLE_SEND_TO_CRM`	Ошибка реквизитов	В ЭД указаны ошибочные реквизиты
	Окончательные(Успешные) статусы/Прекратить опрос
`IMPLEMENTED`	Исполнен	Электронный документ исполнен Банком

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

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

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	BASE64
- (minus)	+
_ (underline)	/

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

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

Код возврата	Описание кода возврата	Причина возникновения
200 (GET-запрос)	`ОК`
201 (POST-запрос)	`CREATED`
	Создан
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`
	Сервис временно недоступен	Проводятся технические работы

Обновлено 27 апреля 2022

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

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