Співробітник (Employee)¶

Співробітник - це особа, яка працює в компанії. Кожен співробітник має унікальний ідентифікатор, ім'я, прізвище, посаду та інші атрибути.

API ендпоінти для роботи зі співробітниками¶

POST /api/public/v1/employee - створити нового співробітника
GET /api/public/v1/employee - отримати список співробітників
GET /api/public/v1/employee/{employee_id} - отримати співробітника за ID
PATCH /api/public/v1/employee/{employee_id} - оновити дані співробітника
GET /api/public/v1/employee/{employee_id}/profile - отримати профіль співробітника
POST /api/public/v1/employee/{employee_id}/profile - оновити профіль співробітника

Повна довідка полів співробітника¶

Базові поля¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`first_name`	string	Ім'я співробітника	Так (для POST)	Мін. 1 символ	"Іван"
`last_name`	string	Прізвище співробітника	Так (для POST)	Мін. 1 символ	"Петренко"
`middle_name`	string \| null	По-батькові	Ні	-	"Олександрович"
`date_of_birth`	date \| null	Дата народження	Ні	Формат ISO 8601 (YYYY-MM-DD)	"1990-05-15"

Контактні дані¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`email`	string \| null	Особиста електронна пошта	Ні	Валідний email формат	"[email protected]"
`work_email`	string \| null	Робоча електронна пошта	Так для `sign_type=corporate`	Валідний email формат	"[email protected]"
`phone`	string \| null	Номер телефону	Ні	Формат: +380XXXXXXXXX	"+380501234567"

Важливо: Якщо sign_type=corporate, поле work_email обов'язкове, бо доступ до системи буде надаватися саме по цьому email.

Ідентифікаційні дані¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`ipn`	string \| null	ІПН (РНОКПП) або номер паспорта	Рекомендовано	10 цифр для ІПН	"1234567890"
`company_number`	string \| null	Табельний номер	Ні	Унікальний в межах компанії	"00123"
`external_id`	string \| null	Зовнішній ідентифікатор	Ні	До 255 символів	"EXT-12345"

Примітка: ipn не є унікальним полем - можна створити декількох співробітників з однаковим ІПН, але різними табельними номерами (наприклад, для сумісництва).

Посада та дати¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`position`	string \| null	Посада співробітника	Ні	До 255 символів	"Старший розробник"
`date_joined`	date \| null	Дата прийому на роботу	Ні	Формат ISO 8601 (YYYY-MM-DD)	"2024-01-15"

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

Поле	Тип	Опис	Обов'язкове	Можливі значення	За замовчуванням
`status`	enum	Статус співробітника	Ні	`candidate`, `draft`, `working`, `fired`, `archived`	`working`
`sign_type`	enum	Тип підписання	Ні	`personal`, `corporate`	`personal`

Статуси: - candidate - кандидат, не може бути призначений на задачі (крім "Прийом") - draft - чернетка, базовий статус при створенні - working - працює, доступний для всіх задач - fired - звільнений, недоступний для нових задач - archived - архівований, повністю недоступний

Типи підписання: - personal - доступ по ІПН, для всіх адміністраторів компанії в ЕДО - corporate - доступ по work_email, лише для конкретного користувача

Організаційна структура¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`group_id`	UUID \| null	ID підрозділу (відділу)	Ні	Існуючий ID групи	"123e4567-e89b-12d3-a456-426614174000"
`leader_id`	UUID \| null	ID адміністративного керівника	Ні	Існуючий ID співробітника зі статусом `working`	"987e6543-e21b-12d3-a456-426614174001"
`managerial_leader_id`	UUID \| null	ID управлінського керівника	Ні	Існуючий ID співробітника зі статусом `working`	"987e6543-e21b-12d3-a456-426614174002"

Системні поля (тільки для читання)¶

Поле	Тип	Опис
`id`	UUID	Унікальний ідентифікатор співробітника
`company_id`	UUID	ID компанії
`user_status`	enum	Статус користувача в ЕДО: `active`, `inactive`, `invited`
`invite_sent_at`	datetime \| null	Дата відправлення запрошення в ЕДО
`date_created`	datetime	Дата створення запису
`date_updated`	datetime	Дата останнього оновлення

Приклади запитів¶

Створення співробітника з мінімальними даними¶

POST /api/public/v1/employee
{
  "first_name": "Іван",
  "last_name": "Петренко"
}

Система автоматично встановить: - status: working - sign_type: personal - company_number: автоматично згенерований

Створення співробітника з повними даними¶

POST /api/public/v1/employee
{
  "first_name": "Марія",
  "last_name": "Коваленко",
  "middle_name": "Володимирівна",
  "ipn": "3456789012",
  "email": "[email protected]",
  "work_email": "[email protected]",
  "phone": "+380671234567",
  "position": "HR Manager",
  "date_joined": "2024-01-15",
  "date_of_birth": "1988-03-22",
  "company_number": "00456",
  "status": "working",
  "sign_type": "corporate",
  "leader_id": "123e4567-e89b-12d3-a456-426614174000",
  "group_id": "987e6543-e21b-12d3-a456-426614174001",
  "external_id": "HR-001"
}

Створення кандидата для подальшого онбордингу¶

POST /api/public/v1/employee
{
  "first_name": "Олександр",
  "last_name": "Сидоренко",
  "middle_name": "Миколайович",
  "email": "[email protected]",
  "phone": "+380931234567",
  "position": "Junior Developer",
  "status": "candidate"
}

Після цього можна створити задачу "Прийом на роботу" для цього співробітника.

Оновлення даних співробітника¶

PATCH /api/public/v1/employee/{employee_id}
{
  "position": "Senior Developer",
  "work_email": "[email protected]",
  "sign_type": "corporate"
}

Правила валідації та бізнес-логіка¶

1. Залежність полів¶

sign_type=corporate → work_email обов'язковий
leader_id / managerial_leader_id → повинні посилатися на співробітників зі статусом working
group_id → повинен існувати в компанії

2. Унікальність¶

company_number - унікальний в межах компанії
ipn - НЕ унікальний (можливі дублі для сумісництва)
external_id - НЕ унікальний

3. Обмеження за лімітом¶

Кожна компанія має ліміт співробітників (за замовчуванням 20). Ліміт перевіряється для співробітників зі статусами: - draft - working

Співробітники зі статусами candidate, fired, archived НЕ враховуються в ліміт.

4. Переходи статусів¶

Дозволені переходи статусів:

candidate → draft → working → fired → archived
    ↓         ↓        ↓
archived  archived  archived

Важливо: - З candidate в working можна перейти лише через задачу "Прийом на роботу" - З working в fired через задачу "Звільнення" - В archived можна перейти з будь-якого статусу

5. Валідація email¶

Повинен відповідати стандартному формату email (RFC 5322)
Приклади валідних: [email protected], [email protected]
Приклади невалідних: user@, @example.com, user.example.com

6. Валідація телефону¶

Формат: +380XXXXXXXXX (міжнародний формат для України)
Приклади валідних: +380501234567, +380671234567, 0501234567, 380501234567

7. Валідація дат¶

Формат ISO 8601: YYYY-MM-DD
date_of_birth - не може бути в майбутньому
date_joined - може бути в майбутньому (для запланованого прийому)

Помилки та їх вирішення¶

Помилка	Причина	Рішення
`company_number already exists`	Табельний номер вже використовується	Використати інший `company_number` або не передавати (автогенерація)
`work_email is required for corporate sign type`	Не вказано `work_email` для `sign_type=corporate`	Додати поле `work_email`
`Employee limit exceeded`	Перевищено ліміт співробітників компанії	Архівувати непотрібних співробітників або збільшити ліміт
`leader_id must be a working employee`	Керівник не має статус `working`	Використати ID співробітника зі статусом `working`
`Invalid email format`	Неправильний формат email	Перевірити формат email
`Invalid phone format`	Неправильний формат телефону	Використати формат `+380XXXXXXXXX`
`Employee not found`	Неправильний `employee_id`	Перевірити ID співробітника
`Cannot edit employee with active onboarding`	Співробітник заблокований під час онбордингу	Завершити або скасувати задачу "Прийом"

Індивідуальний податковий номер (ІПН) (`ipn`)¶

Це не унікальне поле, яке використовується для ідентифікації співробітника в системі, і за допомогою нього видається доступ користувачам при підписі власним Фізичної Особи. Дозволяється створення декількох співробітників з однаковим ІПН, але з різними табельними номерами.

Табельний номер (`company_number`)¶

Це обов'язкове поле, яке використовується для ідентифікації співробітника в межах компанії. Табельний номер повинен бути унікальним для кожного співробітника в межах компанії. Якщо при створенні нового співробітника вказано табельний номер, який вже існує в системі, буде повернуто помилку. При створенні співробітника з тим же ІПН, але з іншим табельним номером, система дозволяє створити нового співробітника. Це може бути корисно, якщо співробітник працює на різних посадах (за сумісництвом), і до кожної з посад проводяться окрема облікова політика. З одним ІПНом може бути створено декілька співробітників, але з однаковим табельним номером - лише один.

Зовнійшний ідентифікатор (`external_id`)¶

Це необов'язкове поле, яке може бути використано для ідентифікації співробітника в зовнішніх системах. Наприклад, це може бути ID співробітника з іншої системи, з якою інтегрується Вчасно.Кадри. Це поле не є унікальним, і може бути використано для зберігання будь-якої інформації, яка допоможе ідентифікувати співробітника в зовнішніх системах.

Статуси співробітника (`status`)¶

Співробітник може мати наступні статуси:

candidate - кандидат, який ще не почав працювати в компанії. Не доступний для назначення у задачі, крім задачі "Прийом на роботу".
draft - базовий статус при створенні співробітника. Використовується для перевірки даних перед остаточним створенням.
working - статус, який назначається системою після успішного створення і валідації співробітника. Після переходу в цей статус співробітник стає доступним для всіх задач.
fired - статус, який назначається після звільнення співробітника. Співробітник більше не може бути призначений на нові задачі, але залишається в системі для історії.
archived - статус, який назначається після ручного видалення/архівації співробітника. Співробітник більше не доступний для задач, але залишається в системі для історії.

Кожна компанія має ліміт кількості співробітників (20 за замовчуванням). Ліміт перевіряється при створенні нового співробітника у статусі draft або working. Якщо ліміт перевищено, співробітник не може бути створений. При архівуванні співробітника або переведення у статус candidate, співробітник більше не враховується в ліміт.

Тип підписання (`sign_type`)¶

Співробітник може мати різні типи підписання, які визначають, який саме користувач отримує доступ до задач співробітника, і може підписувати документи.

personal - доступ надається по ІПН (ipn). До співробітника будуть мати доступ усі користувачі ЕДО, у яких є адмінська роль в компанії з таким же ЄДРПОУ.
corporate - доступ надається по робочій пошті (work_email). До співробітника буде мати доступ лише користувач з цим імейлом. Роль буде видана автоматично при створенні співробітника з таким типом підписання, або при зміні типу підписання на corporate.

Підрозділ (`group_id`)¶

ID підрозділу співробітника. (Документація по сутності Підрозділ)

Лідери співробітника (`leader_id` та `managerial_leader_id`)¶

Лідери використовуються для вказання підписантів у задачах, які створюються для співробітника. Вони є такими ж співробітниками, тому очікуються ID цієї ж сутності.

leader_id - ID Адміністративного керівника співробітника
managerial_leader_id - ID Управлінського Керівника співробітника

Профіль співробітника (Employee Profile)¶

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

API ендпоінти для роботи з профілем¶

GET /api/public/v1/employee/{employee_id}/profile - отримати профіль співробітника з усіма документами та соціальними статусами.

POST /api/public/v1/employee/{employee_id}/profile - оновити профіль співробітника, включаючи документи та соціальні статуси.

Структура профілю¶

Профіль співробітника складається з трьох основних частин:

Базова інформація - ім'я, прізвище, по-батькові, дата народження, стать, контактні дані
Документи - паспорт, ІПН, адреса, освіта, військовий облік, свідоцтва тощо
Соціальні статуси - інвалідність, учасник бойових дій, багатодітна сім'я тощо

Документи (Employee Documents)¶

Кожен співробітник може мати необмежену кількість документів різних типів. Кожен документ має наступну структуру:

Поле	Тип	Опис
`id`	UUID	Унікальний ідентифікатор документа
`document_type`	EmployeeDocumentType	Тип документа (див. таблицю нижче)
`raw_data`	object	Дані документа (структура залежить від типу документа)
`media_file_ids`	UUID[]	Масив ID прикріплених файлів (сканів документа)
`source`	string	Джерело створення документа (manual, diia, api тощо)

Типи документів (EmployeeDocumentType)¶

Тип документа	Опис	Ключові поля в raw_data
`personal-data`	Особисті дані	`first_name`, `last_name`, `middle_name`, `birth_date`, `email`, `gender`
`internal-passport`	Паспорт громадянина України (ID-картка)	`issue_date`, `department`, `document_number`
`foreign-passport`	Закордонний паспорт	`issue_date`, `department`, `document_number`
`taxpayer-card`	РНОКПП (ІПН)	`taxpayer_number`
`refusal-taxpayer-card`	Відмова від надання РНОКПП	`has_refusal` (boolean)
`birth-certificate`	Свідоцтво про народження дитини	`first_name`, `last_name`, `birth_date`, `document_number`
`user-birth-record`	Власне свідоцтво про народження	Аналогічно `birth-certificate`
`marriage-act-record`	Свідоцтво про шлюб	`spouse_first_name`, `spouse_last_name`, `marriage_date`
`divorce-act-record`	Свідоцтво про розлучення	`divorce_date`, `document_number`
`not-married-status`	Статус неодруженого/розлученого/вдівця	`marital_status`
`education-document`	Документ про освіту (диплом, атестат)	`study_form`, `study_type`, `institution`, `specialization`, `diploma_number`, `date_of_issue`
`no-education`	Відсутність освіти	Порожній об'єкт або `has_no_education` (boolean)
`residence-data`	Місце реєстрації (прописка)	`address`, `city`, `region`, `country`, `house_number`, `apartment_number`
`actual-residence-data`	Місце фактичного проживання	Аналогічно `residence-data`
`military-registration-document`	Військово-обліковий документ	`service_fitness`, `registration_category`, `document_series`, `composition`, `rank`, `specialization`, `authority`
`not-conscripted`	Не військовозобов'язаний	`reason`
`reference-internally-displaced-person`	Довідка ВПО	`reference_number`, `issue_date`
`driver-license`	Водійське посвідчення	`document_number`, `issue_date`, `expiry_date`
`vehicle-license`	Техпаспорт	`vehicle_registration_number`, `vehicle_brand`, `vehicle_model`
`student-id-card`	Студентський квиток	`student_id`, `institution`, `issue_date`
`pension-card`	Пенсійне посвідчення	`pension_number`, `issue_date`
`veteran-certificate`	Посвідчення ветерана	`certificate_number`, `issue_date`
`residence-permit-temporary`	Посвідка на тимчасове проживання	`permit_number`, `issue_date`, `expiry_date`
`residence-permit-permanent`	Посвідка на постійне проживання	`permit_number`, `issue_date`
`name-change-act-record`	Актовий запис про зміну імені	`old_name`, `new_name`, `change_date`
`income-report`	Довідка про доходи	`report_year`, `total_income`

Приклад структури документа¶

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "internal-passport",
  "raw_data": {
    "issue_date": "2020-01-15",
    "department": "1234",
    "document_number": "123456789"
  },
  "media_file_ids": [
    "987e6543-e21b-12d3-a456-426614174001",
    "987e6543-e21b-12d3-a456-426614174002"
  ],
  "source": "manual"
}

Соціальні статуси визначають пільги та особливі умови, які застосовуються до співробітника згідно з законодавством України. Кожен співробітник може мати декілька соціальних статусів одночасно.

Типи соціальних статусів (SocialStatus)¶

Тип соціального статусу	Опис	Можливі пільги
`person_with_disability_group_1`	Особа з інвалідністю групи 1	Скорочений робочий тиждень, додаткова відпустка, податкові пільги
`person_with_disability_group_2`	Особа з інвалідністю групи 2	Скорочений робочий тиждень, додаткова відпустка, податкові пільги
`person_with_disability_group_3`	Особа з інвалідністю групи 3	Податкові пільги, додаткова відпустка
`person_with_child_with_disability`	Особа з дитиною з інвалідністю	Скорочений робочий час, додаткова відпустка
`combatant_war_veteran_invalid`	Учасник бойових дій / Ветеран війни / Інвалід війни	Додаткова відпустка (14 днів), податкові пільги
`chernobyl_catastrophe_affected`	Особа, постраждала внаслідок Чорнобильської катастрофи	Додаткова відпустка (14 днів), податкові пільги
`large_family`	Багатодітна сім'я (3+ дітей)	Соціальні пільги, додаткова відпустка
`single_parent`	Одинока мати або батько	Податкові пільги, заборона звільнення за певних умов
`child_guardian`	Опікун/піклувальник дитини	Соціальні пільги, додаткова відпустка
`ato_oos_defender`	Учасник АТО / ООС / Захисник України	Додаткова відпустка (14 днів), податкові пільги
`pension_age_or_privileged`	Особа пенсійного віку або з пільговими умовами	Податкові пільги
`internally_displaced_person`	Внутрішньо переміщена особа (ВПО)	Соціальні пільги
`caregiver_for_sick_relative`	Особа, яка доглядає за хворим родичем	Додаткова відпустка, можливість скороченого робочого дня

Структура соціального статусу¶

Поле	Тип	Опис
`id`	UUID	Унікальний ідентифікатор соціального статусу
`social_status_type`	SocialStatus	Тип соціального статусу (див. таблицю вище)
`active_status`	string	Статус активності: `active` (активний) або інші значення
`documents`	UUID[]	Масив ID документів, які підтверджують цей соціальний статус

Приклад структури соціального статусу¶

{
  "id": "456e7890-e12b-34c5-d678-426614174003",
  "social_status_type": "person_with_disability_group_2",
  "active_status": "active",
  "documents": [
    "789e0123-e45b-67c8-d901-426614174004"
  ]
}

Важливі моменти при роботі з профілем¶

Валідація документів - кожен тип документа має свої правила валідації. Наприклад, паспорт повинен мати номер та дату видачі, освітній документ - назву закладу та спеціальність.
Медіа файли - файли зображень або сканів документів зберігаються окремо і прикріплюються до документа через масив media_file_ids. Спочатку потрібно завантажити файл через відповідний ендпоінт, отримати його ID, а потім використати цей ID при створенні/оновленні документа.
Оновлення профілю - при оновленні профілю через POST /api/public/v1/employee/{employee_id}/profile передається повна структура профілю. Існуючі документи та соціальні статуси, які не передані в запиті, будуть видалені.
Соціальні статуси та документи - кожен соціальний статус повинен бути підтверджений відповідними документами. Наприклад, статус person_with_disability_group_2 вимагає наявності медичної довідки про інвалідність.
Використання в задачі "Прийом" - профіль співробітника активно використовується в процесі найму через задачу "Прийом на роботу". Анкета, яка заповнюється співробітником або HR-спеціалістом, зберігається в профіль і може бути оновлена через ендпоінти /submit-questionnaire та /submit-approve-questionnaire.
Джерела даних - документи можуть бути створені вручну (source: "manual"), імпортовані з Дія (source: "diia"), або створені через API (source: "api"). Це допомагає відстежувати походження даних.

Приклад повної структури профілю¶

{
  "employee": {
    "first_name": "Іван",
    "last_name": "Петренко",
    "middle_name": "Олександрович",
    "birth_date": "1990-05-15",
    "gender": "male",
    "email": "[email protected]",
    "phone": "+380501234567"
  },
  "documents": [
    {
      "document_type": "internal-passport",
      "raw_data": {
        "issue_date": "2020-01-15",
        "department": "1234",
        "document_number": "123456789"
      },
      "media_file_ids": ["file-id-1", "file-id-2"]
    },
    {
      "document_type": "taxpayer-card",
      "raw_data": {
        "taxpayer_number": "1234567890"
      },
      "media_file_ids": ["file-id-3"]
    },
    {
      "document_type": "education-document",
      "raw_data": {
        "study_form": "full_time",
        "study_type": "higher",
        "institution": "Київський політехнічний інститут",
        "specialization": "Програмна інженерія",
        "diploma_number": "КВ 12345678",
        "date_of_issue": "2012-06-30"
      },
      "media_file_ids": ["file-id-4"]
    }
  ],
  "social_statuses": [
    {
      "social_status_type": "ato_oos_defender",
      "active_status": "active",
      "documents": ["file-id-5"]
    }
  ]
}