Як частково оновити дані співробітника через 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

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

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

Employee

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

• BFF бере companyId з Bearer token, а не з параметрів запиту.

• BFF бере 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, сервер створює або повторно синхронізує пов’язаного Keycloak-користувача і відкриває доступ до приватного кабінету.

• Якщо active змінюється з true на false, сервер видаляє пов’язаного Keycloak-користувача і відкликає доступ до приватного кабінету.

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

Edge cases

Edge cases

Помилки

Error responses

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

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

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

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

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

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

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

Typical integration mistakes

FAQ

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

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

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

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

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

API поверне 409 Conflict.

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

Сервер видаляє пов’язаного Keycloak-користувача і відкликає доступ до приватного кабінету.

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

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