School API

Единый доступ ко всем данным Авторской Школы Жании Аубакировой: ученики, родители, учителя, классы, расписание и замены — одним запросом, из любого инструмента.

Только чтение. API ничего не меняет и не удаляет — базы открыты в режиме read-only на уровне подключения. Любой запрос безопасен: сломать данные через него нельзя.

Как начать Ученики Родители Учителя Классы Расписание Поиск и сводка Выгрузка в Excel Готовые рецепты Про данные

Как начать

К каждому запросу нужен ключ. Передавайте его заголовком X-API-Key — либо, если так удобнее, параметром ?api_key= прямо в адресе.

curl -H "X-API-Key: ВАШ_КЛЮЧ" https://api.a-school.space/v1/stats

Проверить, что сервис жив (ключ не нужен):

curl https://api.a-school.space/health

Список всех доступных адресов приходит по GET /v1.

Общие правила

Что	Как
`limit`, `offset`	Постранично. По умолчанию 100 записей, максимум 1000.
`q`	Поиск по ФИО, ИИН и телефону. Понимает казахские буквы: «Дінмұхаммед» найдётся и по «Динмухаммед».
`include`	Догрузить чувствительные блоки: `contract`, `passport`, `grades` или `all`.
Телефоны	Принимаются в любом виде (`+7 705…`, `8705…`), возвращаются как `77XXXXXXXXX`.
Ответ	Всегда JSON: `{ total, limit, offset, count, data }`. Пустые поля не приходят вовсе.

Кириллица в адресе. Класс «5Б» в URL нужно кодировать. В curl проще так: curl --get --data-urlencode "klass=5Б" … — вручную кодировать не придётся.

Ученики

GET/v1/students

Список учеников с фильтрами.

Параметр	Значение
`klass`	Класс с литерой: `5Б`
`class` / `letter`	Отдельно номер и литера: `5`, `Б`
`decision`	`stay` · `thinking` · `leaving`
`signed`	`true` — договор подписан, `false` — нет
`cycle`	`БМЦ` · `ОМЦ` · `СМЦ`
`curator`	Часть фамилии классного руководителя

GET/v1/students/:iin

Полная карточка: договор, паспорт родителя, оценки, братья и сёстры. Здесь всё отдаётся сразу, без include.

GET/v1/students/:iin/schedule

Расписание ученика на неделю — через его класс.

Дата рождения, возраст и пол не хранятся в базе — они вычисляются из ИИН и приходят готовыми.

Родители

GET/v1/parents

Семьи. Фильтры: q, decision, has_iin, min_children.

GET/v1/parents/:phone

Карточка семьи по телефону — со всеми детьми, их классами и суммами.

curl -H "X-API-Key: КЛЮЧ" \
  https://api.a-school.space/v1/parents/77011110422

Семья определяется по платёжному телефону: один номер — одна семья, к ней привязаны все дети.

Учителя

GET/v1/teachers

Педсостав с предметами, классами, нагрузкой и кураторством.

Параметр	Значение
`subject`	Предмет: `математика`, `физика`
`class`	Ведёт в этом классе: `7Б`
`curator_only`	`true` — только классные руководители
`has_phone`	`true` / `false`

GET/v1/teachers/:id

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

Телефоны учителей. Подтверждены у 37 из 173 — остальные в источнике просто не проставлены. Если номер помечен phone_ambiguous: true, он привязан сразу к двум людям и его стоит проверить вручную перед звонком.

Классы

GET/v1/classes

Все 39 классов: сколько учеников, кто классный руководитель, разбивка по решениям.

GET/v1/classes/:klass

Состав класса с родителями и телефонами.

GET/v1/staff

Сотрудники школы вне педсостава: юрист, РОП и другие.

GET/v1/phonebook/:phone

Определить незнакомый номер: родитель, учитель, сотрудник или контакт из общей книги.

Расписание и замены

GET/v1/schedule

Базовая неделя. Фильтры: class, teacher_id, day (0 = понедельник), subject.

GET/v1/schedule/class/:klass

Расписание класса, уже разложенное по дням недели.

GET/v1/schedule/periods

Сетка звонков — начало и конец каждого урока.

GET/v1/substitutions

Замены. Фильтры: date, date_from, date_to, class, teacher_id, status.

GET/v1/absences

Отсутствия учителей. С date покажет тех, кто отсутствует именно в этот день.

GET/v1/attendance

Посещаемость учеников по датам и классам.

Расписание — базовое. /v1/schedule показывает обычную неделю без учёта замен. Чтобы узнать, как прошёл конкретный день, смотрите /v1/substitutions?date=… — там правки на дату.

Поиск и сводка

GET/v1/search?q=…

Ищет разом среди учеников, родителей, учителей и сотрудников. Принимает ФИО, ИИН или телефон.

curl -H "X-API-Key: КЛЮЧ" --get \
  --data-urlencode "q=Абсаметов" \
  https://api.a-school.space/v1/search

GET/v1/stats

Вся школа одним запросом: сколько учеников, решения, подписанные договоры, циклы, финансы, педсостав.

Выгрузка в Excel

Если данные нужны не программе, а человеку — есть готовые CSV. Файл открывается двойным кликом в Excel или Numbers: кириллица и столбцы уже настроены.

GET/v1/export/students.csv

Все ученики: класс, дата рождения, руководитель, решение, договор, родитель, телефон, суммы. Принимает те же фильтры, что и /v1/students.

GET/v1/export/teachers.csv

Педсостав с предметами, классами и нагрузкой.

GET/v1/export/parents.csv

Родители с детьми и ежемесячными суммами.

GET/v1/export/class/:klass.csv

Готовый список класса для классного руководителя — с нумерацией.

Скачать список 7Б себе на компьютер:

curl -H "X-API-Key: КЛЮЧ" -O -J \
  "https://api.a-school.space/v1/export/class/7Б.csv"

Скачать всех, кто ещё не подписал договор:

curl -H "X-API-Key: КЛЮЧ" -o недоговоры.csv \
  "https://api.a-school.space/v1/export/students.csv?signed=false"

Готовые рецепты

Кто ещё не подписал договор

curl -H "X-API-Key: КЛЮЧ" \
  "https://api.a-school.space/v1/students?signed=false&limit=1000"

Все, кто собирается уходить

curl -H "X-API-Key: КЛЮЧ" \
  "https://api.a-school.space/v1/students?decision=leaving"

Список класса с телефонами родителей

curl -H "X-API-Key: КЛЮЧ" --get \
  --data-urlencode "klass=7Б" \
  https://api.a-school.space/v1/classes/7Б

Кто ведёт математику

curl -H "X-API-Key: КЛЮЧ" --get \
  --data-urlencode "subject=математика" \
  https://api.a-school.space/v1/teachers

Замены на сегодня

curl -H "X-API-Key: КЛЮЧ" \
  "https://api.a-school.space/v1/substitutions?date=2026-07-27"

Выгрузить в таблицу (Python)

import requests, csv

r = requests.get(
    "https://api.a-school.space/v1/students",
    headers={"X-API-Key": "КЛЮЧ"},
    params={"limit": 1000, "include": "contract"},
)
students = r.json()["data"]

with open("ученики.csv", "w", newline="", encoding="utf-8-sig") as f:
    w = csv.writer(f)
    w.writerow(["ИИН", "ФИО", "Класс", "Куратор", "Решение", "Родитель", "Телефон"])
    for s in students:
        p = s.get("parent", {})
        w.writerow([
            s["iin"], s.get("name"), s.get("klass"), s.get("curator"),
            s.get("decision"), p.get("name"), p.get("phone"),
        ])

print(f"Готово: {len(students)} учеников")

Про данные

Откуда что берётся

Данные	Источник	Обновление
Ученики, родители, договоры	school.sqlite	каждую ночь в 04:00
Решения «остаётся / уходит»	opros.sqlite	раз в час
Учителя, расписание, замены	schedule.sqlite	при импорте из EduPage
Сотрудники	overrides.sqlite	вручную
Телефонная книга	phonebook.sqlite	синхронизация

Что стоит знать

Момент	Пояснение
Класс	Указан за текущий 2025/26 учебный год. На 2026/27 каждый ребёнок переходит на класс выше, а 11-й выпускается.
Решение родителя	Итоговое: сводит форму опроса, воронку CRM и отметки менеджеров.
ИИН родителей	Есть у 144 семей из 466 — остальные просто не собраны.
Даты рождения	Вычисляются из ИИН. Если ИИН нестандартный, приходит пусто, а не выдуманная дата.
ФИО учителей	В источнике порядок «Имя Отчество Фамилия», часть заглавными. API приводит к «Фамилия Имя Отчество».

Если что-то пошло не так

Код	Что значит
`401`	Ключ не передан
`403`	Ключ неверный
`404`	Запись не найдена или адрес не существует
`429`	Много неудачных попыток — подождите 10 минут
`503`	База временно недоступна, смотрите `/health`