Как получить список сотрудников через API?

GET /v1/employees возвращает страницу сотрудников. Если query-параметры не переданы, API применяет значения по умолчанию: page = 0 и size = 50.

Endpoint

Назначение

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

curl пример

Вызов без параметров

curl -X GET 'https://smartway.pro/api/v1/employees' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Вызов с параметрами

curl -X GET 'https://smartway.pro/api/v1/employees?page=0&size=20&q=Иван' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Вызов с несколькими UTF-8 параметрами

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

Employee

Pagination meta

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

Все query-параметры необязательные.

Если endpoint вызвать без параметров, API возвращает первую страницу сотрудников: page = 0, size = 50.

Параметр page является 0-based: page = 0 - первая страница, page = 1 - вторая страница.

API определяет companyId только из Bearer token.

idCompany не передаётся внешним клиентом.

Поиск q работает по ФИО с частичным совпадением.

Поиск по email не поддерживается.

Параметры q, department и jobTitle поддерживают UTF-8.

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

Для доступа нужен scope employees.read.

Edge cases

Ошибки

Error responses

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

Без query-параметров.

Получение следующей страницы через page.

Изменение размера страницы через size.

Поиск сотрудника по ФИО через q.

Фильтрация сотрудников по department или jobTitle.

Комбинирование поиска и фильтров для узкой выборки.

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

Typical integration mistakes

FAQ

Можно ли вызвать endpoint без query-параметров?

Да. API применит page = 0 и size = 50.

С какой страницы начинается пагинация?

С page = 0.

Поддерживается ли поиск по email?

Нет. Параметр q ищет по ФИО с частичным совпадением.

Можно ли комбинировать фильтры?

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

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

Нет. API определяет companyId из Bearer token.