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

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

Варто звернути увагу

При додаванні співробітника в сервіс, коли передається його мобільний номер телефону, співробітник одразу отримує SMS-сповіщення формату:

Вас запрошено до (Назва компанії). Завантажте та авторизуйтеся в застосунку "Вчасно": Створіть свій акаунт співробітника у «Вчасно.Кадри»

Рекомендація: масово додавати співробітників вже у готовий до роботи кабінет компанії, задля запобігання незручностей.

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

POST /api/public/v1/employee - створити нового співробітника
GET /api/public/v1/employee - отримати список співробітників
GET /api/public/v1/employee/{employee_id} - отримати співробітника за ID
PUT /api/public/v1/employee/{employee_id} - оновити дані співробітника
DELETE /api/public/v1/employee/{employee_id} - архівувати співробітника
GET /api/public/v2/company/employee-profile-definition - отримати визначення профілю компанії (доступні блоки та поля з їх ID)
GET /api/public/v2/employee/{employee_id}/profile - отримати профіль співробітника (формат блоків/полів V2)
PUT /api/public/v2/employee/{employee_id}/profile - повністю оновити профіль (REPLACE-семантика)
PATCH /api/public/v2/employee/{employee_id}/profile - частково оновити профіль (MERGE-семантика)

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

Базові поля¶

Поле	Тип	Опис	Обов'язкове	Валідація	Приклад
`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	Статус користувача в ЕДО: `not_exist`, `inactive`, `active`, `invited`, `has_app`
`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 (табельний номер) не генерується системою. Якщо його не передати, поле залишиться порожнім (null).

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

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"
}

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

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

PUT /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). Ліміт враховує співробітників зі статусами: - candidate - draft - working

Співробітники зі статусами 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`)¶

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

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

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

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

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

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

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

Тип підписання (`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.

У новому профілі V2 дані подаються у вигляді блоків (blocks) та полів (fields). Набір блоків і полів налаштовується для кожної компанії окремо (через визначення профілю), тому замість фіксованих типів документів використовуються динамічні block_definition_id та field_definition_id.

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

GET /api/public/v2/company/employee-profile-definition - отримати визначення профілю компанії: перелік усіх доступних блоків та полів разом з їх ідентифікаторами (id блока = block_definition_id, id поля = field_definition_id), типами полів, опціями та правилами валідації. Саме звідси беруться ID, які потрібно передавати при оновленні профілю.

GET /api/public/v2/employee/{employee_id}/profile - отримати профіль співробітника: базові дані (employee) та заповнені блоки з їх полями, значеннями і прикріпленими файлами.

PUT /api/public/v2/employee/{employee_id}/profile - повністю оновити профіль (REPLACE-семантика): блоки, які не передані в запиті, будуть видалені.

PATCH /api/public/v2/employee/{employee_id}/profile - частково оновити профіль (MERGE-семантика): оновлюються лише передані блоки, решта залишаються без змін.

Профіль V1 (GET/POST /api/public/v1/employee/{employee_id}/profile зі структурою documents / social_statuses) вважається застарілим. Нові інтеграції мають використовувати V2.

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

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

employee - базові дані співробітника (ті самі поля, що повертаються при отриманні співробітника).
blocks - список блоків профілю. Кожен блок відповідає визначенню блока (block_definition_id) і містить список полів (fields); кожне поле відповідає визначенню поля (field_definition_id) і має значення (value).

Конкретний перелік блоків та полів (і їх ID) налаштовується для кожної компанії окремо і повертається ендпоінтом визначення профілю (див. нижче). Стандартний набір зазвичай покриває особисті дані, паспорт, РНОКПП (ІПН), адреси, освіту, військовий облік, соціальні статуси тощо. Блок, у якого is_repeatable = true, може повторюватися (декілька екземплярів з тим самим block_definition_id).

Визначення профілю (Profile Definition)¶

Щоб дізнатися, які блоки та поля доступні для компанії і які block_definition_id / field_definition_id передавати при оновленні, використовуйте:

GET /api/public/v2/company/employee-profile-definition

Відповідь містить версію визначення та список блоків. Кожен блок має поля:

Поле	Тип	Опис
`id`	UUID	Ідентифікатор визначення блока — передається як `block_definition_id` при оновленні
`version_identifier`	UUID	Стабільний ідентифікатор версії блока
`version`	int	Номер версії
`name`	string	Назва блока (напр. "Паспорт громадянина України")
`description`	string \| null	Опис блока
`icon`	string \| null	Іконка
`is_repeatable`	bool	Чи може блок повторюватися
`fields`	array	Список визначень полів блока (див. нижче)

Кожне поле у визначенні має:

Поле	Тип	Опис
`id`	UUID	Ідентифікатор визначення поля — передається як `field_definition_id` при оновленні
`version_identifier`	UUID	Стабільний ідентифікатор версії поля
`version`	int	Номер версії
`type`	FieldDefinitionType	Тип поля (див. таблицю типів нижче)
`label`	string	Назва поля
`placeholder`	string \| null	Підказка
`description`	string \| null	Опис
`allow_custom_value`	bool	Чи дозволено власне значення (для `select`/`radio`/тощо)
`validation`	object \| null	Правила валідації
`options`	array \| null	Список опцій (`value`, `label`, `order`) для `select`/`radio`/`multiselect`/`checkbox`
`default_value`	будь-який \| null	Значення за замовчуванням

Типи полів та значення (FieldDefinitionType)¶

Тип поля	Тип `value`	Приклад `value`
`text`, `email`, `phone`, `select`, `radio`	string	`"123456789"`
`number`	число (int/float)	`42`
`boolean`	bool	`true`
`date`	string (YYYY-MM-DD)	`"2020-01-15"`
`date_range`	object `{ "start", "end" }`	`{ "start": "2020-01-01", "end": "2020-12-31" }`
`address`	object	`{ "address", "city", "region", "country", "house_number", "apartment_number" }`
`multiselect`, `checkbox`	масив рядків	`["a", "b"]`
`file`	значення задається згідно з визначенням поля; прикріплені файли повертаються у `media_files` при читанні	-

Приклад визначення профілю¶

{
  "id": "1a2b3c4d-0000-0000-0000-000000000000",
  "version": 1,
  "company_id": "987e6543-e21b-12d3-a456-426614174001",
  "blocks": [
    {
      "id": "b1000000-0000-0000-0000-000000000001",
      "version_identifier": "b1000000-0000-0000-0000-0000000000aa",
      "version": 1,
      "name": "Паспорт громадянина України",
      "description": null,
      "icon": null,
      "is_repeatable": false,
      "fields": [
        {
          "id": "f1000000-0000-0000-0000-000000000001",
          "version_identifier": "f1000000-0000-0000-0000-0000000000aa",
          "version": 1,
          "type": "text",
          "label": "Серія та номер",
          "placeholder": null,
          "description": null,
          "allow_custom_value": false,
          "validation": null,
          "options": null,
          "default_value": null
        },
        {
          "id": "f1000000-0000-0000-0000-000000000002",
          "version_identifier": "f1000000-0000-0000-0000-0000000000bb",
          "version": 1,
          "type": "date",
          "label": "Дата видачі",
          "placeholder": null,
          "description": null,
          "allow_custom_value": false,
          "validation": null,
          "options": null,
          "default_value": null
        }
      ]
    }
  ]
}

Оновлення профілю: тіло запиту¶

Тіло для PUT та PATCH має однакову структуру — список блоків, кожен з яких посилається на block_definition_id і містить поля з field_definition_id та value:

{
  "blocks": [
    {
      "block_definition_id": "b1000000-0000-0000-0000-000000000001",
      "fields": [
        {
          "field_definition_id": "f1000000-0000-0000-0000-000000000001",
          "value": "123456789"
        },
        {
          "field_definition_id": "f1000000-0000-0000-0000-000000000002",
          "value": "2020-01-15"
        }
      ]
    }
  ]
}

Семантика залежить від методу:

PUT — REPLACE: передається повний набір блоків; блоки, відсутні в запиті, видаляються з профілю.
PATCH — MERGE: оновлюються лише передані блоки, решта залишаються без змін.

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

Спочатку отримайте визначення - перед оновленням профілю отримайте визначення профілю (/company/employee-profile-definition), щоб дізнатися актуальні block_definition_id та field_definition_id, типи полів і допустимі опції. Набір блоків/полів може відрізнятися між компаніями.
Значення відповідає типу поля - формат value визначається типом поля (type) із визначення (див. таблицю типів вище). Наприклад, для date очікується рядок "YYYY-MM-DD", для multiselect - масив рядків.
PUT vs PATCH - використовуйте PUT для повної заміни профілю (з ризиком видалення непереданих блоків) і PATCH для точкового оновлення окремих блоків.
Медіа файли - при читанні профілю кожне поле повертає прикріплені файли у масиві media_files. Файли завантажуються окремо через відповідний ендпоінт завантаження медіа.
Джерело даних (source) - кожен блок має джерело походження: manual (ручне введення), diia (імпорт з Дія) або ai_parsing (автоматичне розпізнавання). Прямі правки через API лишають manual.
Використання в задачі "Прийом" - профіль активно використовується в процесі найму через задачу "Прийом на роботу". Анкета, яку заповнює співробітник або HR-спеціаліст, зберігається в профіль і може оновлюватися через ендпоінти /submit-questionnaire та /submit-approve-questionnaire.

Приклад відповіді `GET .../profile`¶

{
  "employee": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Іван",
    "last_name": "Петренко",
    "middle_name": "Олександрович",
    "date_of_birth": "1990-05-15",
    "email": "[email protected]",
    "phone": "+380501234567",
    "status": "working",
    "sign_type": "personal"
  },
  "blocks": [
    {
      "id": "a1000000-0000-0000-0000-000000000001",
      "block_definition_id": "b1000000-0000-0000-0000-000000000001",
      "version_identifier": "b1000000-0000-0000-0000-0000000000aa",
      "name": "Паспорт громадянина України",
      "icon": null,
      "is_repeatable": false,
      "is_archived": false,
      "order": 1,
      "source": "manual",
      "fields": [
        {
          "field_definition_id": "f1000000-0000-0000-0000-000000000001",
          "version_identifier": "f1000000-0000-0000-0000-0000000000aa",
          "label": "Серія та номер",
          "type": "text",
          "placeholder": null,
          "options": null,
          "value": "123456789",
          "media_files": [],
          "is_archived": false
        },
        {
          "field_definition_id": "f1000000-0000-0000-0000-000000000002",
          "version_identifier": "f1000000-0000-0000-0000-0000000000bb",
          "label": "Дата видачі",
          "type": "date",
          "placeholder": null,
          "options": null,
          "value": "2020-01-15",
          "media_files": [],
          "is_archived": false
        }
      ]
    }
  ]
}