---
title: "API v3"
description: "Розділ «Налаштування»"
url: https://support.hurma.work/uk/articles/153-api-v3
collection: "API"
updated: 2026-06-14
language: uk
alternates: [en]
---

# API v3

Розділ «Налаштування»

> **Info:** Функціонал API v3 доступний в тарифах **«PRO»**
>
> Для розширення вашого тарифу ви можете звернутися до вашого персонального менеджера/-ки або на пошту [support@hurma.work](mailto:support@hurma.work)

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

1.  Перейдіть на сторінку “⚙” - “Для розробників” в HURMA.  
    
    ![](https://staticfiles.gleap.io/gattachments/kmhZ2Xrfc6FetxHAndncHaeiTbmtGJI68nZRNUjQuC4Sct2ImLhLGp10VsuPc1Le7dn4vSAFsP2.png)
    
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.  Сформуйте запит на авторизацію:
    

```javascript
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:
    

```javascript
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

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

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

```javascript
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
```

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

> **Info:** Переглянути всі доступні ендпоінти, структуру запитів та відповідей можна у [API документації](https://developers.hurma.work/docs/getting-started)

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

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

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

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

```javascript
<?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);
}

```

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

```javascript
<?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](mailto:support@hurma.work)
    
-   в [Telegram](https://t.me/HSsupport)