Зарплатная ведомость
Обновлено 31 января 2023
Для обращения к ресурсу необходимо отправлять запрос на:
Тестовый контур
https://edupirfintech.sberbank.ru:9443Промышленный контур
https://fintech.sberbank.ru:9443
Получение информации по зарплатному договору
Ресурс /v1/salary-agreements позволяет получить актуальную информацию по зарплатному договору, которую необходимо использовать при формировании зарплатной ведомости и электронного реестра на открытие счетов и выпуск карт.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения информации необходимо отправить 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://edupirfintech.sberbank.ru:9443/fintech/api/v1/salary-agreements'
Модель ответа
| Наименование | Описание |
|---|---|
| SalaryAgreements [ | |
| SalaryAgreements 1 | |
| ]SalaryAgreements 1 { | |
| 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/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) | Номер счета клиента , |
| 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) , |
| 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- ФЗ не может быть обращено взыскание, |
| 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) | Результат регистрации дохода самозанятого в ФНС (чек) |
| } | |
Пример запроса
{
"account":"40802810600000200000",
"admissionValue":"01",
"amount":{
"amount":"1.01",
"currencyCode":"840",
"currencyName":"USD"
},
"authPersonName":"Иванов Алексей Сергеевич",
"authPersonTelfax":"8(495)1234567",
"bankComment":"string",
"bankStatus":"string",
"bic":"044525225",
"commissionInfo":{
"actualRate":"1.01",
"actualSum":"1.01",
"estimatedRate":"1.01",
"estimatedSum":"1.01",
"invoiceDate":"2018-12-31"
},
"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"
},
"bankMessage":"string",
"bic": "044525225",
"firstName":"Дмитрий",
"withheldAmount":"1010.01",
"lastName":"Петров",
"middleName":"Сергеевич",
"result":"string"
}
],
"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",
"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) | Назначение платежного документа |
| } |
Передача электронной подписи
Для передачи ЭП под документом используется массив digestSignatures, в котором передаются элементы типа Signature:
| Наименование поля | Описание поля | Пример |
|---|---|---|
| base64Encoded (String) | Значение ЭП документа | HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w== |
| certificateUuid (String) | Идентификатор сертификата, использованного при создании ЭП ( можно узнать, обратившись к ресурсу /v1/crypto) | 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.
Модель запроса
| Наименование | Описание |
|---|---|
| Параметры заголовка | |
| 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://edupirfintech.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 | Нарушена целостность документа | Конечный/Прекратить опрашивать |
Получение документа о зачислении
Ресурс /v1/payrolls/{externalId} позволяет получить документ заранее отправленной зарплатной ведомости с информацией о зачислении по каждому сотруднику.
Шаги
1. Получить AccessToken.
2. Отправить запрос.
Для получения документа необходимо отправить GET-запрос (/v1/payrolls/{externalId}), в котором передать авторизационный токен (Access Token) и идентификатор документа (externalId). Авторизационный токен передается в параметре Authorization заголовка запроса.
Чтобы получить доступ к ресурсу, необходимо передать в scope сервис PAYROLL.
Модель запроса
| Наименование | Описание |
|---|---|
| Параметры заголовка | |
| 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://edupirfintech.sberbank.ru:9443//fintech/api/v1/payrolls/550e8400-e29b-41d4-a716-446655440000'
Модель ответа
Соответствует модели ответа /v1/payrolls.
Дополнительная информация
Подписание запроса транспортной подписью
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 преобразования:
- Используются другие вспомогательные символы Base 64 Encoding with URL and Filename Safe Alphabet.
| BASE64URL | BASE64 |
|---|---|
| - (minus) | + |
| _ (underline) | / |
- В BASE64URL не используется (опускается) padding, т.е. не добавляются знаки ‘=’ на конце закодированного содержимого Padding of Encoded Data.
В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.
Коды возврата
| Код возврата | Описание кода возврата | Причина возникновения | |
|---|---|---|---|
| 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 | ||
| Операция не может быть выполнена: доступ к ресурсу запрещен | У пользователя нет прав на использование соответствующего сервиса SberBusinessAPI (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом. | ||
| 415 | JWS_EXCEPTED | ||
| В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization | Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса" | ||
| 500 | UNKNOWN_EXCEPTION | ||
| Внутренняя ошибка сервера | |||
| 503 | UNAVAILABLE_RESOURCE_EXCEPTION | ||
| Сервис временно недоступен | Проводятся технические работы |