Довідник методів зовнішнього API

Нижче — усі публічні методи зовнішнього API, згруповані за ресурсами. Це стислий довідник із ключовими параметрами; повні схеми запитів і відповідей завжди актуальні у Swagger.

Якщо метод не позначено окремо, авторизація — заголовок x-api-key з ключем вашої школи (див. «Робота з API» — як його створити).

Спільні параметри списків

Методи GET, що повертають список (users, homeworks, user_reviews, subject_structures), приймають однакові query-параметри:

Параметр	Опис
start, end	пагінація — індекс першого і останнього запису (стандартно 20 записів на сторінку)
sort, order	поле й напрямок сортування
filter	JSON-рядок з фільтром: filter.q — пошук, filter.extraIds — додати конкретні документи, filter.exceptIds — виключити документи
ids	JSON-масив ID, щоб отримати декілька записів одразу

Користувачі (users)

Метод	Ендпоінт	Опис
GET	/external/api/users/	Список користувачів
GET	/external/api/users/raw-items	"Сирі" записи користувачів (без обробки)
GET	/external/api/users/{id}	Один користувач за ID
GET	/external/api/users/{id}/progress	Прогрес користувача
POST	/external/api/users/	Створити користувача
POST	/external/api/users/upsert	Створити користувача або оновити наявного за email
POST	/external/api/users/create-with-orders	Створити користувача одразу із замовленнями (offerIds)
POST	/external/api/users/bulk-provide-offers	Масово надати оффери (offerIds) списку користувачів (userIds)
PUT	/external/api/users/{id}	Оновити одного користувача
PUT	/external/api/users/bulk-update	Масово оновити список користувачів (userIds + поля, що змінюються)
DELETE	/external/api/users/{id}	Видалити користувача

Ключові поля тіла запиту для створення/оновлення користувача:

• name, email, phone — основні дані (для POST /users/ обов'язкові name і email);

• isActive, isDemoMode — активність акаунту й демо-режим;

• seesAllSubjects, ignoreNotOpenLevels, ignoreStopItems — розширені права перегляду;

• subjects[] — масив доступів до предметів, у кожному: subjectId, groups[], levelPacks[], access.openMode (immediately/exactlyAt), access.closeMode (never/afterSeveralDays/exactlyAt), access.startDate, access.endDate, access.dayCount, userEventsLimit;

• newPassword — новий пароль (мінімум 6 символів), доступно при оновленні;

• noteAboutUser[] — нотатки про користувача (text, createdAt, employeeId, userVisible).

Баланс монет (user_balance)

Метод	Ендпоінт	Опис
PATCH	/external/api/user_balance/	Масове нарахування/списання монет — див. розділ «Масове оновлення балансу монет» на сторінці «Робота з API»

Домашні завдання (homework)

Метод	Ендпоінт	Опис
GET	/external/api/homeworks/	Список домашніх завдань, з додатковими фільтрами по статусу й даті перевірки вчителем
POST	/external/api/ai-media-feedback/{homeworkId}	Прикріпити аудіо-фідбек до домашнього завдання (multipart/form-data, поле file)
POST	/external/api/ai-text-feedback/{homeworkId}	Додати текстовий коментар і/або статус перевірки (text, isApproved)

filter для списку домашніх завдань додатково підтримує: filter.updatedAtByTeacherStart/End (дата перевірки вчителем, формат yyyy-mm-dd), filter.statusHistory.status і filter.statusHistory.updatedAtStart/End.

Методи ai-media-feedback і ai-text-feedback авторизуються заголовком authorization, а не x-api-key.

Події (events)

Метод	Ендпоінт	Опис
POST	/external/api/events/for-many-subjects	Створити подію одразу для декількох предметів

Обов'язкові поля тіла запиту: subjectIds[], name, date, finishDate, description, persons, assignTo (groups/users), registerAllUsers, groups[], users[], online, meetingUrl, notifications[], leader (employee, guest), tags[], ignoreUserLimits, creationWithoutNotice, status. Для платної події — об'єкт paid (price, googleProductId, appleProductId).

Відгуки користувачів (user_reviews)

Метод	Ендпоінт	Опис
GET	/external/api/user_reviews/	Список відгуків користувачів (спільні параметри списків)

Структура предметів (subject_structures)

Метод	Ендпоінт	Опис
GET	/external/api/subject_structures/	Список структур предметів (рівні → теми → уроки) — спільні параметри списків

Уроки (decks)

Метод	Ендпоінт	Опис
PUT	/external/api/decks/{id}/updateTheory	Оновити теорію уроку — тіло запиту: html (HTML-контент теорії)

Генерація вправ (exercises_generate)

Метод	Ендпоінт	Опис
POST	/external/api/exercises_generate/	Згенерувати вправи для уроків за допомогою ШІ
POST	/external/api/exercises_generate/justRefreshTheory	Примусово вивантажити теорію уроків в AI API (без генерації вправ)

Поля запиту генерації: lessons[] (ID уроків), count (1–10 вправ на урок), type — тип вправи (5 — вибрати слова, 7 — домашнє завдання, 8 — знайти пари, 9 — заповнити пропуски, 11 — тест із вибором відповіді), language (мова генерації), additionalInstructions (необов'язкові інструкції для ШІ), forceRefreshTheory (примусово оновити теорію перед генерацією). Для типу 9 обов'язковий об'єкт type9Adjustments.answerType (keyboard/select). Заголовок locale (необов'язково) визначає мову можливих повідомлень про помилки.

Місії (missions)

Метод	Ендпоінт	Опис
POST	/external/api/copy_missions/	Скопіювати місії з одного предмета в інші

Поля запиту: sourceSubjectId — предмет-джерело, targetSubjectsId[] — предмети-цілі, targetCompanyId і targetCompanyApiKey — щоб скопіювати місії в іншу компанію (за замовчуванням копіювання відбувається в межах поточної школи).

Слова та терміни (words)

Метод	Ендпоінт	Опис
POST	/external/api/images_for_words/	Завантажити PPTX із зображеннями та ідентифікаторами слів (multipart/form-data, поле file)