Удаленное подключение зарплатного проекта
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
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 | ||
Сервис временно недоступен | Проводятся технические работы |
Заметили ошибку?
Выделите текст и нажмите Ctrl
+ Enter
, чтобы сообщить нам о ней