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

GET /v1/employees повертає сторінку співробітників. Якщо query-параметри не передати, API застосовує page = 0 і size = 50.

Endpoint

Параметр	Значення
Method	GET
Path	`/api/v1/employees`
Base URL	`https://smartway.pro`
Auth	Bearer token
Required scope	`employees.read`

Призначення

Endpoint використовується для отримання сторінкового списку співробітників у межах компанії з Bearer token.

Endpoint підтримує пагінацію, пошук за ПІБ і фільтри за департаментом та посадою.

Передумови

Клієнт має передати валідний Bearer token.

Token має містити company context.

Token має містити scope employees.read.

idCompany не передається зовнішнім клієнтом. API визначає 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,
      "manager": true
    }
  ],
  "meta": {
    "page": 0,
    "size": 50,
    "totalElements": 385,
    "totalPages": 8,
    "hasNext": true
  }
}

Поля відповіді

EmployeeListResponse

Поле	Тип	Опис
`data`	Employee[]	Масив співробітників.
`meta`	object	Метадані пагінації.

Поле	Тип	Опис
`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	Ознака активності.
`manager`	boolean	Ознака ролі керівника підрозділу. `true` означає, що співробітник має цю роль.

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

Параметр page є 0-based: page=0 - перша сторінка, page=1 - друга сторінка.

Якщо page і size не передані, API застосовує page = 0 і size = 50.

q шукає лише за ПІБ з частковим співпадінням. Пошук за email не підтримується.

department і jobTitle звужують вибірку за відповідними значеннями.

Параметри можна комбінувати між собою; сукупність параметрів застосовується через логіку AND.

Доступ до даних обмежений tenant-контекстом із Bearer token.

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

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

Виклик без параметрів.

Пагіноване завантаження співробітників у зовнішню систему.

Фільтрація списку за департаментом або посадою.

Пошук співробітника за частиною ПІБ.

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

Typical integration mistakes

Типова помилка	Як правильно
Передавати `idCompany` у query string	Не передавайте `idCompany`. API визначає `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 не передається зовнішнім клієнтом; API визначає companyId з Bearer token.

Чи підтримує q пошук за email?

Ні. q підтримує пошук за ПІБ з частковим співпадінням.

Які значення page і size використовуються за замовчуванням?

page = 0 і size = 50.

Чи можна комбінувати q, department і jobTitle?

Так. Параметри комбінуються через логіку AND.