Получение данных по зарплатной ведомости

Обновлено 29 ноября 2024

Компаниям

Холдингам

Платформам

/fintech/api/v1/payrolls/{externalId}

Запрос позволяет позволяет получить полные данные по ранее отправленной зарплатной ведомости. Отправьте GET-запрос с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатором документа (externalId) в path-параметре.

В параметре scope ссылки авторизации пользователя должен быть указан сервис PAYROLL для получения доступа к этому ресурсу.

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

• Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
• Промышленный контур https://fintech.sberbank.ru:9443

Request

/fintech/api/v1/payrolls/{externalId}

• Модель
• Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
Accept	string	string	^(application/json|application/jose)	optional	Указывает на формат данных, который вы готовы принять от Банка. - Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. - Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
PATH PARAMETERS
externalId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Идентификатор документа, присвоенный вами при создании документа

GET /fintech/api/v1/payrolls/7c62a50c-1b9a-4c77-96b3-7b7d3722ea20 HTTP/1.1
Authorization: Bearer bDe6ccc14346dd34aa39C326bd85c42138942c
Accept: */*

Responses

200 (ОК)

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Payroll {
account	string	optional	Номер счета клиента,
admissionValue	string	required	Вид зачисления,
amount	AmountCurrency	required	Итоговая сумма зачисления,
authPersonName	string	optional	ФИО уполномоченного сотрудника организации пользователя,
authPersonTelfax	string	optional	Номер телефона, факса уполномоченного сотрудника организации пользователя,
bankComment	string	optional	Банковский комментарий к статусу документа,
bankStatus	string	optional	Статус документа,
bic	string	required	БИК банка пользователя,
commissionInfo	PayrollCommissionInfo	optional	Тарифы и комиссия зарплатной ведомости,
contractDate	string	required	Дата договора,
contractNumber	string	required	Номер договора,
date	string	required	Дата составления документа,
digestSignatures	Array[Signature]	optional	Электронные подписи по дайджесту документа,
employeeSalaries	Array[PayrollEmpSalary]	optional	Данные сотрудников для зачисления выплаты
employeesNumber	integer	required	Количество сотрудников,
externalId	string	required	Идентификатор документа, который вы присваиваете самостоятельно,
incomeTypeCode	string	optional	Код вида дохода получателей выплаты по 229-ФЗ,
loanAmount	AmountCurrency	optional	Сумма оплаты за счет кредитных средств,
loanDate	string	optional	Дата кредитного договора,
loanNumber	string	optional	Номер кредитного договора,
month	string	required	Месяц отчетного периода,
number	string	optional	Номер документа,
orgName	string	required	Наименование организации пользователя,
orgTaxNumber	string	required	ИНН организации пользователя
payDocs	Array[PayrollPayDoc]	optional	Платежные документы перечисления зарплаты,
year	string	required	Год отчетного периода
}
AmountCurrency {
amount	number	required	Сумма,
currencyCode	string	required	Цифровой код валюты,
currencyName	string	required	Буквенный ISO-код валюты
}
PayrollCommissionInfo {
actualRate	number	optional	Фактическая тарифная ставка комиссии (%),
actualSum	number	optional	Фактическая сумма комиссии,
estimatedRate	number	optional	Предварительная тарифная ставка комиссии (%),
estimatedSum	number	optional	Предварительная сумма комиссии,
invoiceDate	string	optional	Дата выставления счета и направления детализации
}
Signature {
base64Encoded	string	required	Значение электронной подписи (ЭП), закодированное в Base64,
certificateuuid	string	required	Уникальный идентификатор сертификата ключа проверки электронной подписи
}
PayrollEmpSalary {
account	string	required	Номер счета сотрудника,
amount	AmountCurrency	required	Сумма начисления,
bankMessage	string	optional	Сообщение из банка по сотруднику,
bic	string	optional	БИК банка сотрудника,
firstName	string	required	Имя
withheldAmount	number	optional	Сумма удержанных средств по исполнительному документу,
lastName	string	required	Фамилия,
middleName	string	optional	Отчество,
receiptResult	string	optional	Результат регистрации самозанятого в ФНС,
receiptStatus	string	optional	Статус регистрации самозанятого в ФНС,
result	string	optional	Результат начисления
}
PayrollPayDoc {
amount	AmountCurrency	required	Сумма начисления,
docDate	string	required	Дата расчетного документа
number	string	required	Номер расчетного документа
payeeAccount	string	required	Номер счета получателя,
payeeBic	string	required	БИК банка получателя,
payerAccount	string	required	Номер счета плательщика,
payerBic	string	required	БИК банка плательщика,
purpose	string	required	Назначение платежного документа
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8


{
  "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": "Дмитрий",
      "lastName": "Петров",
      "middleName": "Сергеевич",
      "receiptResult": "https://lknpd.nalog.ru/api/v1/receipt/366522706980/2d7yuc/print",
      "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"
} 

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request ресурса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Объект {название объекта} не соответствует модели	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request ресурса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "cause": "WORKFLOW_FAULT",
    "referenceId": "7b0534d6-1d67-4a7d-9254-2f28d1c33091",
    "message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
    "checks": [],
    "fieldNames": null
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959dbbd57490aa9f9ff67fb7380fae5m3"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана операция PAYROLL. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

404 (Not Found)

Cause	Message	Description
NOT_FOUND	Документ с указанным ID не найден

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "NOT_FOUND",
    "referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
    "message": "Документ с указанным ID не найден"
}

429 (Too Many Requests)

Cause	Message	Description
TOO_MANY_REQUESTS	Превышен лимит запросов. Повторите операцию позже.	Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice{
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

json HTTP/1.1 429 Too Many Requests Content-Type: application/json;charset=UTF-8

{ "cause": " TOO_MANY_REQUESTS ", "referenceId": "5650c1e4-5039-4038-8cad-afab64003f61", "message": " Превышен лимит запросов. Повторите операцию позже" }

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}