Как добавить сотрудника через API?
POST /v1/employees создаёт сотрудника. Обязательные поля body: email, name, surname, gender и active. Для доступа нужен
scope employees.write.
Endpoint
| Параметр | Значение | | -------------- | ---------------------- | | Method | POST | | Path | /api/v1/employees | |
Base URL | https://smartway.pro | | Auth | Bearer token | | Required scope | employees.write |
Назначение
Endpoint используется для создания нового сотрудника в рамках компании из Bearer token.
Значение active управляет не только бизнес-флагом, но и созданием или отсутствием связанного пользователя на сервере
авторизации.
Предусловия
Клиент должен передать валидный Bearer token.
Token должен содержать company context.
Token должен содержать scope employees.write.
idCompany не передаётся в body или query string.
Запрос
Body parameters
| Поле | Тип | Обязательное | Описание | | ------------- | -------- | ---------------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | email | string | да | Email сотрудника. | | name | string | да | Имя сотрудника. Это источник данных для
формирования fullName при создании. | | surname | string | да | Фамилия сотрудника. Это источник данных для
формирования fullName при создании. | | gender | string | да | Допустимы только значения Male или Female. | | active |
boolean | да | Допустимы только JSON-boolean значения true или false. true создаёт или синхронизирует доступ к личному
кабинету через сервер авторизации; false создаёт сотрудника без такого доступа. | | manager | boolean | нет | Признак
роли руководителя подразделения. Допустимы только JSON-boolean значения true или false; true создаёт или синхронизирует
доступ с ролями сотрудника и руководителя подразделения, даже если active=false. | | department | string | нет |
Основной департамент. Если не передать, сохраняется null. | | departments | string[] | нет | Набор
департаментов. Если не передать, коллекция остаётся пустой. | | jobTitle | string | нет | Основная
должность. Если не передать, сохраняется null. | | jobTitles | string[] | нет | Набор должностей. Если не
передать, коллекция остаётся пустой. | | phone | string | нет | Телефон. Если не передать, сохраняется null. | |
notes | string | нет | Примечания. Если не передать, сохраняется null. |
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
| Поле | Тип | Описание | | ------------- | -------- |
--------------------------------------------------------------------------------------- | | employeeId | int64 | ID
сотрудника. | | candidateId | int64 | ID связанного кандидата. | | email | string | Email сотрудника. | | fullName
| string | Полное имя, которое сервер формирует из name + surname. | | name | string | Имя. | | surname | string |
Фамилия. | | gender | string | Пол. | | department | string | Основной департамент. | | departments | string[] |
Набор департаментов. | | jobTitle | string | Основная должность. | | jobTitles | string[] | Набор должностей. | |
phone | string | Телефон. | | active | boolean | Признак активности. | | manager | boolean | Признак роли руководителя
подразделения. true означает, что сотрудник имеет эту роль. |
Бизнес-логика
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
| Сценарий | Поведение API | | ----------------------------------------------- |
---------------------------------------------------------------------------------- | | Отсутствует required-поле | API
возвращает 400 Bad Request. | | gender имеет значение не Male и не Female | API возвращает 400 Bad Request с
пояснением. | | active передан строкой или числом | API возвращает 400 Bad Request, потому что active должен
быть JSON-boolean. | | manager передан строкой или числом | API возвращает 400 Bad Request, потому что manager должен
быть JSON-boolean. | | active=false и manager=true | Manager-доступ имеет приоритет; сотрудник создаётся активным. | |
email уже существует | API возвращает 409 Conflict. | | Передан только departments | Первый элемент массива становится
department. | | Переданы department и departments | department остаётся primary, а departments дополняется уникальными
значениями. | | Не передан department или jobTitle | В соответствующем одиночном поле сохраняется null. | | Не передан
departments или jobTitles | Соответствующая коллекция остаётся пустой. |
Ошибки
Error responses
| HTTP status | Когда возникает | | --------------------------- |
--------------------------------------------------------------------------------------------- | | 400 Bad Request |
Отсутствует хотя бы один required-параметр email, name, surname, gender или active. | | 400 Bad Request | gender не
равен Male или Female. | | 400 Bad Request | active не является JSON-boolean значением true или false. | | 400 Bad
Request | manager не является JSON-boolean значением true или false. | | 401 Unauthorized | Bearer token отсутствует или
невалиден. | | 403 Forbidden | Недостаточно прав или token без company context. | | 409 Conflict | Employee с таким
email уже существует. | | 500 Internal Server Error | Неожиданная ошибка API. | | 503 Service Unavailable | Сбой
внутренней серверной интеграции. |
Использование
Создать активного сотрудника с доступом к личному кабинету: active = true.
Создать сотрудника без доступа к личному кабинету: active = false.
Создать сотрудника с ролью руководителя подразделения: manager = true.
Синхронизировать сотрудников из внешней HR-системы.
Типичные ошибки
Typical integration mistakes
| Типичная ошибка | Как правильно | | ----------------------------------------------------------- |
--------------------------------------------------------------- | | Передавать active как строку "true" или "false" |
Передавайте true или false как JSON-boolean. | | Передавать manager как строку "true" или "false" | Передавайте true
или false как JSON-boolean. | | Передавать gender в значении, отличном от Male/Female | Используйте только Male или
Female. | | Передавать idCompany или hrEmail | Не передавайте эти значения; API определяет их из Bearer token. | |
Ожидать идемпотентность через Idempotency-Key | В текущей реализации Idempotency-Key не используется. | |
Передавать fullName вместо name и surname | Передавайте name и surname; fullName формирует сервер. |
FAQ
Какие поля обязательны для создания сотрудника?
email, name, surname, gender и active.
Что делает active = true?
Сервер создаёт или синхронизирует связанный пользовательский аккаунт на сервере авторизации и открывает доступ к личному
кабинету.
Что делает active = false?
Сотрудник создаётся без доступа к личному кабинету, то есть без пользовательского аккаунта на сервере авторизации.
Что делает manager = true?
Сервер создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения. Если одновременно передать
active = false, сотрудник всё равно будет создан как активный пользователь кабинета.
Что будет, если email уже существует?
API вернёт 409 Conflict.
Нужно ли передавать hrEmail?
Нет. API определяет hrEmail из Bearer token.
