Как добавить сотрудника через API?

POST /v1/employees создаёт сотрудника. Обязательные поля body: email, name, surname, gender и active. Для доступа нужен scope employees.write.

Endpoint

Назначение

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

Значение active управляет не только бизнес-флагом, но и созданием или отсутствием связанного пользователя в Keycloak.

Предусловия

• Клиент должен передать валидный Bearer token.

• Token должен содержать company context.

• Token должен содержать scope employees.write.

• idCompany не передаётся в body или query string.

• hrEmail не передаётся внешним клиентом; BFF берёт его из Bearer token.

• В текущей реализации 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,
  "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,
  "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
}

Поля ответа

Employee

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

• BFF определяет companyId только из Bearer token.

• BFF берёт 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 создаёт или синхронизирует связанный пользовательский аккаунт в Keycloak и открывает доступ к личному кабинету.

• active = false создаёт сотрудника без доступа к личному кабинету, то есть без пользователя в Keycloak.

• fullName в ответе формируется сервером из name + surname.

• Если передан только departments или jobTitles, первый элемент массива становится primary-значением в department или jobTitle.

• Если передано и одиночное поле, и массив, одиночное поле имеет приоритет как primary, а массив дополняется уникальными значениями.

• Если department, jobTitle, phone или notes не переданы, в соответствующих одиночных полях сохраняется null.

• Если departments или jobTitles не переданы, соответствующие коллекции остаются пустыми.

• В ответе departments и jobTitles возвращаются в стабильно отсортированном виде.

Edge cases

Edge cases

Ошибки

Error responses

Использование

• Создать активного сотрудника с доступом к личному кабинету: active = true.

• Создать сотрудника без доступа к личному кабинету: active = false.

• Передать несколько департаментов или должностей с определением primary-значения.

• Синхронизировать сотрудников из внешней HR-системы.

Типичные ошибки

Typical integration mistakes

FAQ

Какие поля обязательны для создания сотрудника?

email, name, surname, gender и active.

Что делает active = true?

Сервер создаёт или синхронизирует связанный пользовательский аккаунт в Keycloak и открывает доступ к личному кабинету.

Что делает active = false?

Сотрудник создаётся без доступа к личному кабинету, то есть без пользователя в Keycloak.

Что будет, если email уже существует?

API вернёт 409 Conflict.

Нужно ли передавать hrEmail?

Нет. BFF берёт hrEmail из Bearer token.