Без лишней теории: выберите сценарий входа, получите токен и сделайте первый запрос. Ниже — рабочие примеры, карта данных школы и ответы на частые вопросы.
От этого зависит только способ получения токена и вид адресов.
Человек входит на стороне АИС «Школа», подтверждает доступ, а приложение получает токен его школы. Пароль пользователя не попадает во внешний сервис.
/api/v1/school/...Планировщик или backend получает токен по реквизитам программы. Школа указывается в адресе, а API проверяет выданные программе права на эту школу.
/api/v1/schools/{id}/...Для первого теста проще всего использовать серверный токен.
Напишите на director@ais-school.ru и опишите вашу интеграцию.
Передайте client_id и client_secret только с вашего сервера.
Добавьте заголовок Authorization: Bearer ... к запросу.
curl -X POST "https://ais-school.ru/api/v1/auth/token/" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "ais_...",
"client_secret": "YOUR_CLIENT_SECRET"
}'curl "https://ais-school.ru/api/v1/schools/10/" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"https://ais-school.ru/api/v1/ — официальный адрес API, 10 — ID школы, а ais_... и секрет выдаются после согласования доступа.
Подходит для кабинета, мобильного приложения или другого сервиса, где человек работает со своей школой.
Создайте случайные state и code_verifier.
Из verifier вычислите SHA-256 в формате Base64URL без = —
получится code_challenge. Сохраните state и verifier
в серверной сессии до возврата пользователя.
https://ais-school.ru/api/v1/auth/authorize/
?client_id=ais_...
&redirect_uri=https%3A%2F%2Fclient.example%2Fcallback
&response_type=code
&scope=school.read
&state=RANDOM_STATE
&code_challenge=CHALLENGE
&code_challenge_method=S256
redirect_uri должен полностью совпадать с адресом,
согласованным при подключении. После входа АИС «Школа» вернёт браузер
на этот адрес с параметрами code и state.
Если state не совпал со значением из сессии, остановите вход. Одноразовый code действует 5 минут и используется только один раз.
curl -X POST "https://ais-school.ru/api/v1/auth/token/" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"client_id": "ais_...",
"redirect_uri": "https://client.example/callback",
"code": "ONE_TIME_CODE",
"code_verifier": "ORIGINAL_RANDOM_VERIFIER"
}'Передавать username и password в /auth/token/ нельзя. Для пользовательского входа всегда используйте страницу авторизации.
Client Credentials работает без пользователя и только в границах грантов программы.
/api/v1/auth/me/Проверить программу, пользователя и срок токена
/api/v1/auth/profile/Получить профиль пользователя; для серверного токена вернётся 404
/api/v1/auth/revoke/Немедленно отозвать текущий токен
Не помещайте client_secret в браузерный JavaScript, мобильное приложение, публичный репозиторий или логи.
В пользовательском сценарии школа определяется по профилю. В серверном — указывается явно.
| Операция | OAuth пользователя | Серверный токен |
|---|---|---|
| Карточка школы | /school/ | /schools/{school_id}/ |
| Полный снимок | /school/all/ | /schools/{school_id}/all/ |
| Каталог ресурсов | /school/resources/ | /schools/{school_id}/resources/ |
| Один ресурс | /school/resources/{resource}/ | /schools/{school_id}/resources/{resource}/ |
Реквизиты, адреса, контакты, лицензия, аккредитация, тариф и текущий учебный год.
Школа и весь связанный граф данных. Удобен для первого импорта, но ответ может быть большим.
Отдельные списки с фильтрами — лучший вариант для регулярной синхронизации.
Название справа — значение {resource} в адресе запроса.
academicyearsubjectsgroupsbuildingroomtypesmarkperiodschemeperiodschemeitemperioduserstudentsparentlinkagentworkloadcallscheduletemplatecallscheduleentryscheduletemplatescheduletemplateinfoscheduletypemarkmarkstotalmarksyearfinalmarkktptemplatektptemplateitemktptemplategroupcurriculumplancurriculumitemdebtretakeattendancehomeworkhomeworktargethomeworkattachmentschooldocumentsupportticketsupportmessagesupportattachmentstudentimportjoblogskugschedulestaymodeliterequestslitereportselectionpaymentНичего не найдено. Попробуйте название по-русски или имя ресурса из API.
Запросите GET /api/v1/school/resources/, чтобы увидеть ресурсы, доступные в установленной версии АИС «Школа».
Подставьте имя ресурса и, для одной записи, её ID.
/resources/{resource}/Возвращает count, применённые filters и массив results.
/resources/{resource}/{id}/Возвращает объект или 404, если запись не принадлежит школе.
/resources/{resource}/Требует can_write. Поле школы сервер подставляет сам.
/resources/{resource}/{id}/Передавайте только поля, которые действительно меняются.
/resources/{resource}/{id}/Требует can_write; учитывайте зависимые записи.
id, не как вложенный объект.id при создании не передаётся — его назначит сервер.created_at, updated_at и похожие служебные даты обычно только читаются.PATCH нельзя перенести запись в другую школу.multipart/form-data; JSON-строка не загружает файл.curl -X POST "https://ais-school.ru/api/v1/school/resources/subjects/" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Информатика", "year": 12}'Фильтры добавляются в строку запроса и всегда ограничиваются текущей школой.
?group=5Точное совпадение?id__in=1,2,3Одно из значений, максимум 500?schedule__period=3Один переход по внешней связи?room=nullПустое значение поляcurl "https://ais-school.ru/api/v1/school/resources/schedule/?group=5&subject=4&period=3" \
-H "Authorization: Bearer $TOKEN"Неизвестный или небезопасный фильтр возвращает 400 — API не отдаст весь список из-за опечатки. JSON-поля, длинные цепочки связей и скрытые поля пользователя фильтровать нельзя.
Успешные чтение и изменение возвращают 200, создание — 201, удаление и отзыв токена — 204.
API объясняет причину в JSON: {"detail": "Программе не выдано требуемое право для этой школы."}
Не отправляйте client secret и токены в браузер, URL, аналитику или логи.
Для чтения достаточно can_read; запись включайте только когда она действительно нужна.
При OAuth-входе сравнивайте state до обмена одноразового кода на токен.
Вызовите POST /auth/revoke/ и напишите на director@ais-school.ru, чтобы отключить доступ.
Для регулярной синхронизации используйте ресурсы и фильтры, а не частый полный снимок /all/.
Полная схема полей каждого ресурса, отзывы и дополнительные оговорки собраны в Markdown-спецификации.