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

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

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

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

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'

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

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

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

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

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

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

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

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

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

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

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

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

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

externalId=550e8400-e29b-41d4-a716-446655440000
date=2019-02-20
number=111
orgTaxNumber=7733812920
orgName=Общество с ограниченной ответственностью "Клиент"
account=40802810600000200000
bic=044525225
admissionType=2
authPersonName=Иванов Алексей Сергеевич
authPersonTel=+7(495)1234567
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.

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

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"

Модель и пример ответа

{

"bankStatus": "CREATED",

"bankComment": null,

"channelInfo": null

}

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

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

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

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.

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