API v3

Функціонал API v3 доступний в тарифах «PRO».

Для розширення вашого тарифу ви можете звернутися до вашого персонального менеджера/-ки або на пошту support@hurma.work

Створення API-додатку

1. Перейдіть на сторінку “Налаштування” - “Для розробників” в HURMA.
   

   

2. Натисніть кнопку “Додати клієнт API”. У формі, що відкриється, заповніть поля:

   • Назва - довільна назва вашого додатку (наприклад, "Інтеграція з ERP").

   • Тип авторизації

     • Authorization code - рекомендовано для зовнішніх додатків із авторизацією користувача (через OAuth 2.0).

     • Password - прямий обмін логіном та паролем на токен (використовується в trusted-інтеграціях, наприклад, бекенд до бекенду)

   • Редірект - адреса, куди система буде надсилати код авторизації після входу користувача. Це обов'язкове поле при виборі типу авторизації “Authorization code”.

   • Опис - додаткова інформація або призначення інтеграції (необов’язково).

   • Налаштування доступу до інформації через API та Чутливі поля API - набір дозволів, які будуть доступні цьому додатку.

3. Натисніть “Зберегти” - після цього додаток з'явиться в списку згенерованих клієнтів. Після цього ви отримаєте такі дані:

• Client ID

• Client Secret

Ці значення будуть потрібні для авторизації.

Авторизація через OAuth 2.0

Інтеграція з HURMA API можлива через два методи:

Тип 1: Authorization Code (рекомендовано)

Цей метод підходить, якщо інтеграція передбачає авторизацію через інтерфейс користувача.

1. Сформуйте запит на авторизацію:

GET https://yourcompany.hurma.work/api/v3/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI

2. Користувач авторизується → HURMA перенаправить на ваш redirect_uri із кодом у параметрах (?code=XXXXXX).

3. Обміняйте код на access token:

POST https://yourcompany.hurma.work/api/v3/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=CODE_FROM_STEP_2
&redirect_uri=YOUR_REDIRECT_URI

4. Отримайте access token у відповіді.

Тип 2: Password

Цей метод підходить для серверних сценаріїв без участі користувача.

Надішліть запит на токен:

POST https://yourcompany.hurma.work/api/v3/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&username=USER_EMAIL
&password=USER_PASSWORD

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

Переглянути всі доступні ендпоінти, структуру запитів та відповідей можна у Swagger.

Додайте отриманий access_token до кожного запиту до API:

GET /api/v3/users
Host: yourcompany.hurma.work
Authorization: Bearer YOUR_ACCESS_TOKEN

Приклади запитів на PHP

Отримання токена приклад на чистому PHP

<?php


// Конфігурація
$tokenUrl = 'https://yourdomain.hurma.work/api/v3/oauth/token'; // URL для отримання токена
$clientId = '13';
$clientSecret = '1234nFGPeGLa87dfgkWTpirB39pB4ijK34W3E9P8';
$username = 'email@gmail.com';
$password = '*******';


// Формуємо дані для запиту
$data = [
   'grant_type'    => 'password',
   'client_id'     => $clientId,
   'client_secret' => $clientSecret,
   'username'      => $username,
   'password'      => $password,
];


// Ініціалізуємо cURL
$ch = curl_init();


curl_setopt($ch, CURLOPT_URL, $tokenUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


// Якщо API повертає JSON
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   'Accept: application/json',
]);


$response = curl_exec($ch);


if (curl_errno($ch)) {
   echo 'cURL error: ' . curl_error($ch);
   curl_close($ch);
   exit;
}


curl_close($ch);


// Парсимо відповідь
$result = json_decode($response, true);


// Перевіряємо, чи є токен
if (isset($result['access_token'])) {
   echo "Access Token: " . $result['access_token'] . PHP_EOL;
   // Збережи токен у сесії або локально
} else {
   echo "Помилка отримання токена:\n";
   print_r($result);
}

Запит до списку кандидатів

<?php


// Встанови сюди актуальний токен, який отримав раніше
$accessToken = 'your-token';


// URL ендпоінта
$candidatesUrl = 'https://hurmaqa23.hurma.work/api/v3/candidates';


// Ініціалізуємо cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $candidatesUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


// Додаємо заголовок з токеном
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   'Accept: application/json',
   'Authorization: Bearer ' . $accessToken,
]);


// Виконуємо запит
$response = curl_exec($ch);


if (curl_errno($ch)) {
   echo 'cURL error: ' . curl_error($ch);
   curl_close($ch);
   exit;
}


curl_close($ch);


// Розбираємо JSON
$result = json_decode($response, true);


// Виводимо результат
echo "===== Кандидати =====\n";
print_r($result);

Поради безпеки

• Використовуйте HTTPS для всіх запитів.

• Зберігайте Client Secret у безпечному місці.

• Не використовуйте Password Flow у браузері.

• Регулярно оновлюйте access token за допомогою refresh_token, якщо використовується тип авторизації “Authorization Code”.

Підтримка

У разі виникнення питань, ви можете написати нашій команді:

• в чат всередині системи

• на пошту support@hurma.work

• в Telegram