Как частично обновить данные сотрудника через 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.