# API Reference — Довідник по API ConnectiveOne

API Reference містить загальну інформацію про ConnectiveOne API, навігацію до Swagger документації та приклади основних сценаріїв використання. Для детальної інформації про всі endpoints використовуйте Swagger UI в системі.

## Що таке ConnectiveOne API?

ConnectiveOne API — це REST API для інтеграції з платформою ConnectiveOne. API дозволяє:
- Отримувати дані про чати, тікети, користувачів
- Надсилати повідомлення клієнтам через сценарії ботів
- Керувати даними через Custom Data API
- Отримувати статистику та аналітику
- Інтегруватися з іншими системами

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

Swagger документація доступна безпосередньо в інтерфейсі ConnectiveOne:

1. Відкрийте **меню допомоги** (іконка допомоги в правому верхньому куті інтерфейсу)
2. Оберіть **"API Documentation"** або перейдіть за посиланням `/api-docs`
3. Swagger UI відкриється з повною документацією по всіх API endpoints

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

## Автентифікація

ConnectiveOne API підтримує два типи автентифікації:

### JWT Bearer Token

Використовується для автентифікації через JWT токен:

```http
Authorization: Bearer YOUR_JWT_TOKEN
```

### x-auth-token

Використовується для автентифікації через зовнішній токен:

```http
x-auth-token: YOUR_TOKEN
```

> 📖 **Детальніше:** Повну інформацію про автентифікацію та отримання токенів дивіться в Swagger UI в розділі "Authentication" або в технічній документації.

## Основні групи API

ConnectiveOne API організований за модулями та функціональністю. Нижче наведено перелік основних груп endpoints:

### Authentication
Endpoints для автентифікації та управління сесіями користувачів.

**Основні endpoints:**
- Логін користувача
- Оновлення токену
- Вихід з системи

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Authentication".

### Users
Endpoints для управління користувачами системи.

**Основні endpoints:**
- Отримання списку користувачів
- Отримання користувача за ID
- Створення та оновлення користувачів

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Users".

### Chats
Endpoints для роботи з чатами та діалогами.

**Основні endpoints:**
- Отримання списку чатів (`/kw/api/v1/OpChatRooms/list`)
- Отримання чату за ID
- Фільтрація, сортування та пагінація

**Функціонал:**
- Фільтрація за датою створення, статусом, оператором
- Сортування за різними полями
- Пагінація результатів
- Включення пов'язаних даних (include)

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Chats".

### Tickets
Endpoints для роботи з тікетами.

**Основні endpoints:**
- Отримання списку тікетів (`/kw/api/v1/Ticket/list`)
- Отримання тікету за ID
- Створення та оновлення тікетів

**Функціонал:**
- Фільтрація за датою створення, статусом, пріоритетом
- Сортування за різними полями
- Пагінація результатів
- Включення пов'язаних даних (include)

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Tickets".

### Broadcast
Endpoints для роботи з масовими розсилками.

**Основні endpoints:**
- Створення розсилок
- Управління шаблонами розсилок
- Перегляд результатів розсилок

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Broadcast".

### Custom Data
Endpoints для роботи з кастомними даними та моделями.

**Основні endpoints:**
- Отримання даних з кастомних моделей
- Створення та оновлення записів
- Пошук та фільтрація даних

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Custom Data".

### Call Node
Endpoints для виклику сценаріїв ботів та надсилання повідомлень.

**Основні endpoints:**
- Виклик сценарію через `call_node` (`/kw/api/call_node/`)
- Надсилання повідомлень клієнтам

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Call Node".

### Statistics
Endpoints для отримання статистики та аналітики.

**Основні endpoints:**
- Отримання статистики операторів
- Отримання статистики діалогів
- Отримання метрик SLA

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Statistics".

### Quality Assurance
Endpoints для роботи з системою контролю якості.

**Основні endpoints:**
- Отримання оцінок якості
- Управління критеріями оцінки

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Quality Assurance".

## Приклади основних сценаріїв

### Надсилання повідомлення через call_node

Надсилання повідомлення клієнту через виклик сценарію бота:

**Endpoint:**
```
POST /kw/api/call_node/{bot_id}/{node_id}/{channel}/{chat_id}
```

**Або через JSON body:**
```
POST /kw/api/call_node/
```

**Приклад запиту:**
```json
{
  "bot_id": 1,
  "connector_alias": "entry_point_alias",
  "channel": "telegram",
  "chat_id": "567890",
  "data": {
    "message": "Ваше замовлення готове!"
  }
}
```

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Call Node".

### Отримання списку чатів

Отримання списку чатів з фільтрацією та пагінацією:

**Endpoint:**
```
GET /kw/api/v1/OpChatRooms/list
```

**Приклад запиту з параметрами:**
```
GET /kw/api/v1/OpChatRooms/list?filter[createdAt][gt]=2024-12-01T00:00:00.000Z&filter[createdAt][lt]=2024-12-29T00:00:00.000Z&limit=10&offset=0&order[createdAt]=desc
```

**Параметри:**
- `filter[createdAt][gt]` — фільтр за датою створення ВІД
- `filter[createdAt][lt]` — фільтр за датою створення ДО
- `limit` — кількість записів (за замовчуванням 10)
- `offset` — кількість записів для пропуску
- `order[createdAt]` — сортування (desc або asc)

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Chats".

### Отримання списку тікетів

Отримання списку тікетів з фільтрацією та пагінацією:

**Endpoint:**
```
GET /kw/api/v1/Ticket/list
```

**Приклад запиту з параметрами:**
```
GET /kw/api/v1/Ticket/list?filter[createdAt][gt]=2024-12-01T00:00:00.000Z&filter[createdAt][lt]=2024-12-29T00:00:00.000Z&limit=10&offset=0&order[createdAt]=desc
```

**Параметри:**
- `filter[createdAt][gt]` — фільтр за датою створення ВІД
- `filter[createdAt][lt]` — фільтр за датою створення ДО
- `limit` — кількість записів (за замовчуванням 10)
- `offset` — кількість записів для пропуску
- `order[createdAt]` — сортування (desc або asc)

> 📖 **Детальніше:** Дивіться в Swagger UI в розділі "Tickets".

## Як використовувати Swagger UI

Swagger UI в ConnectiveOne дозволяє:

1. **Переглядати документацію** — детальний опис всіх endpoints, параметрів та відповідей
2. **Тестувати API** — виконувати запити безпосередньо в інтерфейсі
3. **Переглядати схеми** — структури даних для запитів та відповідей
4. **Копіювати приклади** — готові приклади запитів для використання в коді

### Як відкрити Swagger UI

1. Відкрийте **меню допомоги** (іконка допомоги в правому верхньому куті)
2. Оберіть **"API Documentation"** або перейдіть за посиланням `/api-docs`
3. Swagger UI відкриється з повною документацією

### Як тестувати API в Swagger UI

1. Знайдіть потрібний endpoint в Swagger UI
2. Натисніть **"Try it out"**
3. Заповніть параметри запиту
4. Натисніть **"Execute"**
5. Перегляньте відповідь та код запиту

> 💡 **Порада:** Swagger UI автоматично додає токен автентифікації з вашої сесії, тому вам не потрібно вручну додавати заголовки автентифікації.

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

Для детальної інформації про всі API endpoints:

1. **Swagger UI в системі** — меню допомоги → API Documentation (`/api-docs`)
2. **Swagger JSON** — `https://engine-{instancename}.kwizbot.io/swagger.json`

## Пов'язані матеріали

- [Як використовувати API](/uk/integrations/how-to/use-api.md) — інструкція з використання API