API розкладу ЛКЛАУД: підключення та приклади використання

API розкладу ЛКЛАУД дає змогу отримувати актуальні дані про навчальні групи, викладачів і заняття у форматі JSON. Його можна використати для офіційного сайту закладу освіти, мобільного застосунку, інформаційного табло, чат-бота або внутрішньої інформаційної системи.

Що можна отримувати через API

Крок 1. Увімкніть API у ЛКЛАУД

1. Увійдіть у хмару з правами адміністратора.
2. Відкрийте розділ Розклад → Налаштування.
3. Знайдіть блок API розкладу.
4. Увімкніть потрібний режим доступу:
   • Відкритий доступ — для перегляду груп, викладачів та основного розкладу без авторизації;
   • Доступ за token — для захищених запитів та інтеграцій, яким не слід надавати відкритий доступ.
5. Якщо потрібен захищений доступ, згенеруйте token та одразу збережіть його у безпечному місці. Повторно значення token не відображається.

Крок 2. Визначте базову адресу

Базова адреса API формується з адреси вашої хмари:

https://АДРЕСА-ХМАРИ/rozklad/api?version=v1

Наприклад, для хмари college.lcloud.in.ua адреса матиме вигляд:

https://college.lcloud.in.ua/rozklad/api?version=v1

Перевірити, чи API працює, та отримати його актуальний машинозчитуваний опис можна запитом:

https://college.lcloud.in.ua/rozklad/api?version=v1&resource=help

У власних запитах замініть college.lcloud.in.ua на домен вашої хмари.

Крок 3. Отримайте ідентифікатор групи або викладача

Для запиту розкладу потрібно передати ідентифікатор групи gid, викладача tid або обидва значення одночасно.

Список груп

curl "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=groups"

Скорочений приклад відповіді:

{
  "st": true,
  "data": {
    "items": [
      {
        "id": 12,
        "name": "КН-21",
        "short_name": "КН-21",
        "course": 2,
        "year_teach": 2026,
        "department_id": 3
      }
    ]
  }
}

Список викладачів

curl "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=teachers"

{
  "st": true,
  "data": {
    "items": [
      {
        "id": 34,
        "name": "Іван Петренко"
      }
    ]
  }
}

У наступних запитах значення поля id використовується як gid для групи або tid для викладача.

Крок 4. Отримайте розклад

Розклад групи

curl "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=schedule&gid=12&from=2026-09-01&to=2026-09-07"

Розклад викладача

curl "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=schedule&tid=34&from=2026-09-01&to=2026-09-07"

Заняття конкретного викладача у конкретній групі

curl "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=schedule&gid=12&tid=34&from=2026-09-01&to=2026-09-07"

Якщо передати одночасно gid і tid, API поверне лише заняття, що відповідають обом умовам.

Кожен запис розкладу може містити:

• id — ідентифікатор заняття;
• date — дату;
• lesson_number і lesson_name — номер та назву пари;
• start_time — час початку;
• дані групи, підгрупи, предмета, викладача й аудиторії.

Параметри запиту

Підключення із token

Рекомендований спосіб авторизації — заголовок X-API-Key:

curl -H "X-API-Key: ВАШ_TOKEN" \
  "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=teachers"

Також підтримується стандартний заголовок Authorization: Bearer:

curl -H "Authorization: Bearer ВАШ_TOKEN" \
  "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=teachers"

Для тестової бази додайте source=test. Цей режим працює лише за token і лише тоді, коли адміністратор окремо дозволив доступ до тестової бази:

curl -H "X-API-Key: ВАШ_TOKEN" \
  "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=schedule&gid=12&from=2026-09-01&to=2026-09-07&source=test"

Приклади підключення у програмному коді

JavaScript

Цей приклад підходить для відкритого API на тому самому домені. Секретний token у браузерний JavaScript додавати не можна.

const params = new URLSearchParams({
  version: 'v1',
  resource: 'schedule',
  gid: '12',
  from: '2026-09-01',
  to: '2026-09-07'
});

fetch(`/rozklad/api?${params}`)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return response.json();
  })
  .then(result => {
    if (!result.st) {
      throw new Error(result.error?.message || 'Помилка API');
    }
    console.log(result.data.items);
  })
  .catch(error => console.error(error));

PHP

<?php
$url = 'https://college.lcloud.in.ua/rozklad/api?' . http_build_query([
    'version'  => 'v1',
    'resource' => 'schedule',
    'tid'      => 34,
    'from'     => '2026-09-01',
    'to'       => '2026-09-07',
]);

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'Accept: application/json',
        'X-API-Key: ' . getenv('LCLOUD_SCHEDULE_API_TOKEN'),
    ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

curl_close($curl);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

if ($status !== 200 || empty($result['st'])) {
    $message = $result['error']['message'] ?? 'Помилка API';
    throw new RuntimeException($message);
}

foreach ($result['data']['items'] as $lesson) {
    echo $lesson['date'] . ' — ' . $lesson['subject_name'] . PHP_EOL;
}

Python

import os
import requests

url = "https://college.lcloud.in.ua/rozklad/api"
params = {
    "version": "v1",
    "resource": "schedule",
    "gid": 12,
    "from": "2026-09-01",
    "to": "2026-09-07",
}
headers = {
    "Accept": "application/json",
    "X-API-Key": os.environ["LCLOUD_SCHEDULE_API_TOKEN"],
}

response = requests.get(url, params=params, headers=headers, timeout=15)
response.raise_for_status()
result = response.json()

if not result.get("st"):
    raise RuntimeError(result.get("error", {}).get("message", "Помилка API"))

for lesson in result["data"]["items"]:
    print(lesson["date"], lesson["subject_name"])

Підключення API розкладу до ШІ

API можна використовувати як джерело актуальних даних для ШІ-помічника, чат-бота або внутрішнього агента закладу освіти. Користувач ставить запитання звичайною мовою, наприклад «Покажи розклад Стадніка на сьогодні», а ШІ визначає потрібного викладача, формує запит до API та повертає зрозумілу відповідь.

Як працює ШІ-помічник

1. Отримує актуальний опис API через resource=help.
2. Розпізнає в запиті користувача викладача або навчальну групу та потрібний період.
3. Звертається до teachers або groups, щоб знайти правильний ідентифікатор.
4. Формує запит до schedule із параметрами tid або gid, from і to.
5. Перевіряє відповідь API та подає знайдені заняття у зручному для користувача вигляді.

Наприклад, запит «Які пари має викладач Іван Петренко 8 вересня 2026 року?» може бути опрацьований так:

1. GET /rozklad/api?version=v1&resource=teachers
2. Знайти викладача «Іван Петренко» та отримати tid=34
3. GET /rozklad/api?version=v1&resource=schedule&tid=34&from=2026-09-08&to=2026-09-08
4. Сформувати коротку відповідь зі списком занять

Базова інструкція для ШІ

До системної інструкції ШІ-помічника можна додати такий текст:

Ти — помічник із розкладу закладу освіти.
Використовуй тільки дані API розкладу ЛКЛАУД і не вигадуй заняття.

Перед першим запитом ознайомся з контрактом:
https://college.lcloud.in.ua/rozklad/api?version=v1&resource=help

Правила роботи:
1. Для пошуку викладача спочатку отримай resource=teachers.
2. Для пошуку групи спочатку отримай resource=groups.
3. Якщо знайдено декілька схожих результатів, попроси користувача уточнити вибір.
4. Передавай дати тільки у форматі YYYY-MM-DD.
5. Для розкладу використовуй resource=schedule та gid або tid.
6. Якщо data.items порожній, повідом, що занять за заданими умовами немає.
7. Якщо API повернуло помилку, поясни її користувачу та не створюй відповідь із припущень.
8. Виводь дату, номер і час пари, групу, предмет, викладача та аудиторію, якщо ці дані наявні.

Замініть college.lcloud.in.ua у цій інструкції на адресу потрібної хмари.

Рекомендована схема захищеного підключення

Якщо ШІ має працювати з token, навантаженням, вичиткою або операціями редагування, запити потрібно виконувати через серверний модуль інтеграції:

1. ШІ передає серверному модулю назву дозволеної операції та її параметри.
2. Сервер перевіряє параметри, додає заголовок X-API-Key і звертається до ЛКЛАУД.
3. ЛКЛАУД повертає JSON, а сервер передає ШІ лише результат без секретного token.
4. ШІ формує відповідь для користувача.

Безпечне редагування розкладу через ШІ

API підтримує захищені операції оновлення та видалення занять, але для ШІ їх варто вмикати лише за наявності додаткового контролю:

• обмежте доступ користувачами з відповідними повноваженнями;
• перед виконанням покажіть, яке саме заняття і як буде змінено;
• вимагайте явного підтвердження користувача;
• для перевірки інтеграції спочатку використовуйте source=test;
• записуйте результат операції до журналу без збереження token;
• не дозволяйте ШІ самостійно розширювати перелік доступних методів.

Для помічника, який лише відповідає на запитання про розклад, достатньо надати доступ до help, teachers, groups і schedule. Це мінімізує ризики та водночас дає змогу відповідати на більшість типових запитів студентів і викладачів.

Захищені ресурси: навантаження та вичитка

Педагогічне навантаження

Для ресурсу load потрібно передати хоча б один фільтр: навчальний рік навантаження lid, групу gid або викладача tid. Додатково можна вказати семестр.

curl -H "X-API-Key: ВАШ_TOKEN" \
  "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=load&tid=34&semester=1"

У відповіді повертаються підсумки planned_hours, scheduled_hours і remaining_hours, а також деталізація за предметами, групами та видами занять.

Вичитка

curl -H "X-API-Key: ВАШ_TOKEN" \
  "https://college.lcloud.in.ua/rozklad/api?version=v1&resource=proofreading&teacher_id=34&from=2026-09-01&to=2026-09-30"

Для вичитки потрібно передати gid або tid. Максимальний період одного запиту — 93 дні. Відповідь містить кількість занять, суму годин та ознаку заміни викладача.

Формат відповіді та обробка помилок

Успішна відповідь має поле st: true, а корисні дані розміщуються у data:

{
  "st": true,
  "data": {
    "items": []
  }
}

У разі помилки API повертає st: false, HTTP-статус і структурований опис:

{
  "st": false,
  "error": {
    "code": "missing_filter",
    "message": "Вкажіть gid або tid"
  }
}

Під час інтеграції перевіряйте одночасно HTTP-статус, поле st і, за потреби, error.code. Порожній масив data.items не є помилкою: він означає, що об’єкт існує, але за заданими умовами записів немає.

Важливі обмеження

• дати потрібно передавати у форматі YYYY-MM-DD;
• дата from не може бути пізнішою за to;
• для schedule обов’язковий gid або tid;
• період запиту розкладу — не більше 31 дня, вичитки — не більше 93 днів;
• для schedule, load і proofreading повертається не більше 5000 записів;
• параметри сторінок page та offset не підтримуються;
• час занять повертається у локальному часовому поясі сайту без автоматичного перетворення в UTC;
• доступ до даних залежить від налаштувань API та обмежень, установлених у хмарі.

Рекомендації з безпеки

• зберігайте token у змінній середовища або сховищі секретів;
• використовуйте тільки HTTPS;
• не записуйте token у журнали застосунку;
• для звичайного відображення розкладу надавайте інтеграції лише доступ на читання;
• операції зміни й видалення розкладу виконуйте тільки із серверної частини та після додаткової перевірки даних;
• якщо token став відомий стороннім особам, одразу згенеруйте новий.