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

PATCH /v1/employees/{employeeId} оновлює тільки передані поля. Body має містити хоча б одне поле. Для доступу потрібен scope employees.write.

Endpoint

Призначення

Endpoint використовується для часткового оновлення співробітника в межах поточного tenant-а.

Поле fullName у PATCH-контракт не входить; для зміни ПІБ використовуються name і surname.

Передумови

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

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

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

employeeId має належати співробітнику в межах поточного tenant-а.

PATCH-body має містити хоча б одне поле.

idCompany і hrEmail не передаються зовнішнім клієнтом.

Запит

Path parameters

Body parameters

curl приклад

Оновити ПІБ, primary-поля, масиви, active і manager

curl -X PATCH 'https://smartway.pro/api/v1/employees/4432' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "name": "Оновлене Ім'я",
  "surname": "Прізвище",
  "department": "Управління",
  "departments": ["КЛ", "Логістика"],
  "jobTitle": "Старший менеджер",
  "jobTitles": ["Координатор", "Аналітик"],
  "active": true,
  "manager": true
}
JSON

Відповідь

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

{
  "employeeId": 4432,
  "candidateId": 10748,
  "email": "employee@example.com",
  "fullName": "Оновлене Ім'я Прізвище",
  "name": "Оновлене Ім'я",
  "surname": "Прізвище",
  "gender": "not_specified",
  "department": "Управління",
  "departments": [
    "КЛ",
    "Логістика",
    "Управління"
  ],
  "jobTitle": "Старший менеджер",
  "jobTitles": [
    "Аналітик",
    "Координатор",
    "Старший менеджер"
  ],
  "phone": "+380000000000",
  "active": true,
  "manager": true
}

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

Employee

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

API визначає companyId з Bearer token, а не з параметрів запиту.

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

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

PATCH змінює тільки ті поля, які передані в body.

fullName не передається в PATCH-body. Сервер формує fullName з актуальних name + surname.

name і surname можна передавати разом або окремо. Якщо поле передано, воно має містити непорожній текст.

Текстові поля підтримують UTF-8.

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

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

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

Якщо новий email уже належить іншому employee, API повертає 409 Conflict.

Якщо active змінюється з false на true, сервер створює або повторно синхронізує пов'язаний користувацький акаунт на сервері авторизації і відкриває доступ до приватного кабінету.

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

Якщо PATCH одночасно змінює active і email, сервер синхронізує саме акаунт, який уже був пов'язаний із цим employee, а не довільного користувача за новим email.

manager = true додає роль керівника підрозділу і гарантує активний доступ до кабінету; якщо одночасно передати active = false, manager-доступ має пріоритет і employee лишається активним користувачем кабінету.

manager = false знімає тільки роль керівника підрозділу, якщо active не передано як false; доступ до кабінету лишається активним.

Якщо одночасно передати active = false і manager = false, сервер відкликає доступ до кабінету і видаляє пов'язаний користувацький акаунт на сервері авторизації.

Edge cases

Помилки

Error responses

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

Оновити контактні дані співробітника.

Змінити департамент або посаду.

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

Відкликати доступ до приватного кабінету через active = false.

Надати або зняти роль керівника підрозділу через manager.

Оновити email з перевіркою конфлікту.

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

Typical integration mistakes

FAQ

Чи можна передати тільки одне поле в PATCH?

Так. Body має містити хоча б одне поле.

Чи можна змінити fullName напряму?

Ні. fullName не входить у PATCH-контракт. Використовуйте name і surname.

Що буде, якщо новий email уже зайнятий?

API поверне 409 Conflict.

Що відбувається при active = false?

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

Що відбувається, якщо одночасно змінити active і email?

Сервер синхронізує акаунт, який уже пов'язаний із цим employee.

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

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

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

Сервер знімає тільки роль керівника підрозділу, якщо active не передано як false.