Як отримати співробітника за 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 передається автоматично.

Appearance

Language