Как получить список сотрудников через 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 не передаётся внешним клиентом. BFF берёт 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
    }
  ],
  "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 — вторая страница.

• BFF берёт companyId только из Bearer token.

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

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

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

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

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

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

Edge cases

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?

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