Прийом на роботу (Employee Onboarding)¶

Прийом на роботу - це задача, яка дозволяє автоматизувати процес найму нового співробітника, включаючи створення та підписання необхідних документів, валідацію анкетних даних та переведення співробітника в статус "працює".

Компанія може мати кілька шаблонів задачі "Прийом" (наприклад, окремі для штатних співробітників і стажерів). Через API можна створити шаблон, отримати список шаблонів та змінити базові налаштування шаблону (назва, статус, автозавершення, вимоги до полів у мобільному застосунку). Склад документів шаблону налаштовується лише через веб-інтерфейс Вчасно.Кадри. При створенні задачі шаблон обирається полем template_version_identifier; якщо його не передати, використовується найраніше створений активний шаблон "Прийом" компанії (див. Вибір шаблону без template_version_identifier).

Особливості задачі "Прийом"¶

Задача "Прийом" відрізняється від інших задач наступними особливостями:

1. Валідація анкетних даних - можливість відправити анкету співробітника на заповнення та валідацію через спеціальні ендпоінти /submit-questionnaire та /submit-approve-questionnaire
2. Автоматичний перевід співробітника в статус "працює" - після завершення всіх маршрутів задачі, співробітник автоматично отримує статус working
3. Прив'язка до співробітника зі статусом candidate або draft - задачу можна створити тільки для співробітників, які ще не працюють

Статуси задачі¶

Задача "Прийом" має наступні статуси:

Статуси маршруту задачі (Task Route)¶

Кожен маршрут в задачі має свій статус:

Типи маршрутів для задачі "Прийом"¶

Задача "Прийом" може містити наступні типи маршрутів:

Статуси документів¶

Документи в рамках задачі "Прийом" мають наступні статуси:

Статуси підписантів¶

Кожен підписант документа має свій статус:

Робота з анкетними даними (Questionnaire)¶

Одна з ключових особливостей задачі "Прийом" - можливість роботи з анкетними даними співробітника. Це дозволяє:

1. Відправити анкету співробітнику через маршрут типу questionnaire_sent
2. Отримати заповнені дані від співробітника
3. Провалідувати дані через маршрут типу questionnaire_validation
4. Зберегти дані в профілі співробітника

Ендпоінти для роботи з анкетою (v2)¶

Актуальна версія роботи з анкетою — v2. Тіло запиту має формат {employee, blocks}, узгоджений із конфігурацією анкети (блоки та поля), замість попереднього формату v1 {employee, documents, social_statuses}.

GET /api/public/v2/employee-onboarding/{task_id}/questionnaire-definition - отримати визначення (конфігурацію) анкети, закріпленої за задачею. Кожен блок і поле мають стабільний version_identifier, тож клієнт може кешувати конфігурацію та виявляти зміни схеми між запитами.

GET /api/public/v2/employee-onboarding/{task_id}/questionnaire - отримати відповіді анкети (у форматі блоків), які заповнив співробітник.

POST /api/public/v2/employee-onboarding/{task_id}/submit-questionnaire - відправити заповнену анкету на валідацію. Дані будуть збережені, але анкета залишиться на етапі валідації (is_questionnaire_approved=false).

POST /api/public/v2/employee-onboarding/{task_id}/submit-approve-questionnaire - відправити та затвердити анкету одночасно. Дані будуть збережені та анкета буде затверджена (is_questionnaire_approved=true), маршрут questionnaire_validation автоматично завершиться.

Застаріло (v1): ендпоінти POST /api/public/v1/employee-onboarding/{task_id}/submit-questionnaire та POST /api/public/v1/employee-onboarding/{task_id}/submit-approve-questionnaire (формат EmployeeProfileUpdateSerializer з документами та соціальними статусами) залишаються для зворотної сумісності, але рекомендується використовувати v2.

Детальніше про структуру профілю співробітника див. в документації Employee.

Очікувана послідовність дій для задачі "Прийом"¶

Базовий сценарій без анкети¶

1. Створити задачу "Прийом". Передавати ID співробітника (initiator_id) на цьому кроці не обов'язково: якщо його не вказати, система створить нового співробітника у статусі «Кандидат» на основі переданих полів (first_name, last_name, phone тощо). Якщо initiator_id вказано — співробітник повинен мати статус candidate або draft

2. Отримати створену задачу та її маршрути

3. Отримати документи для підпису

4. При необхідності, створити додаткові документи

5. При необхідності, завантажити файл документу

6. Отримати список підписантів документа

7. При необхідності, додати або видалити підписантів

8. Відправити документи на підписання

9. При необхідності, надіслати нагадування підписанту

10. Скачати підписаний документ

Сценарій з анкетою¶

Якщо в шаблоні задачі налаштовано маршрути questionnaire_sent та questionnaire_validation, послідовність дій може бути наступною:

1. Створити задачу "Прийом"

2. Система автоматично відправить анкету співробітнику через маршрут questionnaire_sent

3. Співробітник заповнює анкету через веб-інтерфейс або через інтеграцію

4. Отримати визначення (конфігурацію) анкети, щоб знати структуру блоків і полів:

5. За потреби — отримати поточні відповіді анкети:

6. Відправити заповнену анкету на валідацію через API:

7. Після перевірки даних, затвердити анкету:

8. Після затвердження анкети, маршрут questionnaire_validation автоматично завершиться

9. Продовжити роботу з документами (кроки 3-10 з базового сценарію)

Додаткові операції¶

Робота з шаблонами "Прийом"¶

Отримати список шаблонів "Прийом" компанії (активних і неактивних). Для створення задачі можна використовувати лише активні шаблони:

Створити новий шаблон або оновити наявний за ідентифікатором версії шаблону. Новий шаблон отримує стандартний набір документів (анкета, заява, наказ, особова картка, переведення в статус "працює"):

Приклад: окремий шаблон для стажерів¶

1. Створити шаблон:

   POST /api/public/v1/employee-onboarding/template
   
   {
       "name": "Прийом стажера",
       "is_auto_complete": false
   }
   

   Відповідь 200 OK:

   {
       "detail": {
           "version_identifier": "3f6c1a2e-8d4b-4c1e-9a7f-2b5d6e8f0a13",
           "type": "employee_onboarding",
           "name": "Прийом стажера",
           "status": "active",
           "is_auto_complete": false,
           "mobile_name_requirement": null,
           "mobile_description_requirement": null
       }
   }
   

2. Переглянути шаблони компанії — version_identifier з цього списку передається при створенні задачі:

   GET /api/public/v1/employee-onboarding/template?page_num=1&page_size=100
   

   {
       "detail": {
           "items": [
               {
                   "version_identifier": "9b2e4d71-5a3c-4f08-b6e1-7c9d0a4f2e55",
                   "type": "employee_onboarding",
                   "name": "Прийом на роботу",
                   "status": "active",
                   "is_auto_complete": null,
                   "mobile_name_requirement": null,
                   "mobile_description_requirement": null
               },
               {
                   "version_identifier": "3f6c1a2e-8d4b-4c1e-9a7f-2b5d6e8f0a13",
                   "type": "employee_onboarding",
                   "name": "Прийом стажера",
                   "status": "active",
                   "is_auto_complete": false,
                   "mobile_name_requirement": null,
                   "mobile_description_requirement": null
               }
           ],
           "page_num": 1,
           "page_size": 100,
           "has_prev": false,
           "has_next": false,
           "total_items": 2,
           "total_pages": 1
       }
   }
   

3. Створити задачу з обраного шаблону:

   POST /api/public/v1/employee-onboarding
   
   {
       "template_version_identifier": "3f6c1a2e-8d4b-4c1e-9a7f-2b5d6e8f0a13",
       "first_name": "Олена",
       "last_name": "Коваль",
       "phone": "+380501234567"
   }
   

4. Змінити налаштування шаблону або вимкнути його. Передаються лише поля, які треба змінити; version_identifier шаблону при цьому не змінюється:

   PATCH /api/public/v1/employee-onboarding/template/3f6c1a2e-8d4b-4c1e-9a7f-2b5d6e8f0a13
   
   {
       "status": "inactive"
   }
   

   Неактивний шаблон лишається у списку шаблонів, і його можна знову ввімкнути, передавши "status": "active".

Можливі помилки при створенні задачі з template_version_identifier:

Вибір шаблону без template_version_identifier¶

Якщо поле template_version_identifier не передано, шаблон обирається так:

1. Серед активних шаблонів "Прийом" компанії береться той, що був створений найраніше. Зазвичай це стандартний шаблон, який компанія отримує при підключенні, тож поява нових шаблонів не змінює поведінку наявних інтеграцій.
2. Якщо активних шаблонів немає — береться найраніше створений шаблон незалежно від статусу. Так інтеграції компаній, у яких єдиний шаблон деактивовано, продовжують працювати.

Дата створення шаблону — це дата його першого збереження. Редагування шаблону у веб-інтерфейсі чи через PATCH на неї не впливає, тож шаблон, обраний за замовчуванням, від цього не зміниться.

Приклад: у компанії є стандартний шаблон «Прийом на роботу» (створений першим) і доданий пізніше «Прийом стажера», обидва активні. Запит без template_version_identifier створить задачу зі стандартного шаблону. Якщо стандартний шаблон деактивувати, такі задачі створюватимуться з «Прийом стажера».

Якщо в компанії кілька активних шаблонів "Прийом", рекомендуємо завжди передавати template_version_identifier явно — тоді вибір шаблону не залежить від того, які шаблони існують у компанії.

Оновлення задачі¶

Задачу можна оновити через ендпоінт PATCH /api/public/v1/employee-onboarding/{task_id}:

Можна оновити наступні поля: - name - назва задачі - status - статус задачі (для скасування задачі передайте canceled) - cancellation_reason - причина скасування - manager_id - ID менеджера задачі

Оновлення документа¶

Документ можна оновити через ендпоінт PATCH /api/public/v1/employee-onboarding/{task_id}/document/{document_id}:

Видалення документа¶

Документ можна видалити через ендпоінт DELETE /api/public/v1/employee-onboarding/{task_id}/document/{document_id}:

Список всіх задач "Прийом"¶

Отримати список всіх задач "Прийом" можна через ендпоінт GET /api/public/v1/employee-onboarding:

Підтримуються наступні фільтри (TaskFilterParams):

Скасування задачі¶

Скасувати задачу "Прийом" можна через ендпоінт POST /api/public/v1/employee-onboarding/{task_id}/cancel:

Маршрути задачі¶

Отримати повний список маршрутів задачі з інформацією про виконавців та статуси:

Перевизначення підписантів документа¶

Замінити список підписантів документа (видаляє старих і додає нових):

Погодження¶

Отримати список маршрутів погодження задачі та перевизначити погоджувачів:

Вкладення задачі¶

Отримати список додатків (вкладень) задачі:

Дозволені формати файлів для завантаження¶

При завантаженні документів через ендпоінт POST /api/public/v1/employee-onboarding/{task_id}/document/{document_id}/upload підтримуються наступні формати: - PNG, JPEG, JPG, SVG - PDF - XLS, XLSX, CSV - DOC, DOCX - TXT, XML

Поля для створення задачі "Прийом"¶

¹ Обов'язкове лише при створенні нового співробітника (коли initiator_id не передано). ² Обов'язкове при skip_questionnaire=true та створенні нового співробітника. ³ Обов'язкове при skip_questionnaire=true, sign_type=corporate та створенні нового співробітника.

Поля в відповіді при отриманні задачі¶

Важливі моменти¶

1. Співробітник повинен бути в статусі candidate або draft - якщо передано initiator_id, не можна створити задачу "Прийом" для співробітника, який уже має статус working, fired або archived. Якщо initiator_id не передано, нового співробітника буде автоматично створено у статусі candidate.

2. Блокування редагування співробітника - під час активної задачі "Прийом" (статус new або in_progress), співробітник заблокований для редагування через інші API.

3. Автоматичний перевід в статус working - залежить від налаштування шаблону задачі (документ make_employee_working, поле config.type), яке у ВЕБі відповідає блоку «Переведення співробітника в статус "Працює"»:

   • task_done — співробітник переводиться в статус working одразу після успішного завершення задачі (статус completed);
   • first_working_day — співробітник переводиться в статус working у перший робочий день (коли настане date_joined), навіть якщо задачу завершено раніше. Перевід виконується фоновим завданням.

4. Послідовність відправлення документів - документи можна відправляти на підписання послідовно або одночасно, залежно від налаштувань шаблону задачі. Якщо налаштовано послідовне підписання, то наступний документ можна відправити тільки після повного підписання попереднього.

5. Зміна підписантів - підписантів можна додавати та видаляти тільки до моменту відправлення документа на підписання.

6. Підписанти зі статусом working - в якості підписантів можна використовувати тільки співробітників зі статусом working.

7. Анкета та профіль - дані з анкети зберігаються в профіль співробітника і можуть включати документи та соціальні статуси. Після затвердження анкети, дані стають частиною профілю співробітника.