# Як використовувати API ConnectiveOne

ConnectiveOne надає REST API для отримання та зміни даних, запуску сценаріїв та інтеграції з зовнішніми системами. Ця стаття пояснює основи роботи з API. Для повного списку endpoints та деталей дивіться [API довідник](/uk/integrations/reference/api-reference.md).

## Що можна робити через API?

- Отримувати дані про діалоги, операторів, користувачів, тікети
- Змінювати параметри діалогів (статус, тему, коментар)
- Запускати сценарії ботів
- Керувати даними через Custom Data API
- Отримувати статистику та аналітику

## Доступ до API документації

Для перегляду всіх доступних endpoints:

1. Відкрийте **меню допомоги** (іконка "?" у верхньому правому куті)
2. Оберіть **"API документація"**

Відкриється Swagger UI з повною документацією та можливістю тестування endpoints.

> 💡 **Порада:** Swagger UI дозволяє не тільки переглядати документацію, але й тестувати API endpoints безпосередньо в інтерфейсі.

## Авторизація

Для виконання запитів до API необхідна авторизація. ConnectiveOne підтримує два типи авторизації:

### API Key (спрощена авторизація)

Використовується для простих запитів. Ключ API можна отримати в **Налаштування → Список ботів → Налаштування бота**.

**Формат заголовка:**
```http
Authorization: API-Key YOUR_API_KEY
```

**Приклад curl:**
```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/general/KwBots/get \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### JWT Token (повноцінна авторизація)

Для корпоративних клієнтів доступна авторизація через JWT токен, яка включає функції оновлення токена, встановлення терміну дії та обмежень на швидкість запитів.

**Формат заголовка:**
```http
Authorization: Bearer YOUR_JWT_TOKEN
```

**Отримання JWT токена:**
Використовуйте endpoint `/api/v1/auth/login` для отримання JWT токена.

## Основні типи запитів

### GET (отримання даних)

Використовується для отримання даних з ConnectiveOne.

**Формат:**
```
GET https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/get
```

**Приклад:**
```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/get \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### POST (створення/оновлення)

Використовується для створення або оновлення даних.

**Формат:**
```
POST https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/set
```

**Приклад:**
```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/set \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "chatroom_id": 123
  }'
```

## Формат відповіді

**Успішна відповідь:**
```json
{
  "status": "success",
  "data": [...]
}
```

**Помилка:**
```json
{
  "status": "error",
  "message": "Error description"
}
```

## Приклади використання

### Приклад 1: Отримання списку діалогів

```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/v1/OpChatRooms/list \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### Приклад 2: Зміна статусу діалогу

```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'
```

### Приклад 3: Зміна теми та статусу діалогу

```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": 5,
    "status": "processed",
    "kw_chat_title": "New Title",
    "comment": "Updated via API"
  }'
```

## Доступні модулі

### Модуль Загальний
- Список ботів
- Зареєстровані клієнти

### Модуль Панель оператора
- Діалоги через панелі оператора
- Оператори
- Теми (тематики) в панелях операторів
- Швидкі відповіді
- Групи навичок

### Модуль Custom Data
- Всі дані з користувальницьких модулів

### API для запуску сценаріїв
- `call_node` - запуск сценарію через API
- Entry Point URLs - прямі посилання для запуску

## Безпека та обмеження

### Безпека
- Використовуйте HTTPS для всіх запитів
- Зберігайте API ключі та токени в безпечному місці
- Не передавайте ключі в публічних місцях або логах
- Можна налаштувати список IP-адрес для обмеження доступу
- Дані зберігаються відповідно до стандарту ISO 27001

### Обмеження
- Модуль API доступний для корпоративних користувачів
- Необхідна авторизація для всіх запитів
- Rate limiting може застосовуватися залежно від тарифного плану
- Максимальний розмір даних обмежений налаштуваннями системи

## Де знайти повну документацію?

1. **Swagger UI в системі** — меню допомоги → API документація (`/api-docs`)
2. **API довідник** — [повний список endpoints](/uk/integrations/reference/api-reference.md)

## Пов'язані статті

- [API довідник](/uk/integrations/reference/api-reference.md) — повний список endpoints та параметрів
- [Запуск сценарію через API call_node](/uk/integrations/how-to/launch-scenario-via-call-node.md)
- [Що таке інтеграції](/uk/integrations/explanation/what-are-integrations.md) — огляд типів інтеграцій