Переведення (Employee Transfer)¶
Переведення — це задача, яка автоматизує процес кадрового переміщення співробітника: зміну посади, підрозділу, керівника або управлінського керівника. У межах задачі створюється, погоджується та підписується пакет кадрових документів («Заява про переведення», «Наказ про переведення»), після чого зміни застосовуються до профілю співробітника.
Налаштування шаблону задачі «Переведення» доступне лише через вебінтерфейс Вчасно.Кадри. Публічний API дозволяє створювати задачі на основі вже налаштованих шаблонів, керувати документами й підписантами, а також отримувати статус і підписані файли — що й використовується для інтеграції зі сторонніми ERP.
Статуси та їх переходи¶
Статуси задачі¶
| Статус | Опис |
|---|---|
new |
Задача створена, документи можна додавати та редагувати |
in_progress |
Хоча б один документ відправлено на підписання / триває погодження |
completed |
Усі документи підписані, задача завершена, переведення застосоване |
canceled |
Задача скасована |
Переходи: new → in_progress → completed або canceled.
Статуси маршруту¶
| Статус | Опис |
|---|---|
new |
Маршрут створений, але ще не активний |
in_progress |
Маршрут активний (документи на підписанні або погодження триває) |
completed |
Маршрут завершений |
canceled |
Маршрут скасований |
Статуси документа¶
| Статус | Опис |
|---|---|
new |
Документ створений, але ще не відправлений на підписання |
in_progress |
Документ на підписанні |
completed |
Документ підписаний усіма підписантами |
canceled |
Документ скасований |
Статуси підписанта / погоджувача¶
| Статус | Опис |
|---|---|
new |
Підписанта (погоджувача) додано, документ ще не надіслано |
completed |
Підписант підписав (погоджувач погодив) документ |
declined |
Підписант відхилив підписання (погоджувач відхилив погодження) |
Поля для створення задачі «Переведення»¶
| Поле | Тип | Опис | Обов'язкове |
|---|---|---|---|
initiator_id |
UUID | ID співробітника, якого переводять | Так |
external_id |
string | Зовнішній ідентифікатор задачі для інтеграції з ERP. Має бути унікальним у межах компанії, використовується для ідемпотентного опитування | Ні |
manager_id |
UUID | ID співробітника-менеджера задачі | Ні |
transfer_date |
date (YYYY-MM-DD) |
Дата, з якої застосовується переведення | Ні |
transfer_new_position |
string | Нова назва посади після переведення | Ні |
transfer_new_group_id |
UUID | ID нового підрозділу | Ні |
transfer_new_leader_id |
UUID | ID нового безпосереднього керівника | Ні |
transfer_new_managerial_leader_id |
UUID | ID нового управлінського керівника | Ні |
skip_application |
bool | Пропустити генерацію заяви про переведення (за замовчуванням false) |
Ні |
skip_order |
bool | Пропустити генерацію наказу про переведення (за замовчуванням false) |
Ні |
skip_employee_form |
bool | Пропустити генерацію анкети співробітника (за замовчуванням false) |
Ні |
Поля у відповіді при отриманні задачі¶
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID задачі |
initiator_id |
UUID | ID співробітника, якого переводять |
manager_id |
UUID | null | ID менеджера задачі |
status |
TaskStatus | Статус задачі: new, in_progress, completed, canceled |
description |
string | null | Опис задачі |
cancellation_reason |
string | null | Причина скасування задачі |
cancelled_by |
TaskCancelledByType | null | Хто скасував: initiator, manager, api, document_decline |
cancelled_by_employee_id |
UUID | null | ID співробітника, який скасував задачу |
cancelled_by_user_id |
UUID | null | ID користувача, який скасував задачу |
cancellation_date |
datetime | null | Дата скасування задачі |
external_id |
string | null | Зовнішній ID задачі |
transfer_date |
date | null | Дата переведення |
transfer_new_position |
string | null | Нова посада |
transfer_new_group_id |
UUID | null | ID нового підрозділу |
transfer_new_leader_id |
UUID | null | ID нового безпосереднього керівника |
transfer_new_managerial_leader_id |
UUID | null | ID нового управлінського керівника |
name |
string | null | Назва задачі |
date_created |
datetime | Дата створення задачі |
date_updated |
datetime | Дата останнього оновлення задачі |
Базовий сценарій роботи¶
-
Створити задачу «Переведення» для співробітника зі статусом
working -
Отримати створену задачу
-
Отримати список маршрутів задачі
-
Отримати список документів задачі
-
За потреби створити додатковий документ
-
За потреби завантажити файл для документа
-
Отримати список підписантів документа
-
За потреби додати або видалити підписантів
-
Відправити документи на підписання. В тілі запиту для кожного документа можна передати контекст генерації (
transfer_application_document_info,transfer_order_document_info) -
За потреби надіслати нагадування підписанту
-
Скачати підписаний документ
Додаткові операції¶
Оновлення задачі¶
Оновити поля переведення або встановити менеджера / ім'я можна через PATCH /api/public/v1/employee-transfer/{task_id}:
Доступні для оновлення поля: name, manager_id, transfer_date, transfer_new_position, transfer_new_group_id, transfer_new_leader_id, transfer_new_managerial_leader_id.
Скасування задачі¶
Обов'язкове поле cancellation_reason.
Маршрути погодження¶
Вкладення задачі¶
Оновлення та видалення документа¶
Інтеграція з ERP: періодичне отримання завершених документів¶
Типовий сценарій для ERP: періодично (наприклад, раз на 5–15 хвилин) опитувати API Вчасно.Кадри, отримувати список завершених задач переведення, забирати підписані файли та застосовувати зміни у власній системі.
1. Отримати список завершених задач¶
GET /api/public/v1/employee-transfer повертає сторінкований список задач і підтримує серверну фільтрацію.
Ключові параметри запиту:
| Параметр | Тип | Призначення |
|---|---|---|
status__in |
array[TaskStatus] | Фільтр за статусом задачі. Для ERP-polling вкажіть completed, за потреби додайте canceled |
start_date |
date | Початок періоду (за date_created задачі) |
end_date |
date | Кінець періоду |
external_id__in |
array[string] | Пошук задач за зовнішніми ідентифікаторами, якими їх було створено з ERP |
initiator__in |
array[UUID] | Фільтр за співробітниками, яких переводять |
manager__in |
array[UUID] | Фільтр за менеджером задачі |
is_approved |
boolean | true — задачу успішно погоджено; false — погодження скасовано |
is_approval_needed |
boolean | true — є незавершене погодження; false — погодження не потрібне або вже завершене |
search |
string | Повнотекстовий пошук |
page, size |
int | Пагінація |
Рекомендований polling-запит: GET /api/public/v1/employee-transfer?status__in=completed&start_date={остання_перевірка}. ERP повинна зберігати дату останнього успішного опитування та на кожній ітерації вичитувати всі сторінки результату.
Для дедуплікації слід використовувати поле external_id: ERP задає його при створенні задачі або перевіряє при обробці вже існуючих задач, щоб не застосувати одне й те саме переведення двічі.
2. Отримати повну інформацію про задачу¶
GET /api/public/v1/employee-transfer/{task_id} повертає один об'єкт зі структурою, описаною в таблиці «Поля у відповіді при отриманні задачі».
3. Отримати документи задачі¶
GET /api/public/v1/employee-transfer/{task_id}/document — список документів у межах задачі.
Поля елемента списку:
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID документа |
name |
string | Назва документа |
status |
TaskRouteStatus | Статус документа (new, in_progress, completed, canceled) |
document_type |
TaskDocumentType | Тип документа (наприклад, transfer_application, transfer_order) |
access_settings |
enum | null | extended або private |
is_parallel_action |
bool | null | Паралельний режим підпису |
document_info |
object | null | Метадані файлу (розмір, mime-type тощо) |
edo_document_id |
string | null | ID документа у системі ЕДО (Вчасно.ЕДО), якщо синхронізовано |
external_id |
string | null | Зовнішній ID документа |
4. Завантажити підписаний файл¶
GET /api/public/v1/employee-transfer/{task_id}/document/{document_id}/download повертає бінарний вміст файлу. Рекомендовано звертатися до цього ендпоінта лише для документів у статусі completed.
5. Отримати статус підписантів¶
GET /api/public/v1/employee-transfer/{task_id}/document/{document_id}/signer повертає список підписантів документа та їхній статус.
Поля:
| Поле | Тип | Опис |
|---|---|---|
executor_id |
UUID | ID співробітника-підписанта |
status |
TaskRouteActionStatus | Статус дії підписанта: new, completed, declined |
Приклади запитів та відповідей¶
Повні OpenAPI-приклади (зі згенерованими зразками тіл запитів і відповідей) завжди актуальні в Swagger UI:
- Swagger UI{target=_blank}
- Redoc{target=_blank}
Блоки <swagger-ui> вище підтягують приклади безпосередньо з живої OpenAPI-схеми, тому вони завжди відповідають реальному API.
Структури даних для вкладених об'єктів¶
Маршрут задачі (PublicApiListVacationRouteSerializer)¶
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID маршруту |
name |
string | Назва маршруту |
order |
int | Порядок у задачі |
route_type |
PublicDocumentType | Тип маршруту |
status |
TaskRouteStatus | Статус |
is_parallel_action |
bool | null | Паралельний режим виконання |
access_settings |
enum | null | extended або private |
document_type |
TaskDocumentType | null | Тип документа (для документних маршрутів) |
external_id |
string | null | Зовнішній ID |
actions |
array[RouteAction] | Список дій (підпис/погодження) |
date_created / date_updated |
datetime | Дати створення/оновлення |
Елемент actions[*] (PublicApiRouteActionSerializer):
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID дії |
executor_id |
UUID | null | ID виконавця (підписанта/погоджувача) |
manager_id |
UUID | null | ID менеджера, що делегував дію |
order |
int | Порядковий номер дії |
status |
TaskRouteActionStatus | new, completed, declined |
action_type |
DocumentActionType | null | Тип дії |
decline_reason |
string | null | Причина відхилення |
date_created / date_updated |
datetime | Дати |
Маршрут погодження (PublicApiApprovalRouteSerializer)¶
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID маршруту погодження |
name |
string | Назва |
order |
int | Порядок |
status |
TaskRouteStatus | Статус маршруту |
is_parallel_action |
bool | null | Паралельний режим |
approvers |
array[ApprovalStep] | Список погоджувачів |
Елемент approvers[*] (PublicApiApprovalStepSerializer):
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID кроку погодження |
executor_id |
UUID | ID співробітника-погоджувача |
order |
int | Порядковий номер |
status |
TaskRouteActionStatus | new, completed, declined |
Вкладення задачі (PublicApiTaskAttachmentSerializer)¶
| Поле | Тип | Опис |
|---|---|---|
id |
UUID | ID вкладення |
employee_id |
UUID | ID співробітника, до якого прив'язане вкладення |
media_file_id |
UUID | ID медіафайлу |
attachment_type |
TaskAttachmentType | null | Тип вкладення |
Контекст генерації документів при відправленні¶
Під час виклику POST /api/public/v1/employee-transfer/{task_id}/send-documents для кожного документа у documents_to_send[] можна передати відповідний контекст:
transfer_application_document_info — контекст заяви про переведення:
| Поле | Тип | Опис |
|---|---|---|
company_leader_position_name |
string | null | Посада керівника компанії (перевизначення заголовка) |
company_name |
string | null | Назва компанії |
company_leader_full_name |
string | null | ПІБ керівника компанії |
full_name |
string | null | ПІБ співробітника (перевизначення) |
position |
string | null | Поточна посада (перевизначення) |
application_section |
string | null | Довільний текст тіла заяви |
application_date_created |
date | Дата заяви |
transfer_order_document_info — контекст наказу про переведення:
| Поле | Тип | Опис |
|---|---|---|
company_name |
string | null | Назва компанії |
company_edrpou |
string | null | ЄДРПОУ компанії |
order_date_created |
date | null | Дата створення наказу |
order_number |
string | null | Номер наказу |
city |
string | null | Місто |
full_name |
string | null | ПІБ співробітника |
order_text_header |
string | null | Заголовок тіла наказу |
order_text_body |
string | null | Основний текст наказу |
order_text_reason |
string | null | Підстава переведення |
order_date_signed |
date | null | Дата підписання наказу |
Дозволені формати файлів для завантаження¶
При завантаженні документів через POST /api/public/v1/employee-transfer/{task_id}/document/{document_id}/upload підтримуються: PNG, JPEG, JPG, SVG, PDF, XLS, XLSX, CSV, DOC, DOCX, TXT, XML.
Важливі моменти¶
- Статус співробітника — задачу «Переведення» можна створити лише для співробітника у статусі
working. - Блокування редагування — під час активної задачі «Переведення» (
newабоin_progress) співробітник заблокований для редагування через інші API, щоб уникнути конфліктів з кадровими даними. - Застосування змін — після завершення задачі (
completed) зміни з полівtransfer_*автоматично застосовуються до профілю співробітника. - Ідемпотентність для ERP — використовуйте
external_idпри створенні задач і при подальшому пошуку (external_id__in), щоб безпечно ретраїти запити і не дублювати записи в ERP. - Порядок відправлення документів — документи можна відправляти послідовно або одночасно залежно від налаштувань шаблону. Якщо шаблон передбачає послідовне підписання, наступний документ можна надіслати лише після повного підписання попереднього.
- Зміна підписантів — додавати та видаляти підписантів можна лише до моменту відправлення документа на підписання.
- Підписанти зі статусом
working— як підписантів можна використовувати лише співробітників у статусіworking.