Як додати співробітника через API?

POST /v1/employees створює співробітника. Обов’язкові поля body: email, name, surname, gender і active. Для доступу потрібен scope employees.write.

Endpoint

Призначення

Endpoint використовується для створення нового співробітника в межах компанії з Bearer token.

Значення active керує не тільки бізнес-прапорцем, а й створенням або відсутністю пов’язаного користувача в Keycloak.

Передумови

• Клієнт має передати валідний Bearer token.

• Token має містити company context.

• Token має містити scope employees.write.

• idCompany не передається у body або query string.

• hrEmail не передається зовнішнім клієнтом; BFF бере його з Bearer token.

• У поточній реалізації Idempotency-Key не використовується.

Запит

Body parameters

curl приклад

Створити співробітника з primary-полями і масивами

curl -X POST 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "email": "employee@example.com",
  "name": "Іван",
  "surname": "Петренко",
  "gender": "Female",
  "active": false,
  "department": "Управління",
  "departments": ["КЛ"],
  "jobTitle": "Менеджер",
  "jobTitles": ["Координатор"],
  "phone": "+380000000000",
  "notes": "Новий співробітник public API"
}

Створити співробітника тільки з масивами departments/jobTitles

curl -X POST 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "email": "employee@example.com",
  "name": "Іван",
  "surname": "Петренко",
  "gender": "Male",
  "active": true,
  "departments": ["Управління", "КЛ"],
  "jobTitles": ["Менеджер", "Координатор"],
  "phone": "+380000000000",
  "notes": "Новий співробітник public API"
}

Відповідь

Успішна відповідь: 201 Created. Повертає створений Employee.

{
  "employeeId": 4432,
  "candidateId": 10748,
  "email": "employee@example.com",
  "fullName": "Іван Петренко",
  "name": "Іван",
  "surname": "Петренко",
  "gender": "Female",
  "department": "Управління",
  "departments": [
    "КЛ",
    "Управління"
  ],
  "jobTitle": "Менеджер",
  "jobTitles": [
    "Координатор",
    "Менеджер"
  ],
  "phone": "+380000000000",
  "active": false
}

Поля відповіді

Employee

Бізнес-логіка

• BFF визначає companyId тільки з Bearer token.

• BFF бере hrEmail з Bearer token. hrEmail дорівнює email користувача з роллю HRADMIN, який створив або ротував активний API key компанії.

• Якщо активний API key буде ротований іншим HRADMIN, наступні create-операції автоматично почнуть використовувати його hrEmail.

• Повторний однаковий POST не створює дубль, якщо вже існує employee з таким самим email; API повертає 409 Conflict.

• gender приймає тільки Male або Female.

• active приймає тільки JSON-boolean true або false.

• active = true створює або синхронізує пов’язаний користувацький акаунт у Keycloak і відкриває доступ до приватного кабінету.

• active = false створює співробітника без доступу до приватного кабінету, тобто без користувача в Keycloak.

• fullName у відповіді формується сервером з name + surname.

• Якщо передано тільки departments або jobTitles, перший елемент масиву стає primary-значенням у department або jobTitle.

• Якщо передано і одиничне поле, і масив, одиничне поле має пріоритет як primary, а масив доповнюється унікальними значеннями.

• Якщо department, jobTitle, phone або notes не передані, у відповідних одиничних полях зберігається null.

• Якщо departments або jobTitles не передані, відповідні колекції залишаються порожніми.

• У відповіді departments і jobTitles повертаються у стабільно відсортованому вигляді.

Edge cases

Edge cases

Помилки

Error responses

Використання

• Створення активного співробітника з доступом до приватного кабінету: active = true.

• Створення співробітника без доступу до приватного кабінету: active = false.

• Передача кількох департаментів або посад із визначенням primary-значення.

• Синхронізація співробітників із зовнішньої HR-системи.

Типові помилки

Typical integration mistakes

FAQ

Які поля обов’язкові для створення співробітника?

email, name, surname, gender і active.

Що робить active = true?

Сервер створює або синхронізує пов’язаний користувацький акаунт у Keycloak і відкриває доступ до приватного кабінету.

Що робить active = false?

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

Що буде, якщо email уже існує?

API поверне 409 Conflict.

Чи потрібно передавати hrEmail?

Ні. BFF бере hrEmail з Bearer token.