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