Головна API документація

API документація

Повна документація з використання API
Serhii
Від Serhii
• 7 статті

Як отримати access token

Access token потрібен для авторизації наступних API-запитів у LMS Smart Way. Після отримання токена ви передаєте його в заголовку Authorization з типом Bearer і використовуєте для звернення до доступних endpoint’ів відповідно до scope, які вкладені в токен. Ця стаття показує, як отримати токен, що саме повертає API у відповіді та на що звернути увагу перед інтеграцією. Якщо ви лише починаєте налаштування інтеграції, спочатку переконайтеся, що у вас є дійсний company_api_key. Передумови - У вас має бути дійсний company_api_key вашої компанії. - Запит на отримання токена потрібно виконувати на endpoint /api/v1/auth/token. - API key передається в заголовку X-API-Key. - Отриманий access token використовується лише для наступних викликів API і не замінює собою API key. Запит curl -X POST 'https://smartway.pro/api/v1/auth/token' \ -H 'X-API-Key: <company_api_key>' Успішна відповідь { "access_token": "<short_lived_jwt>", "token_type": "Bearer", "expires_in": 900, "scope": "academy.read academy.write employees.read employees.write tests.read tests.write files.read" } Зафіксовані правила відповіді - access_token — короткоживучий JWT для наступних викликів public API - token_type — завжди Bearer - expires_in — TTL у секундах - scope — space-delimited список scope-ів, вкладених у токен Що всередині access token - JWT містить claim companyId для tenant isolation. - JWT також містить claim hrEmail — email HRADMIN, який створив або ротував поточний активний API key компанії. - Якщо API key згенерує або ротуватиме інший HRADMIN, то нові токени вже міститимуть інший hrEmail, і саме він буде використовуватися для наступних employee write-операцій. Як використовувати access token у наступних запитах Після успішного отримання токена передавайте його в заголовку Authorization у форматі Bearer <access_token>. Саме цей токен використовується для авторизації подальших запитів до public API. Перед виконанням запиту перевіряйте, що токен ще не втратив чинність. Якщо строк дії завершився, отримайте новий access token повторним викликом endpoint’а авторизації.

Востаннє оновлено Mar 28, 2026

Правила поточної реалізації API LMS

Public API використовує схему: company API key -> short-lived Bearer token Правила поточної реалізації: - API key належить компанії, а не окремому користувачу. - Для v1 дозволено один активний API key на компанію. - Керує ключем тільки користувач із роллю HRADMIN у cab > Settings > Company. - Повний секрет показується лише один раз — одразу після генерації або ротації. - Після ротації попередній ключ стає невалідним одразу. - Інтегратор отримує access token через POST /v1/auth/token і далі використовує Authorization: Bearer <token>. - Refresh token для інтегратора у v1 не використовується: після завершення TTL access token інтегратор повторно викликає POST /v1/auth/token. Base URL і загальні правила виклику 1. Base URL Поточний base URL: - https://smartway.pro/api 2. Загальні правила - Формат бізнес-відповідей: application/json - Формат помилок: application/problem+json - Версіонування: major-версія в URI (/v1/...) - Для кореляції запитів рекомендовано передавати traceparent

Востаннє оновлено Mar 28, 2026

Як отримати список співробітників через API?

GET /v1/employees повертає сторінку співробітників. Якщо query-параметри не передати, API застосовує page = 0 і size = 50. Endpoint | Параметр | Значення | | -------------- | ---------------------------------------------------- | | Method | GET | | Path | /v1/employees | | Base URL | https://smartway.pro/api | | Auth | Bearer token | | Required scope | employees.read | Призначення Endpoint використовується для отримання сторінкового списку співробітників у межах компанії з Bearer token. Endpoint підтримує пагінацію, пошук за ПІБ і фільтри за департаментом та посадою. Передумови - Клієнт має передати валідний Bearer token. - Token має містити company context. - Token має містити scope employees.read. - idCompany не передається зовнішнім клієнтом. BFF бере companyId тільки з Bearer token. - Текстові query-параметри підтримують UTF-8 і мають передаватися як стандартний URL-encoded query string. Запит Query parameters | Параметр | Тип | Обов’язковий | Опис | | ------------ | ------- | ---------------- | ----------------------------------------------------------------------- | | page | int32 | ні | Номер сторінки. Значення за замовчуванням: 0. | | size | int32 | ні | Розмір сторінки. Значення за замовчуванням: 50. | | q | string | ні | Пошук за ПІБ з частковим співпадінням. Пошук за email не підтримується. | | department | string | ні | Фільтр за департаментом. | | jobTitle | string | ні | Фільтр за посадою. | curl приклад Виклик без параметрів curl -X GET 'https://smartway.pro/api/v1/employees' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Виклик з кількома параметрами curl -G 'https://smartway.pro/api/v1/employees' \ --data-urlencode 'page=0' \ --data-urlencode 'size=20' \ --data-urlencode 'q=Іван' \ --data-urlencode 'department=Управління' \ --data-urlencode 'jobTitle=Менеджер' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Відповідь Успішна відповідь: 200 OK. Повертає EmployeeListResponse. { "data": [ { "employeeId": 4329, "candidateId": 10602, "email": "employee@example.com", "fullName": "Ім'я Прізвище", "name": "Ім'я", "surname": "Прізвище", "gender": "Female", "department": "КЛ", "departments": [ "КЛ" ], "jobTitle": "Менеджер", "jobTitles": [ "Менеджер" ], "phone": "+380000000000", "active": true } ], "meta": { "page": 0, "size": 50, "totalElements": 385, "totalPages": 8, "hasNext": true } } Поля відповіді EmployeeListResponse | Поле | Тип | Опис | | -------- | ---------- | --------------------- | | data | Employee[] | Масив співробітників. | | meta | object | Метадані пагінації. | meta | Поле | Тип | Опис | | ------------- | ------- | ------------------------------------ | | page | integer | Поточна сторінка. Нумерація 0-based. | | size | integer | Розмір сторінки. | | totalElements | integer | Загальна кількість записів. | | totalPages | integer | Загальна кількість сторінок. | | hasNext | boolean | Ознака наявності наступної сторінки. | 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 | Ознака активності. | Бізнес-логіка - Параметр page є 0-based: page=0 — перша сторінка, page=1 — друга сторінка. - Якщо page і size не передані, API застосовує page = 0 і size = 50. - q шукає лише за ПІБ з частковим співпадінням. Пошук за email не підтримується. - department і jobTitle звужують вибірку за відповідними значеннями. - Параметри можна комбінувати між собою; сукупність параметрів застосовується через логіку AND. - Доступ до даних обмежений tenant-контекстом із Bearer token. Edge cases Edge cases | Сценарій | Поведінка API | | ---------------------------------------- | --------------------------------------------------------------------------- | | Endpoint викликано без query-параметрів | API повертає першу сторінку з page = 0 і size = 50. | | page=1 | API повертає другу сторінку, оскільки нумерація сторінок 0-based. | | q містить email | Пошук за email не підтримується; q призначений для пошуку за ПІБ. | | department або jobTitle містить кирилицю | Значення є валідним, якщо передане як стандартний URL-encoded query string. | | Передано кілька фільтрів | Фільтри комбінуються через AND. | Помилки Error responses | HTTP status | Коли виникає | | ------------------------- | ----------------------------------------------- | | 400 Bad Request | Некоректні query-параметри. | | 401 Unauthorized | Bearer token відсутній або невалідний. | | 403 Forbidden | Недостатньо прав або token без company context. | | 500 Internal Server Error | Неочікувана помилка BFF. | | 503 Service Unavailable | Збій внутрішньої інтеграції BFF -> back2. | Використання - Перший інтеграційний тест — виклик без параметрів. - Пагіноване завантаження співробітників у зовнішню систему. - Фільтрація списку за департаментом або посадою. - Пошук співробітника за частиною ПІБ. Типові помилки Typical integration mistakes | Типова помилка | Як правильно | | ------------------------------------------ | ------------------------------------------------------------------------------------ | | Передавати idCompany у query string | Не передавайте idCompany. BFF бере companyId з Bearer token. | | Очікувати, що q шукає за email | Використовуйте q лише для пошуку за ПІБ. | | Вважати page 1-based | Перша сторінка — page=0. | | Передавати UTF-8 значення без URL encoding | Для кирилиці використовуйте URL-encoded query string або curl -G з --data-urlencode. | FAQ Чи потрібно передавати idCompany? Ні. idCompany не передається зовнішнім клієнтом; BFF бере companyId з Bearer token. Чи підтримує q пошук за email? Ні. q підтримує пошук за ПІБ з частковим співпадінням. Які значення page і size використовуються за замовчуванням? page = 0 і size = 50. Чи можна комбінувати q, department і jobTitle? Так. Параметри комбінуються через логіку AND.

Востаннє оновлено Apr 25, 2026

Як отримати співробітника за ID через API?

GET /v1/employees/{employeeId} повертає одного співробітника за ID у межах tenant-контексту з Bearer token. Endpoint | Параметр | Значення | | -------------- | ---------------------------------------------------- | | Method | GET | | Path | /v1/employees/{employeeId} | | Base URL | https://smartway.pro/api | | Auth | Bearer token | | Required scope | employees.read | Призначення Endpoint використовується для отримання детальної інформації про одного співробітника. Пошук виконується тільки в межах tenant-контексту, визначеного Bearer token. Передумови - Клієнт має передати валідний Bearer token. - Token має містити company context. - Token має містити scope employees.read. - idCompany не передається окремо. - employeeId має належати співробітнику в межах поточного tenant-а. Запит Path parameters | Параметр | Тип | Обов’язковий | Опис | | ------------ | ------- | ---------------- | ----------------- | | employeeId | int64 | так | ID співробітника. | curl приклад Отримати співробітника за ID curl -X GET 'https://smartway.pro/api/v1/employees/3114' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Відповідь Успішна відповідь: 200 OK. Повертає Employee. { "employeeId": 4329, "candidateId": 10602, "email": "employee@example.com", "fullName": "Ім'я Прізвище", "name": "Ім'я", "surname": "Прізвище", "gender": "Female", "department": "КЛ", "departments": [ "КЛ" ], "jobTitle": "Менеджер", "jobTitles": [ "Менеджер" ], "phone": "+380000000000", "active": true } Поля відповіді 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 | Ознака активності. | Бізнес-логіка - BFF бере companyId з Bearer token, а не з параметрів запиту. - Endpoint повертає співробітника тільки з поточного tenant-контексту. - Якщо співробітника не знайдено в межах поточного tenant-а, API повертає 404 Not Found. - Для доступу потрібен scope employees.read. Edge cases Edge cases | Сценарій | Поведінка API | | ---------------------------------- | ---------------------------------------------------------- | | employeeId існує в іншому tenant-і | API повертає 404 Not Found для поточного tenant-контексту. | | Bearer token без company context | API повертає 403 Forbidden. | | employeeId не знайдено | API повертає 404 Not Found. | | Передано idCompany окремо | Endpoint не використовує idCompany з клієнтського запиту. | Помилки Error responses | HTTP status | Коли виникає | | ------------------------- | ----------------------------------------------------- | | 400 Bad Request | Некоректний запит. | | 401 Unauthorized | Bearer token відсутній або невалідний. | | 403 Forbidden | Недостатньо прав або token без company context. | | 404 Not Found | Співробітника не знайдено в межах поточного tenant-а. | | 500 Internal Server Error | Неочікувана помилка BFF. | | 503 Service Unavailable | Збій внутрішньої інтеграції BFF -> back2. | Використання - Отримати картку співробітника після вибору запису зі списку. - Перевірити актуальні поля співробітника перед PATCH. - Завантажити один Employee для синхронізації у зовнішній системі. Типові помилки Typical integration mistakes | Типова помилка | Як правильно | | ------------------------------------------------ | ------------------------------------------------------------- | | Вважати employeeId глобальним для всіх tenant-ів | employeeId шукається в межах tenant-контексту з Bearer token. | | Передавати idCompany окремо | Не передавайте idCompany; companyId береться з token. | | Використовувати token без employees.read | Додайте scope employees.read. | FAQ Чи можна отримати співробітника з іншої компанії? Ні. Пошук виконується в межах tenant-контексту з Bearer token. Що повертає API, якщо employeeId не знайдено? API повертає 404 Not Found. Чи потрібно передавати idCompany? Ні. idCompany передається автоматично.

Востаннє оновлено Apr 25, 2026

Як додати співробітника через API?

POST /v1/employees створює співробітника. Обов’язкові поля body: email, name, surname, gender і active. Для доступу потрібен scope employees.write. Endpoint | Параметр | Значення | | -------------- | ---------------------------------------------------- | | Method | POST | | Path | /v1/employees | | Base URL | https://smartway.pro/api | | Auth | Bearer token | | Required scope | employees.write | Призначення 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 | Поле | Тип | Обов’язкове | Опис | | ----------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | string | так | Email співробітника. | | name | string | так | Ім’я співробітника. Це source of truth для формування fullName під час створення. | | surname | string | так | Прізвище співробітника. Це source of truth для формування fullName під час створення. | | gender | string | так | Допустимі лише значення Male або Female. | | active | boolean | так | Допустимі лише JSON-boolean значення true або false. true створює або синхронізує доступ до приватного кабінету через Keycloak; 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, "department": "Управління", "departments": ["КЛ"], "jobTitle": "Менеджер", "jobTitles": ["Координатор"], "phone": "+380000000000", "notes": "Новий співробітник public API" } Створити співробітника тільки з масивами 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" } Відповідь Успішна відповідь: 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 | Поле | Тип | Опис | | ----------- | -------- | ----------------------------------------------- | | 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 | Ознака активності. | Бізнес-логіка - 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 | Сценарій | Поведінка API | | --------------------------------------- | ----------------------------------------------------------------------------------- | | Відсутнє required поле | API повертає 400 Bad Request. | | gender має значення не Male і не Female | API повертає 400 Bad Request з поясненням. | | active передано рядком або числом | API повертає 400 Bad Request, бо active має бути JSON-boolean. | | email уже існує | API повертає 409 Conflict. | | Передано тільки departments | Перший елемент масиву стає department. | | Передано department і departments | department лишається primary, а departments доповнюється унікальними значеннями. | | Не передано department або jobTitle | У відповідному одиничному полі зберігається null. | | Не передано departments або jobTitles | Відповідна колекція лишається порожньою. | | Клієнт передає fullName | У create request поле fullName не описане. Сервер формує fullName з name + surname. | Помилки 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. | | 401 Unauthorized | Bearer token відсутній або невалідний. | | 403 Forbidden | Недостатньо прав або token без company context. | | 409 Conflict | Employee з таким email уже існує. | | 500 Internal Server Error | Неочікувана помилка BFF. | | 503 Service Unavailable | Збій внутрішньої інтеграції BFF -> back2. | Використання - Створення активного співробітника з доступом до приватного кабінету: active = true. - Створення співробітника без доступу до приватного кабінету: active = false. - Передача кількох департаментів або посад із визначенням primary-значення. - Синхронізація співробітників із зовнішньої HR-системи. Типові помилки Typical integration mistakes | Типова помилка | Як правильно | | -------------------------------------------------------- | ---------------------------------------------------------- | | Передавати active як рядок "true" або "false" | Передавайте true або false як JSON-boolean. | | Передавати gender у значенні, відмінному від Male/Female | Використовуйте тільки Male або Female. | | Передавати idCompany або hrEmail | Не передавайте ці значення; BFF бере їх із Bearer token. | | Очікувати idempotency через Idempotency-Key | У поточній реалізації Idempotency-Key не використовується. | | Передавати fullName замість name і surname | Передавайте name і surname; fullName формує сервер. | FAQ Які поля обов’язкові для створення співробітника? email, name, surname, gender і active. Що робить active = true? Сервер створює або синхронізує пов’язаний користувацький акаунт у Keycloak і відкриває доступ до приватного кабінету. Що робить active = false? Співробітник створюється без доступу до приватного кабінету, тобто без користувача в Keycloak. Що буде, якщо email уже існує? API поверне 409 Conflict. Чи потрібно передавати hrEmail? Ні. BFF бере hrEmail з Bearer token.

Востаннє оновлено Apr 25, 2026

Як частково оновити дані співробітника через API?

PATCH /v1/employees/{employeeId} оновлює тільки передані поля. Body має містити хоча б одне поле. Для доступу потрібен scope employees.write. Endpoint | Параметр | Значення | | -------------- | ---------------------------------------------------- | | Method | PATCH | | Path | /v1/employees/{employeeId} | | Base URL | https://smartway.pro/api | | Auth | Bearer token | | Required scope | employees.write | Призначення Endpoint використовується для часткового оновлення співробітника в межах поточного tenant-а. Поле fullName у PATCH-контракт не входить; для зміни ПІБ використовуються name і surname. Передумови - Клієнт має передати валідний Bearer token. - Token має містити company context. - Token має містити scope employees.write. - employeeId має належати співробітнику в межах поточного tenant-а. - PATCH-body має містити хоча б одне поле. - idCompany і hrEmail не передаються зовнішнім клієнтом. Запит Path parameters | Параметр | Тип | Обов’язковий | Опис | | ------------ | ------- | ---------------- | ----------------- | | employeeId | int64 | так | ID співробітника. | Body parameters | Поле | Тип | Обов’язкове | Опис | | ----------- | -------- | --------------- | -------------------------------------------------------------------------------------- | | email | string | ні | Оновити email. | | name | string | ні | Оновити ім’я співробітника. Якщо поле передано, воно має містити непорожній текст. | | surname | string | ні | Оновити прізвище співробітника. Якщо поле передано, воно має містити непорожній текст. | | gender | string | ні | Оновити стать. | | department | string | ні | Оновити primary-департамент. | | departments | string[] | ні | Замінити повний набір департаментів. | | jobTitle | string | ні | Оновити primary-посаду. | | jobTitles | string[] | ні | Замінити повний набір посад. | | phone | string | ні | Оновити телефон. | | active | boolean | ні | Оновити ознаку активності. | curl приклад Оновити ПІБ, primary-поля, масиви й active 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": false } 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": 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 | Ознака активності. | Бізнес-логіка - BFF бере companyId з Bearer token, а не з параметрів запиту. - BFF бере 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, сервер створює або повторно синхронізує пов’язаного Keycloak-користувача і відкриває доступ до приватного кабінету. - Якщо active змінюється з true на false, сервер видаляє пов’язаного Keycloak-користувача і відкликає доступ до приватного кабінету. - Якщо PATCH одночасно змінює active і email, сервер синхронізує саме акаунт, який уже був пов’язаний із цим employee, а не довільного користувача за новим email. Edge cases Edge cases | Сценарій | Поведінка API | | ----------------------------------------- | ------------------------------------------------------------------------------ | | PATCH-body порожній | API повертає 400 Bad Request. | | name або surname передані порожніми | API повертає 400 Bad Request. | | fullName передано в PATCH-body | Поле не входить у PATCH-контракт; використовуйте name і surname. | | Новий email уже належить іншому employee | API повертає 409 Conflict. | | Передано тільки departments або jobTitles | Перший елемент масиву стає primary-значенням. | | Передано одиничне поле і масив | Одиничне поле лишається primary, масив у відповіді повертається відсортованим. | | active змінюється з false на true | Сервер створює або синхронізує пов’язаного Keycloak-користувача. | | active змінюється з true на false | Сервер видаляє пов’язаного Keycloak-користувача. | | active і email змінюються одночасно | Синхронізується акаунт, уже пов’язаний із цим employee. | Помилки Error responses | HTTP status | Коли виникає | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | 400 Bad Request | Порожній PATCH-body або невалідні значення, зокрема порожні name / surname. | | 401 Unauthorized | Bearer token відсутній або невалідний. | | 403 Forbidden | Недостатньо прав або token без company context. | | 404 Not Found | Співробітника не знайдено в межах поточного tenant-а. | | 409 Conflict | Новий email уже зайнятий іншим employee або не може бути безпечно використаний для синхронізації доступу в Keycloak. | | 500 Internal Server Error | Неочікувана помилка BFF. | | 503 Service Unavailable | Збій внутрішньої інтеграції BFF -> back2. | Використання - Оновити контактні дані співробітника. - Змінити департамент або посаду. - Увімкнути доступ до приватного кабінету через active = true. - Відкликати доступ до приватного кабінету через active = false. - Оновити email з перевіркою конфлікту. Типові помилки Typical integration mistakes | Типова помилка | Як правильно | | ----------------------------------------------------- | ------------------------------------------------------------------- | | Надсилати порожній PATCH-body | Передайте хоча б одне поле для зміни. | | Передавати fullName | Передавайте name і surname. | | Передавати порожні name або surname | Якщо поле передане, воно має містити непорожній текст. | | Очікувати, що зміна active лише змінює прапорець у БД | active також керує синхронізацією пов’язаного Keycloak-користувача. | | Передавати idCompany або hrEmail | Не передавайте ці значення; BFF бере їх із Bearer token. | FAQ Чи можна передати тільки одне поле в PATCH? Так. Body має містити хоча б одне поле. Чи можна змінити fullName напряму? Ні. fullName не входить у PATCH-контракт. Використовуйте name і surname. Що буде, якщо новий email уже зайнятий? API поверне 409 Conflict. Що відбувається при active = false? Сервер видаляє пов’язаного Keycloak-користувача і відкликає доступ до приватного кабінету. Що відбувається, якщо одночасно змінити active і email? Сервер синхронізує акаунт, який уже пов’язаний із цим employee.

Востаннє оновлено Apr 25, 2026

Як видалити співробітника через API?

DELETE /v1/employees/{employeeId} видаляє співробітника в межах tenant-контексту. Успішна відповідь — 204 No Content. Endpoint | Параметр | Значення | | -------------- | ---------------------------------------------------- | | Method | DELETE | | Path | /v1/employees/{employeeId} | | Base URL | https://smartway.pro/api | | Auth | Bearer token | | Required scope | employees.write | Призначення Endpoint використовується для видалення співробітника за employeeId. Операція виконується в межах tenant-контексту з Bearer token. Передумови - Клієнт має передати валідний Bearer token. - Token має містити company context. - Token має містити scope employees.write. - idCompany не передається окремо. - employeeId має належати співробітнику в межах поточного tenant-а. Запит Path parameters | Параметр | Тип | Обов’язковий | Опис | | ------------ | ------- | ---------------- | ----------------- | | employeeId | int64 | так | ID співробітника. | curl приклад Видалити співробітника curl -X DELETE 'https://smartway.pro/api/v1/employees/4432' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Відповідь Успішна відповідь: 204 No Content. Успішна відповідь не містить body. Поля відповіді Delete response | Елемент | Тип | Опис | | ------------- | -------------- | -------------------------- | | HTTP status | 204 No Content | Операція виконана успішно. | | Response body | відсутній | Body не повертається. | Бізнес-логіка - BFF бере companyId з Bearer token, а не з параметрів запиту. - Endpoint видаляє співробітника тільки в межах поточного tenant-контексту. - Для доступу потрібен scope employees.write. Edge cases Edge cases | Сценарій | Поведінка API | | ------------------------------------------- | --------------------------------------------------------- | | employeeId не знайдено в поточному tenant-і | API повертає 404 Not Found. | | Bearer token без employees.write | API повертає 403 Forbidden. | | Операція успішна | API повертає 204 No Content без body. | | Клієнт передає idCompany | Endpoint не використовує idCompany з клієнтського запиту. | Помилки Error responses | HTTP status | Коли виникає | | ------------------------- | ----------------------------------------------------- | | 401 Unauthorized | Bearer token відсутній або невалідний. | | 403 Forbidden | Недостатньо прав або token без company context. | | 404 Not Found | Співробітника не знайдено в межах поточного tenant-а. | | 500 Internal Server Error | Неочікувана помилка BFF. | | 503 Service Unavailable | Збій внутрішньої інтеграції BFF -> back2. | Використання - Видалити співробітника з LMS Smart Way через інтеграцію. - Очистити тестові записи після перевірки інтеграції. - Прибрати співробітника, який більше не має бути в employee dataset. Типові помилки Typical integration mistakes | Типова помилка | Як правильно | | ----------------------------------------- | ------------------------------------------------------------ | | Очікувати JSON у відповіді | Успішна відповідь — 204 No Content без body. | | Передавати idCompany | Не передавайте idCompany; companyId береться з Bearer token. | | Використовувати token без employees.write | Для DELETE потрібен scope employees.write. | FAQ Що повертає API після успішного видалення? 204 No Content без response body. Чи потрібно передавати idCompany? Ні. companyId береться з Bearer token. Що буде, якщо employeeId не знайдено? API поверне 404 Not Found.

Востаннє оновлено Apr 25, 2026