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

GET /v1/employees/{employeeId} повертає одного співробітника за ID у межах tenant-контексту з Bearer token.

Endpoint

Параметр	Значення
Method	GET
Path	`/api/v1/employees/{employeeId}`
Base URL	`https://smartway.pro`
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/4329' \
  -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,
  "manager": 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	Ознака активності.
`manager`	boolean	Ознака ролі керівника підрозділу. `true` означає, що співробітник має цю роль.

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

API визначає companyId з Bearer token, а не з параметрів запиту.

Endpoint повертає співробітника тільки з поточного tenant-контексту.

Якщо співробітника не знайдено в межах поточного tenant-а, API повертає 404 Not Found.

Для доступу потрібен scope employees.read.

fullName є похідним полем і формується сервером з name + surname.

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`	Неочікувана помилка API.
`503 Service Unavailable`	Збій внутрішньої серверної інтеграції.

Використання

Отримати картку співробітника після вибору запису зі списку.

Перевірити актуальні поля співробітника перед PATCH.

Завантажити один Employee для синхронізації у зовнішній системі.

Типові помилки

Typical integration mistakes

Типова помилка	Як правильно
Вважати `employeeId` глобальним для всіх tenant-ів	`employeeId` шукається в межах tenant-контексту з Bearer token.
Передавати `idCompany` окремо	Не передавайте `idCompany`; API визначає `companyId` з token.
Використовувати token без `employees.read`	Додайте scope `employees.read`.

FAQ

Чи можна отримати співробітника з іншої компанії?

Ні. Пошук виконується в межах tenant-контексту з Bearer token.

Що повертає API, якщо employeeId не знайдено?

API повертає 404 Not Found.

Чи потрібно передавати idCompany?

Ні. API визначає companyId з Bearer token.