Зарплатная ведомость

URL для отправки запросов

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

  • Тестовый контур https://edupirfintech.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://edupirfintech.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-agreement/transport-packages позволяет получить список идентификаторов транспортных пакетов, чтобы запрашивать входящие в его состав документы в рамках зарплатного проекта.

Шаги

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

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

Для получения списка идентификаторов транспортных пакетов необходимо отправить GET-запрос (/v1/salary-agreement/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) Номер зарплатного договора
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://edupirfintech.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-agreement/transport-packages/{externalId}/print

Ресурс позволяет получать печатную форму транспортного пакета по идентификатору в формате pdf.

Шаги

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

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

Для получения печатной формы транспортного пакета необходимо отправить GET-запрос (/v1/salary-agreement/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://edupirfintech.sberbank.ru:9443/fintech/api/v1/salary-agreement/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.

Статус регистрации самозанятого в ФНС и результат регистрации самозанятого в ФНС передаются в параметрах ответа (в employeeSalaries)

Если зарплатный договор с резервированием, 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) Сообщение из банка по сотруднику ,
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",
"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) Сообщение из банка по сотруднику ,
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, то они сохраняются вместе с документом, а сам документ продвигается дальше по своему жизненному циклу. если ЭП не была/и передана/ы, то документ сохраняется в своем начальном статусе и ожидает дальнейшего подписания в интерфейсе СББОЛ.

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

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

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

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

Формирование электронной подписи (ГОСТ 2012)

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

Наименование поля Описание поля Пример
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
#

Пример дайджеста (договор зарплатной ведомости без резервирования)

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
incomeTypeCode=1
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://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 преобразования:

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

В ответе на запрос сервер возвращает JSON-документ, который содержит реквизитный состав подготовленного черновика рублевого платежного поручения в статусе Создан.

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

Код возврата Описание кода возврата Причина возникновения
200 (GET-запроса) CREATED
Создан
201 (PUT-запрос) 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 (Fintech API), доступ к которому не предусмотрен настройками scope; У пользователя отсутствует оферта с внешним сервисом.
415 JWS_EXCEPTED
В соответствии с текущими настройками сервиса с clientId=%s необходимо использовать запрос в формате JWS Compact Serialization Ошибка возникает, если в настройках внешних сервисов выставлен флаг "Требуется подпись для внешнего сервиса"
500 UNKNOWN_EXCEPTION
Внутренняя ошибка сервера
503 UNAVAILABLE_RESOURCE_EXCEPTION
Сервис временно недоступен Проводятся технические работы