IT CITY CRM — API Documentation

Як отримати

Налаштування → API ключі → Створити ключ (тільки ADMIN)

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

GET /api/tickets
Authorization: Bearer itc_a1b2c3d4e5f6789...
Content-Type: application/json

Параметри ключа

API ендпоінти для управління ключами

⚠️ Ключ показується тільки при створенні. Зберігається як SHA-256 хеш.

Тіло запиту

{
  "name": "Іван Петренко",
  "email": "ivan@example.com",
  "password": "securePassword123",
  "role": "TECH"
}

Параметри

Відповідь (201)

{
  "id": "clx1abc...",
  "name": "Іван Петренко",
  "email": "ivan@example.com",
  "role": "TECH"
}

Тіло запиту

{
  "email": "ivan@example.com"
}

Відповідь (200)

{
  "message": "Якщо email існує, лист з інструкціями відправлено"
}

Тіло запиту

{
  "token": "reset-token-from-email",
  "password": "newSecurePassword456"
}

Відповідь (200)

{
  "message": "Пароль успішно змінено"
}

Query-параметри

Відповідь (200)

{
  "tickets": [
    {
      "id": "clx1abc...",
      "number": 1042,
      "title": "Не працює принтер",
      "status": "NEW",
      "store": { "id": "...", "name": "Магазин #5" },
      "assignee": { "id": "...", "name": "Олег Коваль" },
      "createdAt": "2026-03-28T10:00:00.000Z"
    }
  ],
  "total": 156,
  "page": 1,
  "totalPages": 16
}

Тіло запиту

{
  "title": "Заміна картриджа",
  "description": "Потрібно замінити картридж у принтері HP LaserJet",
  "storeId": "clx1store...",
  "assigneeId": "clx1user...",
  "priority": "HIGH",
  "categoryId": "clx1cat...",
  "scheduledAt": "2026-04-05T10:00:00.000Z",
  "scheduledEndAt": "2026-04-05T12:00:00.000Z",
  "isPlanned": true
}

Відповідь (201)

{
  "id": "clx1new...",
  "number": 1043,
  "title": "Заміна картриджа",
  "status": "NEW",
  "createdAt": "2026-03-28T12:00:00.000Z"
}

Тіло запиту

{
  "status": "COMPLETED",
  "completionNote": "Картридж замінено",
  "gpsLat": 49.5535,
  "gpsLng": 25.5948
}

Тіло запиту

{
  "action": "assign",
  "ticketIds": ["clx1a...", "clx1b...", "clx1c..."],
  "assigneeId": "clx1user..."
}

// Або зміна статусу:
{
  "action": "status",
  "ticketIds": ["clx1a...", "clx1b..."],
  "status": "COMPLETED"
}

// Або видалення:
{
  "action": "delete",
  "ticketIds": ["clx1a...", "clx1b..."]
}

Відповідь (200)

{
  "updated": 3,
  "message": "Успішно оновлено 3 заявки"
}

GET — Список обладнання прив'язаного до заявки

GET /api/tickets/clx1abc.../equipment

POST — Прив'язати обладнання до заявки

{
  "equipmentId": "clx1eq...",
  "action": "install"
}

Відповідь (200)

[
  {
    "id": "clx1eq...",
    "name": "HP LaserJet Pro",
    "serialNumber": "VNB3K12345",
    "type": "PRINTER"
  }
]

POST — Завантаження фото (multipart/form-data)

Content-Type: multipart/form-data

photo: [binary file]
description: "Фото пошкодженого принтера"

Відповідь (201)

{
  "id": "clx1ph...",
  "url": "/uploads/tickets/clx1abc.../photo1.jpg",
  "description": "Фото пошкодженого принтера",
  "createdAt": "2026-03-28T12:30:00.000Z"
}

POST — Додавання коментаря

Підтримує application/json та multipart/form-data (з файлами).

{
  "text": "Замовив новий картридж, доставка завтра"
}

DELETE /api/tickets/[id]/comments/[commentId] — Видалення коментаря

Автор може видалити свій коментар, ADMIN — будь-який. Створює запис в журналі змін заявки.

PATCH /api/tickets/[id]/comments/[commentId] — Редагування коментаря

Тільки автор, зберігає попередні версії в editHistory.

Відповідь (201)

{
  "id": 42,
  "text": "Замовив новий картридж, доставка завтра",
  "author": { "id": 1, "name": "Олег Коваль" },
  "files": [],
  "createdAt": "2026-03-28T13:00:00.000Z"
}

Опис

Повертає файл у форматі iCalendar (.ics) з подією VEVENT для запланованого виїзду. Файл містить нагадування VALARM за 1 день до події. Сумісний з Google Calendar, Apple Calendar та Outlook.

Відповідь (200)

Content-Type: text/calendar

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//IT CITY CRM//Tickets//UK
BEGIN:VEVENT
UID:ticket-clx1abc@crm.its.te.ua
DTSTART:20260405T100000Z
DTEND:20260405T120000Z
SUMMARY:Заявка #1043 — Заміна картриджа
DESCRIPTION:Магазин #5\nПріоритет: HIGH\nhttps://crm.its.te.ua/tickets/clx1abc
LOCATION:вул. Центральна, 15
BEGIN:VALARM
TRIGGER:-P1D
ACTION:DISPLAY
DESCRIPTION:Нагадування: завтра плановий виїзд — Заявка #1043
END:VALARM
END:VEVENT
END:VCALENDAR

Query-параметри

Відповідь (200)

{
  "equipment": [
    {
      "id": "clx1eq...",
      "name": "HP LaserJet Pro M404dn",
      "type": "PRINTER",
      "serialNumber": "VNB3K12345",
      "status": "ACTIVE",
      "store": { "id": "...", "name": "Магазин #5" }
    }
  ],
  "total": 84,
  "page": 1
}

Тіло запиту

{
  "name": "HP LaserJet Pro M404dn",
  "type": "PRINTER",
  "serialNumber": "VNB3K12345",
  "storeId": "clx1store...",
  "notes": "Нове обладнання, гарантія до 2027"
}

Відповідь (201)

{
  "id": "clx1new...",
  "name": "HP LaserJet Pro M404dn",
  "type": "PRINTER",
  "serialNumber": "VNB3K12345",
  "status": "ACTIVE"
}

Тіло запиту

{
  "name": "HP LaserJet Pro M404dn (оновлено)",
  "serialNumber": "VNB3K12345-NEW",
  "status": "REPAIR",
  "notes": "Відправлено на ремонт"
}

Тіло запиту

{
  "toStoreId": "clx1store2...",
  "reason": "Переміщення на іншу точку за запитом клієнта"
}

Відповідь (200)

{
  "id": "clx1eq...",
  "store": { "id": "clx1store2...", "name": "Магазин #12" },
  "movement": {
    "id": "clx1mv...",
    "fromStore": "Магазин #5",
    "toStore": "Магазин #12",
    "movedAt": "2026-03-28T14:00:00.000Z",
    "movedBy": "Олег Коваль"
  }
}

GET — Query-параметри

POST — Створення запису

{
  "type": "INCOME",
  "amount": 15000,
  "description": "Оплата за обслуговування - Березень",
  "categoryId": "clx1cat...",
  "date": "2026-03-28",
  "organizationId": "clx1org..."
}

Відповідь (200)

{
  "id": "clx1cf...",
  "type": "INCOME",
  "amount": 15000,
  "tax": 750,
  "netAmount": 14250,
  "description": "Оплата за обслуговування - Березень",
  "date": "2026-03-28T00:00:00.000Z"
}

Query-параметри

Відповідь (200)

{
  "month": {
    "income": 85000,
    "expense": 42000,
    "tax": 4250,
    "profit": 38750
  },
  "quarter": {
    "income": 240000,
    "expense": 118000,
    "tax": 12000,
    "profit": 110000
  }
}

POST — Створення регулярного платежу

{
  "name": "Оренда офісу",
  "amount": 8000,
  "type": "EXPENSE",
  "frequency": "MONTHLY",
  "categoryId": "clx1cat...",
  "dayOfMonth": 5
}

Відповідь (200)

{
  "items": [
    {
      "id": "clx1ri...",
      "name": "Оренда офісу",
      "amount": 8000,
      "type": "EXPENSE",
      "frequency": "MONTHLY",
      "nextDate": "2026-04-05",
      "isActive": true
    }
  ]
}

POST — Закрити або відкрити місяць

{
  "month": 3,
  "year": 2026,
  "action": "close"
}

Відповідь (200)

{
  "month": 3,
  "year": 2026,
  "isClosed": true,
  "closedAt": "2026-04-01T00:00:00.000Z",
  "closedBy": "Адмін"
}

Query-параметри

Відповідь (200)

{
  "month": 3,
  "year": 2026,
  "recurringItems": [
    {
      "id": "clx1ri...",
      "name": "Оренда офісу",
      "amount": 8000,
      "type": "EXPENSE",
      "category": "Оренда"
    }
  ],
  "totals": {
    "income": 85000,
    "expense": 42000,
    "recurringExpense": 18000,
    "recurringIncome": 5000
  }
}

Тіло запиту

{
  "orderedIds": ["clx1cat1...", "clx1cat2...", "clx1cat3..."]
}

Відповідь (200)

{
  "success": true,
  "message": "Порядок категорій оновлено"
}

POST — Створення виплати

{
  "userId": "clx1user...",
  "amount": 25000,
  "type": "SALARY",
  "month": 3,
  "year": 2026,
  "note": "Зарплата за березень"
}

Відповідь (201)

{
  "id": "clx1pay...",
  "userId": "clx1user...",
  "amount": 25000,
  "type": "SALARY",
  "createdAt": "2026-04-01T00:00:00.000Z"
}

POST — Створення категорії

{
  "name": "Витратні матеріали",
  "type": "EXPENSE",
  "parentId": null
}

GET — Відповідь (200)

{
  "categories": [
    {
      "id": "clx1cat...",
      "name": "Витратні матеріали",
      "type": "EXPENSE",
      "parentId": null,
      "children": [
        { "id": "clx1cat2...", "name": "Картриджі" },
        { "id": "clx1cat3...", "name": "Папір" }
      ]
    }
  ]
}

Query-параметри

Відповідь (200)

{
  "tickets": {
    "total": 156,
    "new": 12,
    "inProgress": 28,
    "completed": 110,
    "cancelled": 6
  },
  "technicians": [
    { "name": "Олег Коваль", "completed": 45, "avgTime": "2.3 год" }
  ],
  "finance": {
    "income": 85000,
    "expense": 42000,
    "profit": 43000
  }
}

Query-параметри

Типи звітів

Приклад запиту

GET /api/reports/detailed?from=2026-01-01&to=2026-03-31&type=summary

Відповідь (200)

{
  "period": { "from": "2026-01-01", "to": "2026-03-31" },
  "type": "summary",
  "data": {
    "totalIncome": 240000,
    "totalExpense": 118000,
    "totalTax": 12000,
    "netProfit": 110000,
    "ticketsCompleted": 312,
    "avgTicketTime": "2.1 год"
  }
}

Query-параметри

Ті самі параметри, що й для /api/reports/detailed

Відповідь

Бінарний файл application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Content-Disposition: attachment; filename="report-2026-Q1.xlsx"

Тіло запиту

{
  "type": "monthly",
  "month": 3,
  "year": 2026
}

Відповідь (200)

{
  "success": true,
  "message": "Тестовий звіт відправлено в Telegram"
}

Відповідь (200)

{
  "weeklyReport": {
    "enabled": true,
    "dayOfWeek": 1,
    "time": "09:00",
    "chatIds": ["-100123456789"]
  },
  "monthlyReport": {
    "enabled": true,
    "dayOfMonth": 1,
    "time": "10:00",
    "chatIds": ["-100123456789"]
  }
}

Заголовки

Тіло запиту (від Eddy)

{
  "event": "ticket.created",
  "data": {
    "id": 12345,
    "subject": "Не працює каса",
    "description": "Каса не включається після оновлення",
    "priority": "high",
    "store": {
      "name": "Магазин Електроніка #7",
      "address": "вул. Центральна, 15"
    },
    "contact": {
      "name": "Марія Коваленко",
      "phone": "+380501234567"
    }
  }
}

Маппінг полів Eddy → CRM

Відповідь (200)

{
  "success": true,
  "ticketId": "clx1new...",
  "ticketNumber": 1044
}

Типи сповіщень

Формат повідомлення (приклад)

🔔 Нова заявка #1044

📋 Не працює каса
🏪 Магазин Електроніка #7
⚡ Пріоритет: Високий

🔗 https://crm.its.te.ua/tickets/clx1new...

Опис

Одноразове посилання для закриття заявки зовнішнім підрядником без облікового запису в CRM.

Приклад URL

https://crm.its.te.ua/magic/abc123def456...

Процес

Можливості

Відповідь (403)

{
  "error": "Видалення користувачів заборонено. Використовуйте деактивацію.",
  "hint": "PATCH /api/users/[id] з { \"isActive\": false }"
}

GET — Список тестів

Для техніка: тільки обов'язкові + призначені. Для адміна: всі опубліковані.

POST — Створення тесту (ADMIN)

{
  "title": "Основи мереж",
  "description": "Базові знання мережевих технологій",
  "level": "BEGINNER",
  "category": "networks",
  "passingScore": 80,
  "timeLimitMin": 15,
  "isRequired": false,
  "questions": [
    {
      "text": "Який порт використовує HTTPS?",
      "type": "single",
      "options": ["80", "443", "8080", "22"],
      "correctAnswer": [1],
      "explanation": "HTTPS працює на порті 443"
    }
  ]
}

GET — повертає тест з питаннями (для техніка без правильних відповідей).

PATCH — оновлення тесту та питань (ADMIN). DELETE — видалення (ADMIN).

{
  "answers": {
    "1": [1],
    "2": [0, 2],
    "3": [0]
  }
}

Повертає результат: score, passed, детальний розбір кожного питання з правильними відповідями.

{
  "userIds": [4, 5, 6],
  "deadline": "2026-04-15"
}

Надсилає Telegram та in-app сповіщення кожному призначеному користувачу.

Створює 6 шаблонів: Мережі, Принтери, Windows, Сервери, Безпека, Hardware (54 питання).

Повертає матрицю: користувачі × тести з найкращими балами та кількістю спроб.

GET

Параметр ?unread=1 — тільки непрочитані. Повертає { notifications, unreadCount }.

PATCH — Позначити прочитаним

// Одне сповіщення
{ "id": 42 }
// Все прочитано
{ "markAll": true }

Типи сповіщень

Тіло запиту

{
  "name": "Акція березень",
  "message": "Шановні клієнти! Знижка 20% на обслуговування до кінця місяця.",
  "channel": "telegram",
  "filters": {
    "organizationId": "clx1org...",
    "tags": ["active"]
  }
}

Відповідь (201)

{
  "id": "clx1br...",
  "name": "Акція березень",
  "status": "DRAFT",
  "recipientCount": 45,
  "createdAt": "2026-04-01T10:00:00.000Z"
}

Відповідь (200)

{
  "broadcasts": [
    {
      "id": "clx1br...",
      "name": "Акція березень",
      "status": "SENT",
      "channel": "telegram",
      "recipientCount": 45,
      "sentCount": 42,
      "failedCount": 3,
      "createdAt": "2026-04-01T10:00:00.000Z",
      "sentAt": "2026-04-01T10:05:00.000Z"
    }
  ]
}

Опис

Запускає відправку розсилки всім отримувачам. Статус змінюється на SENDING, потім на SENT після завершення.

Відповідь (200)

{
  "id": "clx1br...",
  "status": "SENDING",
  "recipientCount": 45,
  "message": "Розсилка запущена"
}

Опис

Імпорт даних з CSV-файлу. Підтримує контакти, обладнання та організації. Формат: multipart/form-data.

Тіло запиту (multipart/form-data)

Content-Type: multipart/form-data

file: [CSV file]
type: "contacts"  // contacts | equipment | organizations

Відповідь (200)

{
  "imported": 42,
  "skipped": 3,
  "errors": [
    { "row": 5, "error": "Дублікат email" }
  ]
}

Query-параметри

Відповідь

Бінарний файл text/csv

Content-Disposition: attachment; filename="contacts-2026-04-01.csv"

Відповідь (200)

{
  "templates": [
    {
      "id": "clx1tmpl...",
      "name": "Заміна картриджа",
      "title": "Заміна картриджа — {printer}",
      "description": "Потрібна заміна картриджа",
      "priority": "MEDIUM",
      "categoryId": "clx1cat..."
    }
  ]
}

Тіло запиту

{
  "name": "Заміна картриджа",
  "title": "Заміна картриджа — {printer}",
  "description": "Потрібна заміна картриджа в принтері",
  "priority": "MEDIUM",
  "categoryId": "clx1cat..."
}

Відповідь (201)

{
  "id": "clx1tmpl...",
  "name": "Заміна картриджа",
  "createdAt": "2026-04-01T10:00:00.000Z"
}

Відповідь (200)

{
  "items": [
    {
      "id": "clx1pm...",
      "name": "Щомісячна перевірка принтерів",
      "frequency": "MONTHLY",
      "templateId": "clx1tmpl...",
      "storeId": "clx1store...",
      "nextRunAt": "2026-05-01T09:00:00.000Z",
      "isActive": true
    }
  ]
}

Тіло запиту

{
  "name": "Щомісячна перевірка принтерів",
  "frequency": "MONTHLY",
  "dayOfMonth": 1,
  "templateId": "clx1tmpl...",
  "storeId": "clx1store...",
  "assigneeId": "clx1user..."
}

Відповідь (201)

{
  "id": "clx1pm...",
  "name": "Щомісячна перевірка принтерів",
  "nextRunAt": "2026-05-01T09:00:00.000Z"
}

Тіло запиту

{
  "provider": "liqpay",
  "plan": "professional",
  "period": "monthly"
}

Відповідь (200)

{
  "paymentUrl": "https://www.liqpay.ua/checkout/...",
  "orderId": "ord_abc123"
}

Тіло запиту

{
  "message": "TypeError: Cannot read property 'id' of undefined",
  "stack": "at TicketList.render (tickets.js:42:15)...",
  "url": "/tickets",
  "userAgent": "Mozilla/5.0..."
}

Відповідь (201)

{
  "id": "clx1err...",
  "message": "Помилку зафіксовано"
}

Відповідь (200)

{
  "status": "ok",
  "version": "4.0.0",
  "uptime": 1234567,
  "database": "connected",
  "timestamp": "2026-04-01T12:00:00.000Z"
}

Приймає повідомлення від Telegram Bot API. Обробляє текст, фото, відео, файли, контакт (request_contact), callback_query (рейтинг).

Логіка

Створює/знаходить ChatSession → зберігає повідомлення → ідентифікує клієнта → Zabbix-перевірка → AI-відповідь (якщо немає оператора) → автопризначення → сповіщення.

Приймає повідомлення від Viber Bot. Повна паритетність з Telegram: кнопки (Viber Keyboard), рейтинг, Zabbix, AI.

Query параметри

Відповідь

Масив ChatSession з вкладеними contact, store, operator, останнє повідомлення, _count.messages. Плюс об'єкт counts з кількістю по кожному статусу.

Повна інформація: всі повідомлення з replyTo, контакт (customFields, stores), оператор, канал, рейтинг.

Body параметри

FormData: text, file (attachment), isComment (внутрішній коментар), replyToId (цитування).

Коментарі не надсилаються клієнту. Звичайні повідомлення надсилаються через Telegram/Viber API.

KPI: всього заявок, закрито, середній час відповіді, середній рейтинг. Графіки по статусах, каналах, операторах. Список відгуків з фільтрацією.

Query

Query параметри

Авторизація через x-cron-secret header. Знаходить заявки де останнє повідомлення від клієнта старше SLA, надсилає сповіщення через Telegram та in-app.

Query параметри

Повертає: проблеми (severity: High), inventory роутера (модель, прошивка, S/N), тривалість простою.

Повертає всі статті з title, content, tags, isPublic, slug. Фільтрація по тегах та пошук по заголовку.

Окремий сервер (порт 3099). Список публічних статей з пошуком та фільтрацією по тегах. Без авторизації.

HTML-сторінка статті з повним контентом. Slug генерується транслітерацією з кирилиці.