Справочник API партнёра

Базовый адрес: https://api.rismik.ru/api/partner/v1 (старый https://api.whiteboard.quest-practices.ru/api/partner/v1 продолжает работать для уже подключённых платформ). Ключ: заголовок Authorization: Bearer wbk_…. Тело запросов и ответов — JSON (UTF-8). Ограничение: 600 запросов в минуту на ключ.

Ошибки

{"detail": {"code": "not_found", "message": "Урок не найден"}}

Уроки

POST /lessons → 201

Ответ — урок:

{
  "id": "6f1c…", "external_id": "course-7/lesson-3", "title": "Дроби, 5 класс", "mode": "full",
  "created_at": "2026-10-14T09:00:00Z", "started_at": null, "ended_at": null,
  "billed_seconds": 0, "archived": false
}

started_at и ended_at описывают последнее занятие на этой доске. Доску можно использовать повторно: следующее занятие снова будет lesson.started. billed_seconds — всё время урока с момента создания.

GET /lessons/{id}, GET /lessons?external_id=…

Возвращают урок или список (пустой, если ничего не найдено).

DELETE /lessons/{id} → 204

Урок уходит в архив: ссылки на него перестают открываться, и новые ссылки не выдаются.

Ссылки участников

POST /lessons/{id}/links

{"user": {"id": "42", "name": "Миша", "role": "student"}, "ttl_minutes": 180}

Ответ: {"url": "https://rismik.ru/embed/<token>", "token": "…", "expires_at": "…"}.

Выдавайте ссылку прямо перед входом и только этому человеку: ссылка и есть его пропуск.

Содержимое урока

• GET /lessons/{id}/snapshot — доска в JSON: элементы и страницы. Удобно хранить у себя после урока.
• GET /lessons/{id}/preview — последняя миниатюра доски в PNG. Если миниатюры ещё нет, возвращает 404 no_preview.

Минуты и тариф

Урок считается, пока в нём одновременно не меньше двух человек (на доске или в звонке); преподаватель, который готовится один, минуты не тратит.

Тарифов два:

• «Доска + видео» — можно создавать уроки обоих видов. Минута урока с видео списывает минуту баланса, минута урока board_only — её долю (board_rate_percent, обычно 30 %).
• «Только доска» — уроки только board_only, видеозвонка нет ни в одном уроке, каждая минута списывает board_rate_percent минуты.
• GET /balance → {"balance_seconds": 35940, "balance_minutes": 599, "plan": "full", "board_rate_percent": 30}. Во время урока, который идёт, баланс может уйти в минус.
• GET /usage?from=2026-10-01&to=2026-10-31 → минуты по урокам и дням (дни по московскому времени, период до года, по умолчанию последние 30 дней). seconds — время урока, charged_seconds — сколько списано с баланса:

{"total_seconds": 5400, "total_charged_seconds": 3510, "items": [
  {"lesson_id": "6f1c…", "external_id": "course-7/lesson-3", "mode": "full", "day": "2026-10-14", "seconds": 2700, "charged_seconds": 2700},
  {"lesson_id": "9a2d…", "external_id": "course-7/lesson-4", "mode": "board_only", "day": "2026-10-14", "seconds": 2700, "charged_seconds": 810}
]}

• GET /calls?from=2026-10-01&to=2026-10-31&limit=100&offset=0 → детализация: каждое занятие, от момента, когда в уроке стало двое, до 5 минут без людей. Новые сверху, период — по дате начала (московские дни), до года, по умолчанию последние 30 дней. people — сколько человек было одновременно в самый людный момент, cost_rub — стоимость списанных минут по средней цене ваших минут на тот момент (оплаченные суммы на все полученные минуты; бесплатные минуты её снижают). У занятия, которое идёт, ended_at — null. То же — в кабинете, раздел «Детализация», с выгрузкой в таблицу:

{"from": "2026-10-01", "to": "2026-10-31",
 "total": {"count": 2, "seconds": 5400, "charged_seconds": 3510, "cost_rub": 4563.0},
 "items": [
  {"id": "…", "lesson_id": "6f1c…", "title": "Дроби, 5 класс", "external_id": "course-7/lesson-3", "mode": "full",
   "started_at": "2026-10-14T15:00:00+00:00", "ended_at": "2026-10-14T15:44:00+00:00", "going": false,
   "seconds": 2700, "charged_seconds": 2700, "cost_rub": 3510.0, "people": 2}
 ]}

Вебхук

• PUT /webhook {"url": "https://…"} → {"url", "secret"}. Секрет новый при каждом вызове и показывается один раз.
• DELETE /webhook → 204.
• POST /webhook/test → 202: отправляет на ваш адрес событие webhook.test.

События и проверка подписи описаны в webhooks.md.