StudyИнструкция
Войти

Справочник методов API

Все методы Enterprise API: адрес, что передавать, что возвращается.

Все адреса начинаются с https://api.1app.kz. В каждом запросе обязателен заголовок X-API-Key с ключом школы. Там, где указано «ключ и токен ученика», дополнительно нужен заголовок Authorization: Bearer cli_… — его выдают методы входа.

Подсказка
Формат ответа одинаковый у всех методов: {"success": true, "data": { … }} при успехе и {"success": false, "error": {"message": "…", "code": "…"}} при ошибке. Ниже описано содержимое data.

Вход ученика

POST /api/enterprise/v2/auth/login

Вход по паролю. Только ключ. Тело: phone, password. Возвращает token (cli_…), expiresAt и client с id, phoneNumber, name. Не чаще 20 запросов в минуту на школу.

POST /api/enterprise/v2/auth/send-otp

Отправить ученику код подтверждения. Только ключ. Тело: phone. Возвращает message и expiresAt. Не чаще 10 запросов в минуту на школу.

POST /api/enterprise/v2/auth/verify

Проверить код и получить токен. Только ключ. Тело: phone, code из 6 цифр, необязательно name для нового ученика. Возвращает token, expiresAt, client. Не чаще 20 запросов в минуту.

curl -X POST "https://api.1app.kz/api/enterprise/v2/auth/login" \
  -H "X-API-Key: ent_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"phone":"77001234567","password":"123456"}'

Ученики

GET /api/enterprise/v2/clients/lookup?phone=77001234567

Проверить, есть ли человек в школе. Только ключ. Возвращает found, userExists и client с id, именем, телефоном, email и датой регистрации, либо found: false.

GET и PATCH /api/enterprise/v2/clients/me

Профиль текущего ученика. Ключ и токен ученика. GET возвращает id, телефон, имя, фамилию, email, дату рождения, язык, аватар, баланс бонусов и уровень. PATCH обновляет эти поля.

PATCH /api/enterprise/v2/clients

Проставить или исправить имя своего ученика по номеру телефона. Только ключ. Тело: phoneNumber, name, необязательно surname. Работает и для приглашённых, которые ещё не вошли. Карточка ученика в вашей школе обновляется всегда; общий профиль — только пока ученик не задал имя сам.

Школа и курсы

GET /api/enterprise/v2/school/tabs

Структура школы для вашего интерфейса. Только ключ. Возвращает school (id, название, логотип, цвет), tabs — вкладки приложения и homePage. Если подписка школы приостановлена, придёт suspended: true и контактный телефон.

GET /api/enterprise/v2/lms/courses

Каталог курсов. Только ключ. Необязательные параметры: search, page, limit. Возвращает courses, total, page, limit.

GET /api/enterprise/v2/lms/courses/{id}

Карточка курса с модулями и уроками. Ключ и токен ученика: состав курса виден тем, у кого есть доступ.

GET /api/enterprise/v2/lms/lessons/{id}

Содержимое урока: блоки текста, видео, файлы. Ключ и токен ученика.

PUT и POST /api/enterprise/v2/lms/lessons/{id}/progress

Отметить прогресс по уроку. Ключ и токен ученика.

POST /api/enterprise/v2/lms/lessons/{id}/ai-chat

Вопрос ИИ-помощнику по материалу урока. Ключ и токен ученика.

Доступ к курсам

POST /api/enterprise/v2/lms/invites

Выдать доступ по номеру телефона, аккаунт при необходимости создаётся сам. Только ключ — ученику не нужно входить. Тело: courseId, streamId, phoneNumber, необязательно customPassword, name и surname. Передавайте имя, если оно есть в форме: ученик сразу появится в базе с именем. Возвращает inviteId, enrollmentId, isNewUser, isPending, credentials. Это основной метод для формы на сайте.

GET /api/enterprise/v2/lms/enrollments

Записи на курсы. Если передать параметр phone, достаточно одного ключа школы: так можно проверить прогресс ученика со своего сервера, не входя за него. Без phone нужен ещё токен ученика. Необязательный параметр status: pending, active, completed, expired, cancelled.

POST /api/enterprise/v2/lms/enrollments

Записать на курс уже вошедшего ученика. Ключ и токен ученика. Тело: courseId, необязательно streamId и paymentMethodId.

GET /api/enterprise/v2/lms/enrollments/{id}

Одна запись с прогрессом по курсу. Ключ и токен ученика.

В каждой записи приходят status, progressPercent, lessonsCompleted, totalLessons, lastActivityAt, enrolledAt, completedAt и expiresAt. Результатов тестов там пока нет: их отдаёт только метод попыток, а ему нужен токен ученика.

Задания и тесты

  • GET и POST /api/enterprise/v2/lms/assignments — список заданий и создание. Ключ и токен ученика.
  • GET и PUT /api/enterprise/v2/lms/assignments/{id} — одно задание и его изменение.
  • POST /api/enterprise/v2/lms/assignments/{id}/submit — сдать задание на проверку.
  • GET, POST и PUT /api/enterprise/v2/lms/quizzes/{id}/attempts — попытки прохождения теста: список, начать, завершить.

Челленджи

  • GET /api/enterprise/v2/lms/challenges — список челленджей школы. Только ключ.
  • GET /api/enterprise/v2/lms/challenges/{id} — карточка челленджа. Только ключ.
  • GET /api/enterprise/v2/lms/challenges/for-student — челленджи конкретного ученика. Ключ и токен.
  • GET /api/enterprise/v2/lms/challenges/{id}/progress — прогресс ученика.
  • GET /api/enterprise/v2/lms/challenges/{id}/feed — лента работ участников.
  • POST /api/enterprise/v2/lms/challenges/{id}/submissions — отправить работу.
  • GET и POST …/submissions/{id}/comments — комментарии к работе.
  • POST и DELETE …/submissions/{id}/like — поставить и снять лайк.

Страницы, формы, рейтинг

  • GET /api/enterprise/v2/pages и /pages/{id} — страницы школы и их содержимое. Ключ и токен ученика.
  • GET и POST /api/enterprise/v2/pages/{id}/comments, POST …/comments/{id}/like — комментарии к странице.
  • GET, POST и DELETE /api/enterprise/v2/pages/{id}/reactions — реакции.
  • GET /api/enterprise/v2/lms/forms/{id} — описание формы.
  • GET, POST и PUT /api/enterprise/v2/lms/forms/{id}/submissions — ответы на форму.
  • GET /api/enterprise/v2/lms/leaderboard — рейтинг учеников.

Уведомления

  • GET, PATCH и DELETE /api/enterprise/v2/notifications — список уведомлений ученика, отметить прочитанными, удалить.
  • POST и DELETE /api/enterprise/v2/notifications/push-token — зарегистрировать и отключить push-токен устройства.

Данные школы

GET и PATCH /api/enterprise/me — реквизиты вашей школы и их изменение. Только ключ.

Совет
Если нужного метода в списке нет, напишите в поддержку: часть задач закрывается имеющимися методами, а недостающее мы добавляем.