Темный режим
4. API интеграция
4.1. Описание API endpoints
HRoom предоставляет комплексный набор REST API endpoints для взаимодействия с различными частями системы. Все API endpoints организованы по функциональным модулям и имеют единый формат ответов.
Базовый URL API
Все API запросы выполняются к базовому URL: https://api.hroom.ai/webhook/
Основные API endpoints
Аутентификация и пользователи
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/auth/login |
POST | Аутентификация пользователя | email, password | - |
JSON |
/auth/signup |
POST | Регистрация нового пользователя | email, password, firstName, lastName, companyName, phone | - |
JSON |
/auth/activation |
GET | Активация аккаунта по ссылке из email | token | - |
JSON |
/auth/activation-retry |
GET | Повторная отправка письма активации | - |
JSON |
|
/auth/reset |
POST | Запрос на сброс пароля | - |
JSON |
|
/auth/newpass |
POST | Установка нового пароля после сброса | token, password | - |
JSON |
Метрики и аналитика
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/teams/metric/get |
GET | Получение метрик команды | curdate [6m, 3m, 1m], paramNameMetric | company_token |
JSON |
/metric/dynamic/get |
GET | Получение динамики изменения метрик | - | company_token |
JSON |
/metric/score |
GET | Получение общего показателя метрики | - | company_token |
JSON |
Вопросы и опросы
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/questions/get |
POST | Получение списка вопросов | departmentId, paramNameMetric | company_token |
JSON |
/surveys/get |
POST | Получение списка опросов | - | company_token |
JSON |
/surveys/create |
POST | Создание нового опроса | name, status [planned, draft], type [q20, q5], test [Boolean], start_date, end_date, auditory [{"departmentIds": []}] | company_token |
JSON |
/surveys/delete |
POST | Удаление опроса | surveyId | company_token |
JSON |
/surveys/update |
POST | Обновление данных опроса | surveyId, name, status [planned, draft], type [q20, q5], test [Boolean], start_date, end_date, auditory [{"departmentIds": []}] | company_token |
JSON |
/surveys/complete |
POST | Завершение опроса | surveyId | company_token |
JSON |
/surveys/count |
POST | Получение количества опросов по компании | - | company_token |
JSON |
/survey/data/get |
GET | Получение данных опроса | surveyId(uuid),userId(uuid) | - |
JSON |
Сотрудники и отделы
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/employees/get |
POST | Получение списка сотрудников | departmentId, status, hireDate, searchTerm, userId | company_token |
JSON |
/employees/count |
POST | Получение количества сотрудников в компании | - | company_token |
JSON |
/employees/create |
POST | Создание нового сотрудника | lastName, firstName, middleName, role, city, birthDate, hireDate, gender, phone, email, telegram, departmentId, status | company_token |
JSON |
/employees/delete |
POST | Удаление сотрудника | userId | company_token |
JSON |
/employees/update |
POST | Обновление данных сотрудника | lastName, firstName, middleName, role, city, birthDate, hireDate, gender, phone, email, telegram, departmentId, status, userId | company_token |
JSON |
/employees/import |
POST | Массовый импорт сотрудников | file[csv/xlsx] | company_token |
JSON |
/departments/get |
POST | Получение списка отделов компании | heads[true/false] | company_token |
JSON |
/departments/create |
POST | Создание нового отдела | name, headid | company_token |
JSON |
/departments/delete |
POST | Удаление отдела | departmentId | company_token |
JSON |
/departments/update |
POST | Обновление данных отдела | departmentId, name, headid | company_token |
JSON |
Профиль и настройки
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/profile/personal/get |
POST | Получение личных данных пользователя | - | manager_token |
JSON |
/profile/personal/save |
POST | Сохранение личных данных пользователя | managerid, firstname, lastname, middlename, phone | manager_token |
JSON |
/profile/company/get |
POST | Получение данных компании пользователя | - | company_token |
JSON |
/profile/company/save |
POST | Сохранение данных компании | ncompanyId, name, website, billingInfo: { "legalAddress", "actualAddress", "kpp", "inn", "ogrn", "bankAccount", "corrAccount", "bik", "bankName" } | manager_token |
JSON |
/profile/company/billing/get |
POST | Получение платежных данных компании | - | company_token |
JSON |
/profile/company/billing/save |
POST | Сохранение платежных данных компании | billingInfo: { "legalAddress", "actualAddress", "kpp", "inn", "ogrn", "bankAccount", "corrAccount", "bik", "bankName" } | company_token |
JSON |
/profile/file/upload |
POST | Загрузка файла (аватар, лого и т.д.) | file (image) | manager_token |
JSON |
/unsubscribe |
GET | Отписка от рассылок | token (user uuid) or manager_token (uuis), action (true/false), status | - |
JSON |
AI рекомендации и инсайты
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/ai/get |
GET | Получение ИИ советов/инсайтов | departmentId, type, paramNameMetric | company_token |
JSON |
/ai/get/long |
GET | Получение детальной информации по ИИ совету/инсайту | ai_data_id | company_token |
JSON |
Администрирование
| Endpoint | Метод | Описание | Параметры | Auth | Формат ответа |
|---|---|---|---|---|---|
/company/get |
POST | Получение списка компаний | companyId (all, id) | manager_token |
JSON |
/company/add |
POST | Добавление новой компании | name, accountType, website, expirationDate | manager_token |
JSON |
/company/update |
POST | Обновление данных компании | name, accountType, website, expirationDate | manager_token |
JSON |
/company/delete |
POST | Удаление компании | companyId | manager_token |
JSON |
/managers/get |
POST | Получение списка HR-менеджеров | companyId, isActive, search, page, limit, sortBy, sortDirection | manager_token |
JSON |
/managers/add |
POST | Добавление нового HR-менеджера | firstname, lastname, middlename, phone, companyId, email | manager_token |
JSON |
/managers/update |
POST | Обновление данных HR-менеджера | managerid, firstname, lastname, middlename, phone, companyId, email | manager_token |
JSON |
/managers/delete |
POST | Удаление HR-менеджера | managerid | manager_token |
JSON |
/translations/get |
GET | Получение переводов интерфейса | key, type | company_token |
JSON |
4.2. Аутентификация запросов
Все API-запросы к HRoom (кроме публичных endpoints) требуют аутентификации. HRoom использует механизм JWT-токенов для авторизации и аутентификации запросов.
Получение токена
Для получения токена необходимо выполнить авторизацию через эндпоинт /auth/login:
// Пример запроса авторизации
const loginResponse = await fetch('https://api.hroom.ai/webhook/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
password: 'password123'
})
});
// Получение токенов из ответа
const authData = await loginResponse.json();
const companyToken = authData.company_token; // Токен компании для доступа к общим данным
const managerToken = authData.manager_token; // Токен HR-менеджера для управления ресурсами
// Сохранение токенов в localStorage
localStorage.setItem('companyToken', companyToken);
localStorage.setItem('managerToken', managerToken);
Использование токена в запросах
Полученные токены необходимо включать в заголовок Authorization запросов. В зависимости от endpoint следует использовать либо company_token, либо manager_token:
// Пример запроса с авторизацией через company_token
const response = await fetch('https://api.hroom.ai/webhook/teams/metric/get', {
headers: {
'Authorization': `Bearer ${localStorage.getItem('companyToken')}`,
'Content-Type': 'application/json'
}
});
// Пример запроса с авторизацией через manager_token
const surveysResponse = await fetch('https://api.hroom.ai/webhook/surveys/get', {
method: 'POST',
headers: {
'Authorization': `Bearer ${localStorage.getItem('managerToken')}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'ACTIVE'
})
});
Хранение токенов
В приложении HRoom токены сохраняются в localStorage для использования между сессиями:
// Сохранение токенов в localStorage
localStorage.setItem('companyToken', companyToken);
localStorage.setItem('managerToken', managerToken);
// Получение токенов из localStorage
const companyToken = localStorage.getItem('companyToken');
const managerToken = localStorage.getItem('managerToken');
Однако стоит помнить о потенциальных рисках безопасности при хранении токена в localStorage. В более критичных с точки зрения безопасности сценариях можно рассмотреть использование sessionStorage или HTTP-only куки.
Обновление токена
JWT-токены имеют ограниченный срок действия. После истечения срока действия токена необходима повторная авторизация пользователя. Система отслеживает состояние токена и перенаправляет пользователя на страницу входа при получении ошибки 401 (Unauthorized).
Использование API-клиента с интерцепторами
В HRoom используется централизованный API-клиент, который автоматически добавляет токен к каждому запросу:
// Пример API-клиента с интерцепторами для авторизации
const apiClient = {
async request(url, options = {}) {
// Определяем, какой токен использовать в зависимости от endpoint
let token;
if (url.includes('/teams/') || url.includes('/metric/')) {
token = localStorage.getItem('companyToken');
} else {
token = localStorage.getItem('managerToken');
}
const headers = {
'Content-Type': 'application/json',
...options.headers
};
if (token) {
headers.Authorization = `Bearer ${token}`;
}
const config = {
...options,
headers
};
try {
const response = await fetch(`https://api.hroom.ai/webhook${url}`, config);
// Обработка ошибки авторизации
if (response.status === 401) {
localStorage.removeItem('companyToken');
localStorage.removeItem('managerToken');
window.location.href = '/auth/login';
return Promise.reject(new Error('Unauthorized'));
}
return response;
} catch (error) {
console.error('API request failed:', error);
throw error;
}
},
// GET запрос
async get(url, options = {}) {
return this.request(url, { ...options, method: 'GET' });
},
// POST запрос
async post(url, data, options = {}) {
return this.request(url, {
...options,
method: 'POST',
body: JSON.stringify(data)
});
},
};