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

Appearance

Language