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

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

Endpoint

Назначение

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

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

Предусловия

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

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

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

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

Запрос

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

Поля ответа

Employee

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

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

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

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

manager = true создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения. Если одновременно передать active = false, manager-доступ имеет приоритет и сотрудник будет создан как активный пользователь кабинета.

manager = false или отсутствие поля manager не назначает роль руководителя подразделения.

manager возвращается в Employee response; после создания эту роль можно изменить через PATCH /v1/employees/{employeeId}.

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

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

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

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

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

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

Edge cases

Ошибки

Error responses

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

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

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

Создать сотрудника с ролью руководителя подразделения: manager = true.

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

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

Typical integration mistakes

FAQ

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

email, name, surname, gender и active.

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

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

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

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

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

Сервер создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения. Если одновременно передать active = false, сотрудник всё равно будет создан как активный пользователь кабинета.

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

API вернёт 409 Conflict.

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

Нет. API определяет hrEmail из Bearer token.