Зарплатная ведомость
URL для отправки запросов
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://iftfintech.testsbi.sberbank.ru:9443
Промышленный контур
https://fintech.sberbank.ru:9443
Получение информации по договору
Ресурс /v1/salary-agreements
позволяет получить актуальную информацию по зарплатному договору, которую необходимо использовать при формировании зарплатной ведомости и электронного реестра на открытие счетов и выпуск карт.
Авторизация
Для получения информации необходимо отправить GET-запрос (/v1/salary-agreements), в котором в качестве входящего параметра необходимо передать авторизационный токен к данным (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис SALARY_AGREEMENT
.
В случае отсутствия в ответе блока полей commissionInfo необходимо повторить выполнение GET-запроса (/v1/salary-agreements) позднее или обратиться в Банк.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer 70f6c4dd-dd79-41ef-9a35-4b386802d601-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/salary-agreements'
Модель ответа
Параметр | Описание |
---|---|
Модель SalaryAgreements | |
admissionValueTypes (Array [SalaryAgreementAdmissionValueType] optional) | Виды зачислений |
branchBic (string, optional) | БИК подразделения |
branchName (string, optional) | Наименование подразделения |
cardTypes (Array [SalaryAgreementCardType], optional) | Типы пластиковых карт |
contractEndDate (string, optional) | Дата окончания действия договора |
contractNumber (string, optional) | Номер договора |
contractStartDate (string, optional) | Дата начала действия договора |
isReserve (boolean, optional) | Признак резервирования |
orgTaxNumber (string, optional) | ИНН организации пользователя |
osb (string, optional) | Номер отделения сберегательного банка |
placesOfService (Array [SalaryAgreementPlaceOfService], optional) | Места обслуживания |
tb (string, optional) | Номер территориального банка |
Модель SalaryAgreementAdmissionValueType | |
admissionCode (string, optional) | Код зачисления |
admissionName (string, optional) | Наименование зачисления |
admissionType (string, optional) | Тип зачисления |
SalaryAgreementCardType | |
bonusProgramCode (string, optional) | Код бонусной программы |
depositSubtypeCode (string, optional) | Код подвида вклада |
depositTypeCode (string, optional) | Код вида вклада |
endDate (string, optional) | Дата закрытия возможности выпуска карт |
peopleGroupCode (string, optional) | Код категории населения |
peopleGroupName (string, optional) | Название категории населения |
typeCode (string, optional) | Код вида карты |
typeName (string, optional) | Вид карты |
Модель SalaryAgreementCommissionInfo | |
actualDateTime (string, optional) | Дата и время последнего обновления информации банком о неоплаченной комиссии |
currentRate (number, optional) | Текущая ставка тарифа за реестровые зачисления (%) |
diffTariffs (Array [SalaryAgreementDiffTariff], optional) | Дифференцированные тарифы для зарплатных реестров |
invoiceDate (string, optional) | Дата выставления счета и направления детализации |
otherRate (number, optional) | Фиксированная ставка по прочим зачислениям (%) |
periodInfo (SalaryAgreementPeriodInfo, optional) | Информация за расчетный период |
salaryRate (number, optional) | Фиксированная ставка комиссии по зарплатным зачислениям (%) |
Модель SalaryAgreementPlaceOfService | |
osb (string, optional) | Номер отделения сберегательного банка |
placeAddress (string, optional) | Адрес подразделения |
placeCode (string, optional) | Код подразделения |
placeName (string, optional) | Наименование подразделения |
tb (string, optional) | Номер территориального банка |
vsp (string, optional) | Номер внутреннего структурного подразделения |
Модель SalaryAgreementDiffTariff | |
admissionTypeCode (string) | Тип зачисления = ['Other', 'Salary'] stringEnum:"Other", "Salary" |
endAmount (number) | Конечная сумма диапазона выплат |
fromAmount (number) | Начальная сумма диапазона выплат |
tariffRate (number) | Тарифная ставка (%) |
Модель SalaryAgreementPeriodInfo | |
commissionAmount (number) | Сумма начисленной комиссии за расчетный период |
endDate (string) | Дата окончания расчетного периода |
payAmount (number) | Сумма выплат за расчетный период |
startDate (string) | Дата начала расчетного периода |
Пример ответа
[
{
"admissionValueTypes":[
{
"admissionCode":"01",
"admissionName":"Заработная плата",
"admissionType":"Зарплатный"
}
],
"branchBic":"044525225",
"branchName":"ПАО СБЕРБАНК",
"cardTypes":[
{
"bonusProgramCode":"11",
"depositSubtypeCode":"11",
"depositTypeCode":"11",
"endDate":"2018-12-31",
"peopleGroupCode":"111",
"peopleGroupName":"Зарплатная",
"typeCode":"11",
"typeName":"Visa Classic"
}
],
"commissionInfo":{
"actualDateTime":"2018-12-31T23:59:59",
"currentRate":1.01,
"diffTariffs":[
{
"admissionTypeCode":"Other",
"endAmount":1.01,
"fromAmount":1.01,
"tariffRate":1.01
}
],
"invoiceDate":"2018-12-31",
"otherRate":1.01,
"periodInfo":{
"commissionAmount":1.01,
"endDate":"2018-12-31",
"payAmount":1.01,
"startDate":"2018-12-31"
},
"salaryRate":1.01,
"totalDebitAmount":1.01
},
"contractEndDate":"2018-12-31",
"contractNumber":"10000001",
"contractStartDate":"2018-12-31",
"isReserve":false,
"orgTaxNumber":"7707083893",
"osb":"1111",
"placesOfService":[
{
"osb":"1111",
"placeAddress":"г.Москва, Кутузовский проспект, 34",
"placeCode":"1111111111",
"placeName":"Доп офис 1111",
"tb":"11",
"vsp":"1111"
}
],
"tb":"11"
}
]
Получение списка идентификаторов
Ресурс /v1/salary-agreements/transport-packages
позволяет получить список идентификаторов транспортных пакетов, чтобы запрашивать входящие в его состав документы в рамках зарплатного проекта.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения списка идентификаторов транспортных пакетов необходимо отправить GET-запрос (/v1/salary-agreements/transport-packages), в котором в качестве входящего параметра передать авторизационный токен к данным (Acces Token). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис SALARY_AGREEMENT
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | |
Access token организации-клиента/собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 | |
Параметры запроса | |
page (Number) | Номер запрашиваемой страницы. По умолчанию 100 записей на странице. |
salaryAgreementNumber (String) | Номер зарплатного договора Значение contractNumber из ответа GET /v1/salary-agreements |
periodStartDate (Date) | Дата начала платежного периода По умолчанию: текущая дата минус месяц Формат: yyyy-MM-dd |
periodEndDate (Date) | Дата конца платежного периода По умолчанию: текущая дата Формат: yyyy-MM-dd |
isViewed (Boolian) | Признак того был ли отображен этот пакет ранее Значения: true, false По умолчанию: false |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer 70f6c4dd-dd79-41ef-9a35-4b386802d601-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/salary-agreements/transport-packages?page&salaryAgreementNumber&periodStartDate&periodEndDate&isViewed'
Модель ответа
Наименование | Описание |
---|---|
{ | |
_links[ { | |
href (String) | Абсолютный или относительный адрес, |
rel (String) | Отношение ссылки к текущей сущности (next, prev) |
} ], | |
transportPackages [ { | |
externalId (String) | Внешний идентификатор транспортного пакета, |
packageDate (Date) | Дата формирования транспортного пакета, |
periodEndDate (Date) | Дата окончания расчетного периода, |
periodStartDate (Date) | Дата начала расчетного периода, |
salaryAgreementDate (Date) | Дата зарплатного договора, который связан с данным пакетом, |
salaryAgreementNumber (String) | Номер зарплатного договора |
} ] | |
} |
Пример ответа
{
"_links": [ {
"href": "?accountNumber=40702810500006103990&statementDate=2018-03-15&page=3",
"rel": "next"
} ],
"transportPackages": [ {
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"packageDate": "2018-12-31",
"periodEndDate": "2018-12-31",
"periodStartDate": "2018-12-31",
"salaryAgreementDate": "2018-12-31",
"salaryAgreementNumber": "1"
} ]
}
Получение печатной формы
Ресурс /v1/salary-agreements/transport-packages/{externalId}/print
позволяет получать печатную форму транспортного пакета по идентификатору в формате pdf.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения печатной формы транспортного пакета необходимо отправить GET-запрос (/v1/salary-agreements/transport-packages/{externalId}/print), в котором в качестве входящего параметра передать авторизационный токен к данным (Access Token). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис SALARY_AGREEMENT
.
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token организации-клиента/собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Параметры запроса | |
externalId (String) | Внешний идентификатор транспортного пакета Формат: UUID |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer 70f6c4dd-dd79-41ef-9a35-4b386802d601-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/salary-agreements/transport-packages/a0000000-0000-0000-0000-000000000001/print'
Модель ответа
Наименование | Описание |
---|---|
{ | |
file (String): | Файл выписки в формате Base64string |
} |
Пример ответа
{
"file": "string"
}
Отправка зарплатной ведомости
Ресурс v1/payrolls
позволяет отправлять зарплатную ведомость.
Шаги
1. Получить AccessToken.
2. Сформировать ЭП.
3. Отправить запрос.
4. Получить статус.
5. Получить документ.
Для создания зарплатной ведомости необходимо отправить POST-запрос (/v1/payrolls), в котором передать авторизационный токен (Access Token) и реквизиты зарплатной ведомости. Авторизационный токен передается в параметре Authorization
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAYROLL
.
Если зарплатный договор с резервированием, PayrollPayDoc не заполняется.
В случае отсутствия в ответe блока commissionInfo необходимо повторить выполнение GET-запроса (/v1/payrolls/{externalId}) позднее или обратиться в Банк.
Модель запроса и ответа (договор зарплатной ведомости с резервированием)
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Параметры тела запроса | |
Payroll { | |
account (string, optional) | Номер счета клиента , Размерность [1 .. 20] , |
admissionValue (string) | Вид зачисления. Необходимо использовать значения полученные из запроса на получение информации по зарплатному договору "Код зачисления " , Размерность [1 .. 2] , |
amount (AmountCurrency) | Итоговая сумма зачисления , Размерность [До точки: 1 .. 16, после точки 1 .. 2] , |
authPersonName (string, optional) | ФИО уполномоченного сотрудника организации пользователя , Размерность [1 .. 60] , |
authPersonTelfax (string, optional) | Номер телефона, факса уполномоченного сотрудника организации пользователя , Размерность [1 .. 40] , |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа , Размерность [1 .. 4000] , |
bankStatus (string, optional, read only) | Статус документа , Размерность [1 .. 255] , |
bic (string) | БИК банка пользователя , Размерность [1 .. 9] , |
contractDate (string) | Дата договора , Дата в формате YYYY-MM-DD , |
contractNumber (string) | Номер договора , Размерность [1 .. 255] , |
date (string) | Дата составления документа , Дата в формате YYYY-MM-DD , |
digestSignatures (Array[Signature], optional) | Электронные подписи по дайджесту документа , |
employeeSalaries (Array[PayrollEmpSalary], optional) | Сотрудники, которым зачисляют зарплату , |
employeesNumber (integer) | Количество сотрудников , |
externalId (string) | Идентификатор документа, присвоенный сервисом (UUID) , |
incomeTypeCode (string, optional) | Код вида дохода получателей выплаты по 229-ФЗ. |
loanAmount (AmountCurrency, optional) | Сумма оплаты за счет кредитных средств , Размерность [До точки: 1 .. 16, после точки 1 .. 2] , |
loanDate (string, optional) | Дата кредитного договора , Дата в формате YYYY-MM-DD , |
loanNumber (string, optional) | Номер кредитного договора , Размерность [1 .. 50] , |
month (string) | Месяц отчетного периода , Размерность [1 .. 2] , |
number (string, optional) | Номер документа , Размерность [1 .. 50] , |
orgName (string) | Наименование организации пользователя , Размерность [1 .. 160] , |
orgTaxNumber (string) | ИНН организации пользователя , Размерность [1 .. 12] , |
payDocs (Array[PayrollPayDoc], optional) | Платежные документы перечисления зарплаты , |
year (string) | Год отчетного периода Размерность [1 .. 4] , |
}AmountCurrency { | |
amount (number) | Сумма , Размерность [До точки: 1 .. 16, после точки 1 .. 2] , |
currencyCode (string) | Цифровой код валюты , Размерность [1 .. 3] , |
currencyName (string) | Буквенный ISO-код валюты, Размерность [1 .. 3] , |
}PayrollCommissionInfo{ | |
actualRate (number, optional, read only) | Фактическая тарифная ставка комиссии (%) , |
actualSum (number, optional, read only) | Фактическая сумма комиссии , |
estimatedRate (number, optional, read only) | Предварительная тарифная ставка комиссии (%) , |
estimatedSum (number, optional, read only) | Предварительная сумма комиссии , |
invoiceDate (string, optional, read only) | Дата выставления счета и направления детализации |
}Signature { | |
base64Encoded (string) | Значение электронной подписи, закодированное в Base64 , |
certificateUuid (string) | Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID) , Размерность [1 .. 36] , |
}PayrollEmpSalary { | |
account (string) | Номер счета сотрудника , Размерность [1 .. 20] , |
amount (AmountCurrency) | Сумма начисления , Размерность [До точки: 1 .. 16, после точки 1 .. 2] , |
bankMessage (string, optional, read only) | Сообщение из банка по сотруднику , Размерность [1 .. 3000] , |
bic (string, optional) | БИК банка сотрудника , Размерность [1 .. 9] , |
firstName (string) | Имя , Размерность [1 .. 1024] , |
withheldAmount (number, optional) | Сумма удержанных средств по исполнительному документу , |
lastName (string) | Фамилия , Размерность [1 .. 1024] , |
middleName (string, optional) | Отчество , Размерность [1 .. 1024] , |
result (string, optional, read only) | Результат начисления, Размерность [1 .. 255] , |
receiptStatus (string, optional) | Статус регистрации дохода самозанятого в ФНС (чек), Размерность [1 .. 255] , |
receiptResult (string, optional) | Результат регистрации дохода самозанятого в ФНС (чек) Размерность [1 .. 255] , |
} | |
Пример запроса
{
"account": "40802810600000200000",
"admissionValue": "01",
"amount": {
"amount": 1.01,
"currencyCode": "840",
"currencyName": "USD"
},
"authPersonName": "Иванов Алексей Сергеевич",
"authPersonTelfax": "8(495)1234567",
"contractDate": "2018-12-31",
"contractNumber": "1",
"date": "2018-12-31",
"digestSignatures": [
{
"base64Encoded": "HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w==",
"certificateUuid": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
],
"employeeSalaries": [
{
"account": "40802810600000200000",
"amount": {
"amount": 1.01,
"currencyCode": "840",
"currencyName": "USD"
},
"bic": "044525225",
"firstName": "Дмитрий",
"lastName": "Петров",
"middleName": "Сергеевич",
"receiptStatus": "Получен",
"result": "string",
"withheldAmount": 1.01
}
],
"employeesNumber": 254,
"externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
"incomeTypeCode": "1",
"loanAmount": {
"amount": 1.01,
"currencyCode": "840",
"currencyName": "USD"
},
"loanDate": "2018-12-31",
"loanNumber": "1234567890",
"month": "Январь",
"number": "1",
"orgName": "Общество с ограниченной ответственностью \"Клиент\"",
"orgTaxNumber": "7707083893",
"payDocs": [
{
"amount": {
"amount": 1.01,
"currencyCode": "840",
"currencyName": "USD"
},
"docDate": "2018-12-31",
"number": "1",
"payeeAccount": "40802810600000200000",
"payeeBic": "044525225",
"payerAccount": "40802810600000200000",
"payerBic": "044525225",
"purpose": "Выплата заработной платы за январь. НДС не облагается."
}
],
"year": "2019"
}
Модель запроса (договор зарплатной ведомости без резервирования)
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token собственной организации, полученный через SSO Пример: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1 |
Параметры тела запроса | |
Payroll { | |
account (string, optional) | Номер счета клиента , |
admissionValue (string) | Вид зачисления. Необходимо использовать значения полученные из запроса на получение информации по зарплатному договору "Код зачисления " , |
amount (AmountCurrency) | Итоговая сумма зачисления , |
authPersonName (string, optional) | ФИО уполномоченного сотрудника организации пользователя , |
authPersonTelfax (string, optional) | Номер телефона, факса уполномоченного сотрудника организации пользователя , |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа , |
bankStatus (string, optional, read only) | Статус документа , |
bic (string) | БИК банка пользователя , |
contractDate (string) | Дата договора , |
contractNumber (string) | Номер договора , |
date (string) | Дата составления документа , |
digestSignatures (Array[Signature], optional) | Электронные подписи по дайджесту документа , |
employeeSalaries (Array[PayrollEmpSalary], optional) | Сотрудники, которым зачисляют зарплату , |
employeesNumber (integer) | Количество сотрудников , |
externalId (string) | Идентификатор документа, присвоенный сервисом (UUID) , |
loanAmount (AmountCurrency, optional) | Сумма оплаты за счет кредитных средств , |
loanDate (string, optional) | Дата кредитного договора , |
loanNumber (string, optional) | Номер кредитного договора , |
month (string) | Месяц отчетного периода , |
number (string, optional) | Номер документа , |
orgName (string) | Наименование организации пользователя , |
orgTaxNumber (string) | ИНН организации пользователя , |
payDocs (Array[PayrollPayDoc], optional) | Платежные документы перечисления зарплаты , |
year (string) | Год отчетного периода |
}AmountCurrency { | |
amount (number) | Сумма , |
currencyCode (string) | Цифровой код валюты , |
currencyName (string) | Буквенный ISO-код валюты |
}PayrollCommissionInfo{ | |
actualRate (number, optional, read only) | Фактическая тарифная ставка комиссии (%) , |
actualSum (number, optional, read only) | Фактическая сумма комиссии , |
estimatedRate (number, optional, read only) | Предварительная тарифная ставка комиссии (%) , |
estimatedSum (number, optional, read only) | Предварительная сумма комиссии , |
invoiceDate (string, optional, read only) | Дата выставления счета и направления детализации |
}Signature { | |
base64Encoded (string) | Значение электронной подписи, закодированное в Base64 , |
certificateUuid (string) | Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID) |
}PayrollEmpSalary { | |
account (string) | Номер счета сотрудника , |
amount (AmountCurrency) | Сумма начисления , |
bankMessage (string, optional, read only) | Сообщение из банка по сотруднику (может прийти пустое поле) , |
bic (string, optional) | БИК банка сотрудника , |
firstName (string) | Имя , |
withheldAmount (number, optional) | Сумма удержанных средств по исполнительному документу , |
lastName (string) | Фамилия , |
middleName (string, optional) | Отчество , |
result (string, optional, read only) | Результат начисления Возможные значения: Зачислено Отвергнут Банком На проверке у специалиста Банка Требуется подтверждение СМС-паролем Не Зачислено |
receiptStatus (string, optional) | Статус регистрации дохода самозанятого в ФНС (чек), |
receiptResult (string, optional) | Результат регистрации дохода самозанятого в ФНС (чек) |
}PayrollPayDoc { | |
amount (AmountCurrency) | Сумма , |
docDate (string) | Дата расчетного документа , |
incomeTypeCode (string, optional) | Код вида дохода получателей выплаты по 229-ФЗ Коды: 1 - При переводе денежных средств, являющихся заработной платой и (или) иными доходами, в отношении которых статьей 99 Федерального закона N 229-ФЗ установлены ограничения, 2 - При переводе денежных средств, являющихся доходами, на которые в соответствии со статьей 101 Федерального закона N 229-ФЗ не может быть обращено взыскание, за исключением доходов, указанных в пунктах 1 и 4 части 1 статьи 101 Федерального закона N 229-ФЗ), 3 - При переводе денежных средств, являющихся видами доходов, на которые в соответствии с пунктами 1 и 4 части 1 статьи 101 Федерального закона N 229- ФЗ не может быть обращено взыскание, |
number (string) | Номер расчетного документа , |
payeeAccount (string) | Номер счета получателя , |
payeeBic (string) | БИК банка получателя , |
payerAccount (string) | Номер счета плательщика , |
payerBic (string) | БИК банка плательщика , |
purpose (string) | Назначение платежного документа |
} |
Передача электронной подписи вместе с документом
В API можно использовать два вида документов: те, которые подписаны электронной подписью (ЭЦП), и те, которые не подписаны.
- Если документ подписан ЭЦП, то он сразу же отправляется на обработку в автоматизированную банковскую систему (АБС банка), при условии, что под документом есть достаточное количество электронных подписей.
- Документ без ЭЦП создается в СберБизнес как черновик. Если клиент не подпишет этот черновик в СберБизнес, то документ не отправится на обработку.
Использование сертификатов ЭЦП в API помогает автоматизировать процесс подписания отправляемых документов.
Требования к ЭЦП:
- Подпись CaDES-BES в формате PEM;
- Подпись открепленная — detatched;
- Алгоритм цифровой подписи ГОСТ Р 34.10-2012 для ключей длины 256 бит;
- Блок с сертификатами (Certificates) обязателен — включает сертификат подписанта;
- Данные подписанта (Signer Info) — содержит информацию только по одному подписанту;
- Присутствует время формирования подписи (Signing Time).
Рекомендация
Проверить сформированную подпись можно на странице Удостоверяющего центра:
- Выбрете раздел «Проверка электронной подписи»
- Выбрете тип электронной подписи - Отсоединенная (электронная подпись содержится в отдельном файле)
Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:
Наименование поля | Описание поля | Пример |
---|---|---|
base64Encoded (string) | Значение ЭП документа | HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w== |
certificateUuid (string) | Идентификатор сертификата, использованного при создании ЭП (можно узнать, обратившись к ресурсу /v1/crypto или /v1/crypto/eio) | 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6 |
В документе можно передать одну или две электронных подписи вместе с реквизитами создаваемого документа. Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл. Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.
Документ может быть подписан следующими наборами подписей:
- одна (единственная) подпись;
- первая и вторая подписи.
При этом нельзя сочетать подпись, имеющую единственное полномочие, с подписью, имеющей первую или вторую подписи.
Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.
Формат дайджеста
Наименование поля | Описание поля | Пример |
---|---|---|
account | Номер счета клиента | 40702810600000001523 |
admissionValue | Вид зачисления (цифровое значение вида зачисления) из справочника видов зачисления SalType | 01 |
amount.amount | Сумма по договору | 1240687.00 |
amount.currencyName | Трехбуквенный код валюты | RUB |
authPersonName | Имя уполномоченного сотрудника организации пользователя | Иванов Алексей Сергеевич |
authPersonTelfax | Номер телефона, факса уполномоченного сотрудника организации пользователя | 8(495)3612541 |
bic | БИК банка пользователя | 044525225 |
contractDate | Дата договора | 2018-02-20 |
contractNumber | Номер договора | 456 |
date | Дата составления документа | 2018-02-20 |
employeesNumber | Количество сотрудников | 300 |
externalId | Идентификатор документа, присвоенный сервисом (UUID) | 550e8400-e29b-41d4-a716-446655440000 |
incomeTypeCode | Код вида дохода получателей выплаты по 229-ФЗ | 1 |
loanAmount | Сумма оплаты за счет кредитных средств | 1000.00 |
loanDate | Дата кредитного договора | 04.03.2019 |
loanNumber | Номер кредитного договора | 155 |
month | Месяц отчетного периода | Январь |
orgName | Наименование организации пользователя | ООО Ромашка |
orgTaxNumber | ИНН пользователя | 222201236445 |
year | Год отчетного периода | 2018 |
TABLES | ||
TABLES=employeeSalaries | ||
account | Номер счета физического лица Счет физического лица (получателя зарплаты) не может быть открыт в стороннем банке. Подразделение Сбербанка определяется в СББОЛ по счету, а именно по цифрам из отмеченных разрядов хххххххххХХХХххххххх | 40702810600000001673 |
amount.amount | Сумма | 675988.00 |
amount.currencyName | Трехбуквенный код валюты | RUB |
firstName | Имя физического лица | Дмитрий |
lastName | Фамилия физического лица | Петров |
middleName | Отчество физического лица | Дмитриевич |
withheldAmount | Сумма удержанных средств по исполнительному документу | 1010.01 |
Не заполняется если в зарплатном договоре стоит признак «с резервированием»! | ||
TABLES=payDocs | ||
amount.amount | Сумма | 675988.00 |
amount.currencyName | Трехбуквенный код валюты | RUB |
docDate | Дата расчетного документа (по местному времени обслуживающего подразделения банка) | 2018-02-20 |
number | Номер расчетного документа | 388 |
payeeAccount | Номер счета получателя | 40702810500006103990 |
payeeBic | БИК банка зачисления | 044525225 |
payerAccount | Номер счета плательщика | 40702810500006103990 |
payerBic | БИК банка плательщика | 044525225 |
purpose | Назначение платежа | Зачисление зарплаты |
Теги дайджеста должны быть отсортированы по алфавиту. Если значение поля не определено, то тег в дайджесте не используется.
Пример дайджеста (договор зарплатной ведомости c резервированием)
account=40702810078452334405
admissionValue=01
amount.amount=10000.55
amount.currencyName=RUB
authPersonName=Иванов Александр Сергеевич
authPersonTelfax=+7(812)1234567
bic=044525225
contractDate=2019-02-04
contractNumber=46096
date=2019-02-04
employeesNumber=2
externalId=b37fbdbc-d7a3-49c4-a191-be8e8b49ffba
incomeTypeCode=1
loanamount=1000.00
loandate=04.03.2019
loanNumber=155
month=Январь
orgName=Организация MuSAAIQKoXSVAFU
orgTaxNumber=4781796357
year=2019
TABLES
Table=EmployeeSalaries
account=42301810600000200001
amount.amount=5000.50
amount.currencyName=RUB
firstName=Иван
lastName=Иванов
middleName=Иванович
withheldAmount=1010.01
#
account=42301810600000200002
amount.amount=5000.05
amount.currencyName=RUB
firstName=Петр
lastName=Петров
middleName=Петрович
withheldAmount=1020.01
#
Пример дайджеста (договор зарплатной ведомости без резервирования)
Если договор зарплатной ведомости без резервирования, то заполнять блок PayDocs в дайджесте не обязательно.
account=40702810078452334405
admissionValue=01
amount.amount=10000.55
amount.currencyName=RUB
authPersonName=Иванов Александр Сергеевич
authPersonTelfax=+7(812)1234567
bic=044525225
contractDate=2019-02-04
contractNumber=46096
date=2019-02-04
employeesNumber=2
externalId=b37fbdbc-d7a3-49c4-a191-be8e8b49ffba
loanamount=1000.00
loandate=04.03.2019
loanNumber=155
month=Январь
orgName=Организация MuSAAIQKoXSVAFU
orgTaxNumber=4781796357
year=2019
TABLES
Table=EmployeeSalaries
account=42301810600000200001
amount.amount=5000.50
amount.currencyName=RUB
firstName=Иван
lastName=Иванов
middleName=Иванович
withheldAmount=1010.01
#
account=42301810600000200002
amount.amount=5000.05
amount.currencyName=RUB
firstName=Петр
lastName=Петров
middleName=Петрович
withheldAmount=1020.01
#
Table=PayDocs
amount.amount=10000.55
amount.currencyName=RUB
docDate=2019-02-04
number=1
payeeAccount=40702810828030026262
payeeBic=044525225
payerAccount=40702810078452334405
payerBic=40702810078452334405
purpose=Назначение платежа
#
Получение статуса зарплатной ведомости
Ресурс /v1/payrolls/{externalId}/state
позволяет получить статус ранее отправленной зарплатной ведомости.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения статуса необходимо отправить GET-запрос ( /v1/payrolls/{externalId}/state ), в котором передать авторизационный токен ( Access Token ) и идентификатор документа ( externalId ). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAYROLL
.
Статус регистрации дохода самозанятых в ФНС передается в параметрах ответа (receiptStatus)
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token полученный через SSO Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1 |
Параметры запроса | |
externalId (String) | Идентификатор документа, присвоенный сервиса |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1'
'https://iftfintech.testsbi.sberbank.ru:9443/fintech/api/v1/payrolls/22a6dd81-103a-4d3a-8e9b-0ba4b527f010/state'
Модель ответа
Наименование | Описание |
---|---|
DocState { | |
bankComment (string, optional, read only) | Банковский комментарий к статусу документа, |
bankStatus (string, optional) | Статус документа, |
receiptStatus (string) | Статус регистрации дохода самозанятого в ФНС (чек) |
} |
Пример ответа
{
"bankStatus": "CREATED",
"bankComment": null,
"receiptStatus": "FINISHED"
}
Возможные статусы
Статус | Значение | Состояние |
---|---|---|
DELIVERED | Доставлен | Промежуточный/Продолжать опрашивать |
VALIDEDS | ЭП/АСП верна | Промежуточный/Продолжать опрашивать |
INVALIDEDS | ЭП/АСП не верна | Конечный/Прекратить опрашивать |
REQUISITEERROR | Ошибка реквизитов | Конечный/Прекратить опрашивать |
TRIED | Проверен | Промежуточный/Продолжать опрашивать |
DELAYED | Приостановлен | Промежуточный/Продолжать опрашивать |
CORRESPONDENT_APPROVE_WAITING | Ожидает подтверждения контрагента | Промежуточный/Продолжать опрашивать |
EXPORTED | Выгружен | Промежуточный/Продолжать опрашивать |
IMPLEMENTED | Исполнен | Успешный конечный/Прекратить опрашивать |
REFUSEDBYABS | Отказан АБС | Конечный/Прекратить опрашивать |
ACCEPTED | Принят | Промежуточный/Продолжать опрашивать |
ACCEPTED_BY_ABS | Принят АБС | Промежуточный/Продолжать опрашивать |
PARTIMPLEMENTED | Частично исполнен | Конечный/Прекратить опрашивать (Для получения подробной информации об исполнении документа выполнить запрос /v1/payrolls/{externalId}) |
CARD2 | Картотека №2 | Промежуточный/Продолжать опрашивать |
FRAUDSMS | Требуется подтверждение паролем | Промежуточный/Продолжать опрашивать |
FRAUDREVIEW | На проверке у специалиста банка | Промежуточный/Продолжать опрашивать |
FRAUDDENY | Отвергнут ФРОД | Конечный/Прекратить опрашивать |
FRAUDSENT | Отправлен во ФРОД | Промежуточный/Продолжать опрашивать |
SIGNED_BANK | Подписан Банком | Промежуточный/Продолжать опрашивать |
REFUSEDBYBANK | Отказан Банком | Конечный/Прекратить опрашивать |
FRAUDALLOW | Одобрен ФРОД | Промежуточный/Продолжать опрашивать |
SIGNED | Подписан | Промежуточный/Продолжать опрашивать |
UNABLE_TO_RECEIVE | Ошибка при приеме | Конечный/Прекратить опрашивать |
CREATED | Создан | Промежуточный/Продолжать опрашивать |
IMPORTED | Импортирован | Промежуточный/Продолжать опрашивать |
PARTSIGNED | Частично подписан | Промежуточный/Продолжать опрашивать |
CHECKERROR | Ошибка контроля | Конечный/Прекратить опрашивать |
INCONSISTENT_DATA | Нарушена целостность документа | Конечный/Прекратить опрашивать |
TRANSIT | Транзитный | Промежуточный/Продолжать опрашивать |
WAITING_FOR_ORDER | Ожидает распоряжения | Промежуточный/Продолжать опрашивать |
WAITING_FOR_MIGRATION | Ожидает миграции | Промежуточный/Продолжать опрашивать |
EXPORTING | Выгружается | Промежуточный/Продолжать опрашивать |
TEMPLATE | Шаблон | Конечный/Прекратить опрашивать |
Ресурс /v1/payrolls/{externalId}
Ресурс позволяет получить документ заранее отправленной зарплатной ведомости с информацией о зачислении по каждому сотруднику.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения документа необходимо отправить GET-запрос (/v1/payrolls/{externalId}), в котором передать авторизационный токен (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAYROLL
.
Статус регистрации самозанятого в ФНС и результат регистрации самозанятого в ФНС передаются в параметрах ответа от SberBusiness API только в ресурсе GET /v1/payrolls/{externalId}" (в employeeSalaries).
Модель запроса
Наименование | Описание |
---|---|
Параметры заголовка | |
Authorization (String) | Access token полученный через SSO Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1 |
Параметры запроса | |
externalId (String) | Идентификатор документа, присвоенный сервисом |
Пример запроса
curl -X GET --header 'Accept: application/json' --header
'Authorization: Bearer f8ad3141-b7e8-4924-92de-3de4fd0a464e-1'
'https://iftfintech.testsbi.sberbank.ru:9443//fintech/api/v1/payrolls/550e8400-e29b-41d4-a716-446655440000'
Модель ответа
Соответствует модели ответа /v1/payrolls.
Дополнительная информация
Подписание запроса транспортной подписью
Content-Type может содержать одно из двух значений:
- application/json – запрос без подписи
- application/jose – запрос, подписанный транспортной подписью
Если Content-Type имеет значение application/jose, то запрос должен содержать данные в виде компактной сериализации RFC 7515: JSON Web Signature (JWS).
JWS состоит из трёх частей:
- Заголовок (Header) - определяет алгоритм подписи и тип токена
- Полезная нагрузка (Payload) - содержит данные, которые необходимо защитить
- Электронная подпись (Signature) - вычисляется с использованием приватного ключа клиента
Base64Url(Header) || ’.’ || Base64Url(Payload) || ’.’ || Base64Url(Signature)
Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.
Signature - это подпись данных приватной частью ключевой пары клиента (используется приватный ключ парный сертификату клиента). Подпись вычисляется по алгоритму указанному в Заголовке (Header) в параметре alg (в нашем случае gost34.10-2012) и вычисляется от исходных данных:
Base64Url(Header) || ‘.’ || Base64Url(Payload).
Формирование исходных данных для вычисления подписи описано в спецификации RFC 7515: JSON Web Signature (JWS).
При кодировании JWS используется преобразование Base64Url. Преобразование можно представить следующим образом:
Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’)
- функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x,
- функция Replace(x,y) заменяет все вхождения символа x на символ y.
Преобразование Base64Url, отличается от Base64 преобразования:
- В Base64Url не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
- Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.
BASE64URL | BASE64 |
---|---|
- (minus) | + |
_ (underline) | / |
Коды возврата
Код возврата | Описание кода возврата | Причина возникновения | |
---|---|---|---|
200 (GET-запроса) | CREATED | ||
Создан | |||
201 (PUT-запрос) | CREATED | ||
Создан | |||
202 | ACCEPTED | ||
Операция не завершена полностью | |||
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 | ||
Операция не может быть выполнена: доступ к ресурсу запрещен | У пользователя нет прав на использование соответствующего сервиса Sber API (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом. | ||
415 | JWS_EXCEPTED | ||
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization | Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса" | ||
500 | UNKNOWN_EXCEPTION | ||
Внутренняя ошибка сервера | |||
503 | UNAVAILABLE_RESOURCE_EXCEPTION | ||
Сервис временно недоступен | Проводятся технические работы |