Документация Bonch Go API

Быстрый старт

⚠️ Все запросы требуют ключа. Без него ответ — 401 KEY_REQUIRED; открыт только /health, и то в урезанном виде. Проверить, что сервис жив, можно без ключа:

curl https://api.bonchgo.ru/api/v1/health

Всё остальное — с ключом, заголовком Authorization: Bearer <ключ> (или X-API-Key):

curl -H "Authorization: Bearer $BONCHGO_API_KEY" \
"https://api.bonchgo.ru/api/v1/groups?search=ИКТМ&limit=10"

На Go:

var client = &http.Client{Timeout: 10 * time.Second}

// Имя группы кириллическое, а номер аудитории бывает со слэшем («507/2») —
// поэтому сегмент пути всегда экранируем.
u := "https://api.bonchgo.ru/api/v1/groups/" + url.PathEscape("ИКТМ-41") + "/schedule?semester=current"

req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
if err != nil {
    return nil, err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BONCHGO_API_KEY"))

resp, err := client.Do(req)
if err != nil {
    return nil, err
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
    return nil, fmt.Errorf("bonchgo: %s", resp.Status)
}

var out struct {
    Data []Lesson `json:"data"`
}
err = json.NewDecoder(resp.Body).Decode(&out)
return out.Data, err

Ключ принимается ещё и как ?api_key= в строке запроса — но так его лучше не передавать: строка запроса оседает в логах прокси и в истории браузера, а заголовок — нет.

Эндпоинты

Все методы — GET, все пути — от /api/v1. Имя группы, ФИО и номер аудитории подставляются прямо в путь и должны быть URL-экранированы.

Параметры запроса

Формат ответа

Успех — конверт {data, meta}. Вот настоящий ответ на расписание группы:

{
  "data": [
    {
      "date": "2026-09-03",
      "day_of_week": 4,
      "order": 2,
      "number": 2,
      "number_label": "2",
      "time": "10:45-12:20",
      "subject": "Цифровая обработка сигналов",
      "lesson_type": "Лекция",
      "location": "700; Б22/1",
      "classroom": "700/1",
      "teacher": "Межевов Павел Александрович",
      "source": "regular"
    }
  ],
  "meta": {
    "total": 3,
    "semester": "fall-2026",
    "generated_at": "2026-08-31T12:58:17Z"
  }
}

В meta три поля:

Ошибка — конверт {error}. Настоящий ответ на оборванное имя группы:

{ "error": {
  "code": "GROUP_NOT_FOUND",
  "message": "Группа 'ИКТМ-4' не найдена.",
  "suggestions": ["ИКТМ-41", "ИКТМ-42", "ИКТМ-42м (арх.)", "ИКТМ-43"]
} }

suggestions появляется, только когда похожие имена действительно нашлись, — поле необязательное.

Поля занятия

Одно занятие описывается одним объектом. Набор полей у разных эндпоинтов отличается, и это не случайность: в расписании группы поля группы избыточны — вы её и запрашивали, — а в расписании преподавателя без них нельзя понять, кому он читает.

Тот же лектор, тот же день, но запрошенный через /teachers/{name}/schedule — видно и неделю, и все группы потока:

{
  "data": [
    {
      "date": "2026-09-03",
      "day_of_week": 4,
      "order": 1,
      "number": 1,
      "number_label": "1",
      "time": "09:00-10:35",
      "subject": "Техническая электродинамика",
      "lesson_type": "Лекция",
      "location": "700; Б22/1",
      "classroom": "700/1",
      "teacher": "Межевов Павел Александрович",
      "week_number": 1,
      "week_type": "Нечётная",
      "source": "regular",
      "group_id": "56675",
      "group_name": "ИКТМ-41",
      "groups": ["ИКТМ-41", "ИКТМ-42", "ИКТМ-43"]
    }
  ],
  "meta": { "total": 2, "generated_at": "2026-08-31T12:58:17Z" }
}

Коды ошибок

При каждом запросе с ключом сервис возвращает заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset — по ним видно остаток минутной квоты, не дожидаясь 429.

Ключи и скоуп

У каждого ключа есть срок действия, лимиты запросов в минуту/сутки и опциональный скоуп — список групп, преподавателей или аудиторий, к которым ему разрешено обращаться. Пустой список означает «без ограничения»; непустой — запрос к сущности вне списка получает 403 SCOPE_FORBIDDEN.

Сравнение нормализованное: регистр, дефис, пробелы, точки, «ё»/«е» и адрес аудитории значения не имеют — «ИКТУ-41» и «икту 41» в скоупе совпадут, как и «Иванов И.И.» с «Иванов И. И.».

Доступ по методам

Отдельно от скоупа у ключа есть список разрешённых методов — тех самых путей из раздела «Эндпоинты». Пустой список означает «все методы»; если он задан, всё, что в него не вошло, отвечает 403 ENDPOINT_FORBIDDEN. Ограничение выдаёт администратор при выпуске ключа, а сузить его до меньшего набора можно самому в кабинете.

Это ответ на другой вопрос, чем скоуп: скоуп говорит, про кого можно спрашивать, права на методы — что можно спрашивать. Ключу виджета расписания незачем уметь выкачивать справочник преподавателей, даже если сами данные ему открыты. Совпадение точное: право на /groups (список групп) не открывает /groups/{group}/schedule.

Личный кабинет

Вход в кабинет — только через аккаунт бота Bonch Go: код из Настроек бота обменивается на сессию сайта, отдельных паролей не существует.

Заявка на ключ — не форма на сайте: напишите разработчику лично и договоритесь о задаче и нужном доступе. Ключ выдаётся вручную и сразу появляется в кабинете. ⚠️ Само значение ключа показывается один раз, при выдаче — сохраните его сразу.

В кабинете видно график использования по дням, список IP и топ эндпоинтов. Оттуда же можно сузить доступ, лимиты и срок или отозвать ключ. Расширить права уже выданного ключа из кабинета нельзя — это делает только администратор.