API методы сервиса «Timesheet»

API методы сервиса «Timesheet»

API cервисa «Электронный табель» предоставляет возможность вызывать следующие методы:

1. Группа методов «Табель».

1.1. «/calendar/get-data-for-department», GET-запрос. Получить данные о кодах и часах из табеля на определенный месяц и отдел. Среди данных также будет итоговая информация по каждому из сотрудников. Входящие параметры:

id_department — идентификатор отдела\подразделения(целое число). Обязательный параметр.

date — месяц и год, на которые требуется извлечь данные из табеля. Необязательный параметр, если не задан, то будет равен текущему месяцу. Формат «m.Y», например 02.2023

Возвращаемое значение(в случае успешного выполнения запроса):

{
  "status": 1,
  "data": <информация о сотрудниках>
}

Информация о сотрудниках — это массив элементов и каждый элемент содержит следующую информацию:

"ordering_number" - порядковый номер;
"countDays" - количество дней;
"name_employee" - ФИО сотрудника;
"timesheet_number" - табельный номер сотрудника;
"position_in_organization" - должность сотрудника;
"hours"(перечисление заполненных часов на даты месяца)
 {
        "d18": 8,
        "d19": 8,
        "d20": 8,
        "d21": 8,
        "d22": 8,
        "d23": 8,
        "d24": 8,
        "d25": 8,
        "d26": 8,
        "d9": 8,
        "d16": 3,
        "d3": 0,
        "d4": 0,
        "d6": 0,
        "d7": 0,
        "d1": "",
        "d2": "",
        "d5": "",
        "d8": "",
        "d10": "",
        "d11": "",
        "d12": "",
        "d13": "",
        "d14": "",
        "d15": "",
        "d17": "",
        "d27": "",
        "d28": "",
        "d29": "",
        "d30": "",
        "d31": ""
} формат имени d<number date>;
"sumHoursFirstPartMonth" - количество рабочих часов в первой половине месяца;
"sumHoursSecondPartMonth" - количество рабочих часов во второй половине месяца;
"sumHoursWholeMonth" - количество рабочих часов месяца;
"sumWorkDaysFirstPartMonth" - количество рабочих дней в первой половине месяца;
"sumWorkDaysSecondPartMonth" - количество рабочих дней во второй половине месяца;
"sumWorkDaysWholeMonth" - количество рабочих дней месяца;
"visiting"(перечисление заполненных кодов на даты месяца) {
        "d18": "Я",
        "d19": "Я",
        "d20": "Я",
        "d21": "Я",
        "d22": "Я",
        "d23": "Я",
        "d24": "Я",
        "d25": "Я",
        "d26": "Я",
        "d9": "Я",
        "d16": "Я",
        "d3": "В",
        "d4": "В",
        "d6": "K",
        "d7": "K",
        "d1": "",
        "d2": "",
        "d5": "",
        "d8": "",
        "d10": "",
        "d11": "",
        "d12": "",
        "d13": "",
        "d14": "",
        "d15": "",
        "d17": "",
        "d27": "",
        "d28": "",
        "d29": "",
        "d30": "",
        "d31": ""
} формат имени d<number date>
"countOverTimeHours" - количество сверхурочных часов за месяц;
"countNightHours" - количество ночных часов за месяц;
"countDaysTempDisworkingWithPayment" - количество дней(за месяц) нетрудоспособности с оплатой;
"countWeekendAndHolidayHours" - количество праздничных и выходных дней за месяц;
"countDaysMiss" - количество дней неявок за месяц;
"zp" - размер заработной платы;

К оглавлению.

2. Группа методов «Подразделения».

2.1. «/department/find-by», GET-запрос. Найти отделения. Входящие параметры:

id — идентификатор отдела\подразделения(целое число). Не обязательный параметр.

name — наименование отдела\подразделения(строка). Не обязательный параметр. Поиск по этому параметру проводится как вхождение строки в любой части целевой.

Если не заданы параметры, то возвращает список всех доступных отделов\подразделений.

Возвращаемое значение:

{
  "status": 1,
  "data": <отделы>
}

Отделы — массив элементов, каждый из которых содержит параметры:

"id" - идентификатор отдела\подразделения;
"name" - наименование отдела\подразделения;
"status" - статус отдела\подразделения;
"base_rate" - базовая ставка отдела\подразделения;

К оглавлению.

2.2. «/department/add-one», GET-запрос. Добавить отделение. Входящие параметры: 

name - (строка, макс. длина 255) наименование добавляемого подразделения.

В случае успешного выполнения запроса результат например следующий:

{
  "status": 1,
  "data": {
    "id": 11719,
    "name": "Подразделение через API",
    "status": 1
  }
}

При возникновении ошибки в ходе выполнения запроса результат например следующий:

{
  "status": 0,
  "data": {
    "name": [
      "Значение «Имя» должно содержать максимум 255 символов."
    ]
  }
}

К оглавлению.

2.3. «/department/update-one», GET-запрос. Обновить существующее отделение. Входящие параметры: 

id - (целое число) идентификатор обновляемого подразделения.
name - (строка, макс. длина 255) новое наименование обновляемого подразделения.

В случае успешного выполнения запроса результат например следующий: 

{
  "status": 1,
  "data": {
    "id": 11719,
    "name": "Подразделение через API с длинным названием"
  }
}

При возникновении ошибки в ходе выполнения запроса результат например следующий: 

{
  "status": 0,
  "data": "Не найдено подразделение с таким ID"
}

К оглавлению.

3. Группа методов «Должности».

3.1. «/position-of-employee/find-by», GET-запрос. Найти должности. Входящие параметры:

id — идентификатор должности(целое число). Не обязательный параметр.

name — наименование должности(строка). Не обязательный параметр. Поиск по этому параметру проводится как вхождение строки в любой части целевой.

Если не заданы параметры, то возвращает список всех доступных должностей.

Возвращаемое значение:

{
  "status": 1,
  "data": <должности>
}

Должности — массив элементов, каждый из которых содержит параметры:

"id" - идентификатор должности;
"name" - наименование должности;
"rate" - ставка должности;

К оглавлению.

3.2. «/position-of-employee/add-one», GET-запрос. Добавить должность. Входящие параметры:

name - (строка, макс. длина 255) наименование добавляемой должности.

В случае успешного выполнения запроса результат например следующий:

{
  "status": 1,
  "data": {
    "id": 5747,
    "name": "Должность из API"
  }
}

К оглавлению.

3.3. «/position-of-employee/update-one», GET-запрос. Обновить существующую должность. Входящие параметры:

id - (целое число) идентификатор обновляемой должности.
name - (строка, макс. длина 255) новое наименование обновляемой должности.

В случае успешного выполнения запроса результат например следующий: 

{
  "status": 1,
  "data": {
    "id": 5747,
    "name": "Обновленное название должности из API"
  }
}

К оглавлению.

4. Группа методов «Пользователи».

4.1. «/user/find-by», GET-запрос. Найти сотрудника(ов). Входящие параметры:

id — идентификатор сотрудника(целое число). Не обязательный параметр.

name — ФИО сотрудника(строка). Не обязательный параметр. Поиск по этому параметру проводится как вхождение строки в любой части целевой.

ext_id — внешний идентификатор сотрудника(целое число). Не обязательный параметр.

email — адрес электронной почты сотрудника(строка). Не обязательный параметр. Поиск по точному соответствию.

name_position — должность сотрудника(строка). Не обязательный параметр. Поиск по этому параметру проводится как вхождение строки в любой части целевой.

Если не заданы параметры, то возвращает список всех сотрудников.

Возвращаемое значение:

{
   "status": 1,
   "data": <сотрудники>
 }

Сотрудники — массив элементов, каждый из которых содержит параметры:

"id" - идентификатор сотрудника,
"email" - эл. почта сотрудника,
"timesheet_number" - табельный номер сотрудника,
"day_rate" - дневная ставка сотрудника,
"month_rate" - месячный оклад сотрудника,
"gender" - пол(0 - мужской, 1 - женский),
"working_rate" - ставка сотрудника,
"name" - ФИО сотрудника,
"position_name" - наименование должности сотрудника,
"work_periods_in_departments" - периоды работы в подразделениях.

Каждый элемент массива «work_periods_in_departments» содержит следующие параметры:

{
   "index": 2 - порядковый номер,
   "id_work_period": 7 - уникальный идентификатор периода 
    работы сотрудника в отделении
   "id_department": 2 - уникальный идентификатор подразделения,
   "start_date": "02.05.2023" - начало периода работы сотрудника в 
    подразделении,
   "end_date": "03.05.2023" - конец периода работы сотрудника в         
    подразделении
},

К оглавлению.

4.2. «/user/add-few», POST-запрос. Добавить\обновить сотрудника(ов). Входящие параметры:

users — JSON массив элементов-сотрудников. Каждый элемент может содержать параметры:

"id" - ID(идентификатор) сотрудника,
"ext_id" - внешний ID сотрудника,
"name" - ФИО сотрудника,
"timesheet_number" - табельный номер сотрудника,
"position_name" - наименование должности сотрудника

Если сотрудник есть в базе, то его параметры(ФИО, должность) обновляются. Поиск сотрудника проводится по параметрам: id или ext_id или timesheet_number.

Возвращаемое значение:

{
«status»: 1,
«data»: <информация>
}

Информация содержит следующие данные:

«countUpdatedUsers» — количество обновленных сотрудников, «countAddedUsers» — количество добавленных сотрудников, «errors» — информация об ошибках при выполнении.

К оглавлению.

4.3. «/user/enlist-to-department», GET-запрос. Зачислить сотрудника в подразделение. Входящие параметры:

id_target_department - (целое число)идентификатор подразделения, в который зачисляется сотрудник.
id_user - (целое число) идентификатор сотрудника, который зачисляется в подразделение.
date_enlist - дата(формат d.m.Y, например: 03.01.2023), начиная с которой зачисляется сотрудник в подразделение.

Возвращаемое значение при успешном выполнении запроса:

{
  "status": 1,
  "data": "Пользователь(сотрудник) зачислен в подразделение"
}

Возвращаемое значение при возникновении ошибки во время выполнении запроса, например:

{
  "status": 0,
  "data": "Ошибка. Период работы '1' в подразделении пересекается по датам с периодом работы '3' в подразделении"
}

Конечная дата периода работы в подразделении считается по формуле: date_enlist + 1 год.

К оглавлению.

4.4. «/user/fire-from-department», GET-запрос. Исключить сотрудника из подразделения. Входящие параметры: 

id_department - (целое число)идентификатор подразделения, из которого исключается сотрудник.
id_user - (целое число) идентификатор сотрудника, который исключается из подразделения.
date_fire - дата(формат d.m.Y, например: 03.01.2023), начиная с которой исключается сотрудник из подразделения. Дата окончания периода, в течение которого сотрудник числился в подразделении.

Возвращаемое значение при успешном выполнении запроса: 

{
  "status": 1,
  "data": "Пользователь(сотрудник) исключен из подразделения."
}

Возвращаемое значение при возникновении ошибки во время выполнении запроса, например: 

{
  "status": 0,
  "data": "Не найдет период работы в подразделении для этого сотрудника с учетом даты исключения из отдела"
}

Данный метод работает следующим образом: находит последний период работы сотрудника и если этот период в заданном подразделении и дата увольнения попадает в этот период, то конечная дата этого периода становится равной той, которая задается в качестве параметра.

К оглавлению.

4.5. «/user/move-to-another-department», GET-запрос. Перевести сотрудника из одного подразделения в другое. Входящие параметры:

id_source_department - (целое число)идентификатор подразделения, из которого переводится сотрудник. 
id_target_department - (целое число)идентификатор подразделения, в который зачисляется сотрудник.
id_user - (целое число) идентификатор сотрудника, который переводится из подразделения в подразделение.
date_move - дата(формат d.m.Y, например: 03.01.2023) перевода сотрудника. Дата зачисления + 1 день в целевое подразделение, дата исключения сотрудника из исходного подразделения.

Возвращаемое значение при успешном выполнении запроса:

{
  "status": 1,
  "data": "Пользователь(сотрудник) переведен из одного подразделения в другое"
}

Возвращаемое значение при возникновении ошибки во время выполнении запроса, например: 

{
  "status": 0,
  "data": "Дата перевода не попадает в последний период работы в исходном отделе для переводимого сотрудника."
}

Конечная дата периода работы в целевом подразделении равна: date_move + 1 год.

К оглавлению.

Обсуждение закрыто.