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

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

Endpoint

Призначення

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

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

Передумови

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

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

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

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

У поточній реалізації 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,
  "manager": false,
  "department": "Управління",
  "departments": ["КЛ"],
  "jobTitle": "Менеджер",
  "jobTitles": ["Координатор"],
  "phone": "+380000000000",
  "notes": "Новий співробітник public API"
}
JSON

Створити співробітника тільки з масивами 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,
  "manager": true,
  "departments": ["Управління", "КЛ"],
  "jobTitles": ["Менеджер", "Координатор"],
  "phone": "+380000000000",
  "notes": "Новий співробітник public API"
}
JSON

Відповідь

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

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

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

Employee

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

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

API визначає 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 створює або синхронізує пов'язаний користувацький акаунт на сервері авторизації і відкриває доступ до приватного кабінету.

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

manager = true створює або синхронізує доступ з ролями співробітника і керівника підрозділу. Якщо одночасно передати active = false, manager-доступ має пріоритет і співробітник буде створений як активний користувач кабінету.

manager = false або відсутнє поле manager не призначає роль керівника підрозділу.

manager повертається в Employee response; після створення цю роль можна змінити через PATCH /v1/employees/{employeeId}.

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

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

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

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

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

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

Edge cases

Помилки

Error responses

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

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

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

Створення співробітника з роллю керівника підрозділу: manager = true.

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

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

Typical integration mistakes

FAQ

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

email, name, surname, gender і active.

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

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

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

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

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

Сервер створює або синхронізує доступ з ролями співробітника і керівника підрозділу. Якщо одночасно передати active = false, співробітник усе одно буде створений як активний користувач кабінету.

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

API поверне 409 Conflict.

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

Ні. API визначає hrEmail з Bearer token.