Как получить сотрудника по 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.
idCompany не передаётся отдельным параметром.
Поиск сотрудника выполняется в рамках tenant-контекста из Bearer token.
Если employeeId не найден в текущем tenant-е, API возвращает 404 Not Found.
Для доступа нужен scope employees.read.
fullName является производным полем и формируется сервером из name + surname.

Edge cases

Edge cases

Сценарий	Поведение API
employeeId существует в текущем tenant-е	API возвращает 200 OK и Employee.
employeeId не найден в текущем tenant-е	API возвращает 404 Not Found.
employeeId существует в другой компании	API не возвращает сотрудника вне текущего tenant-контекста.
Bearer token без company context	API возвращает 403 Forbidden.
Клиент передаёт 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.

Использование

Получить карточку сотрудника по employeeId.
Проверить результат создания или обновления сотрудника.
Синхронизировать данные одного сотрудника во внешней системе.
Проверить, доступен ли employeeId в рамках текущего tenant-а.

Типичные ошибки

Typical integration mistakes

Типичная ошибка	Как правильно
Передавать idCompany вместе с employeeId	Не передавайте idCompany; tenant определяется Bearer token.
Использовать token без employees.read	Для чтения сотрудника нужен scope employees.read.
Ожидать доступ к сотруднику другой компании	API ищет только в текущем tenant-контексте.
Считать 404 технической ошибкой	404 означает, что сотрудник не найден в текущем tenant-е.

FAQ

Нужно ли передавать idCompany?

Нет. companyId берётся из Bearer token.

Какой scope нужен?

employees.read.

Что будет, если employeeId не найден?

API вернёт 404 Not Found.

Возвращается ли fullName?

Да. fullName возвращается как поле Employee и формируется сервером из name + surname.

Appearance

Language