Як додати співробітника через 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.
У поточній реалізації Idempotency-Key не використовується.
Запит
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 через 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.
