Skip to main content
Exode SaaS API — это REST API поверх HTTPS. Все эндпоинты находятся под префиксом saas/v2/.

Базовый URL

Полный адрес метода: https://api.exode.biz/saas/v2/<module>/<method> — например https://api.exode.biz/saas/v2/user/create.

Аутентификация

Запросы выполняются от имени сервисного пользователя (API-клиента) — это сотрудник школы с настроенным набором прав и собственным API-токеном.
  • Аутентификация — через заголовок Authorization: Bearer <TOKEN>.
  • Токен бессрочный, его можно отозвать в любой момент.
  • Токен должен принадлежать пользователю с признаком API-клиента — иначе SaaS-эндпоинты вернут ошибку доступа, даже если остальные права на месте.

Создание API-ключа в кабинете

Владелец школы может создать сервисного пользователя и API-токен самостоятельно: раздел Управление → Школа → API-ключи (/manage/school/api-keys). Там же — список ключей с превью токена и датой выпуска, а также ротация (перевыпуск) токена. Если удобнее — напишите в поддержку, поможем с настройкой.
Токен показывается целиком только в момент создания или ротации — сохраните его сразу. В списке ключей отображается только превью (первые и последние 4 символа) и дата выпуска. Ротация выпускает новый токен и немедленно отзывает старый.
Набор прав ключа зависит от сегмента школы: для корпоративных школ ключ создаётся с правами управления орг-структурой (StaffManage, StaffView) — синк сотрудников из HR/1С работает из коробки; для коммерческих — с правами продаж (SellerSales, SellerRefunds). Набор можно изменить на странице ключа в кабинете.
Никогда не храните токен в коде или репозитории. Используйте переменные окружения. Токен даёт доступ к данным школы — не передавайте его третьим лицам.

Обязательные заголовки

Заголовки запроса

string
required
API токен сервисного пользователя в формате Bearer. Получите токен в панели администратора школы. Формат: Bearer YOUR_TOKEN.
string
required
Уникальный идентификатор продавца в системе. Используется для разграничения доступа между разными продавцами.
string
required
Уникальный идентификатор школы в системе. Определяет контекст выполнения операции.
Отсутствие или невалидность Authorization приводит к ошибке 401. Seller-Id и School-Id определяют контекст продавца и школы; без них защищённые методы вернут 401.

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

Любой успешный ответ обёрнут в единую структуру:
boolean
required
true для успешных ответов (HTTP-коды 200206).
integer
required
HTTP-код ответа (200, 201, и т.д.).
any
required
Полезная нагрузка метода. Структура описана на странице конкретного метода и строго соответствует схеме ответа (лишние поля не возвращаются).
Успешный ответ

Формат ошибок

Ошибки возвращаются с тем же конвертом плюс полями cause, message, error и опциональным data:
boolean
required
Всегда false для ошибок.
integer
required
HTTP-код ошибки: 400, 401, 403, 404, 429, 500.
string
required
Машиночитаемый код причины. По нему удобно строить обработку. Примеры: validation, Unauthorized, Forbidden, EmailIsBusy, Rate.
string
required
Человекочитаемое сообщение об ошибке.
string
required
Техническое описание (по умолчанию совпадает с message).
object
Дополнительные данные (например, retryAfter для 429). Опционально.
Пример ошибки

Частые коды причин (cause)

Конкретные cause-коды для каждого метода перечислены на его странице (раздел ответов «Error»). Например, при создании пользователя возможны UserAlreadyExist, EmailIsBusy, PhoneIsBusy, TgIdIsBusy.

Права доступа (RBAC)

Каждый метод требует у токена определённых прав. Если у метода указано несколько прав — достаточно любого одного из них (семантика OR). Примеры прав, используемых в SaaS API:

Rate-limit

Часть методов ограничена по частоте вызовов. При превышении возвращается HTTP 429 с cause: "Rate":
Превышение лимита
  • Лимит считается по сервисному пользователю (токену).
  • Поле data.retryAfter подсказывает, когда можно повторить запрос.
  • Лимиты указаны на страницах методов. Например, генерация выгрузок — 100 запросов в час.
Реализуйте retry с учётом retryAfter и экспоненциальной задержкой для временных ошибок (429, 5xx).

Пагинация

Списочные методы (.../list/raw, прогресс по курсу и т.п.) принимают параметры пагинации в query:
integer
Размер страницы. От 1 до 1000. По умолчанию 100.
integer
Номер страницы (начиная с 1). Альтернатива skip.
integer
Смещение (число пропускаемых записей). Игнорируется, если задан page.
Ответ списочного метода — единый конверт со страницей:
Структура страницы
Параметры-массивы передаются повторением ключа: userIds=1&userIds=2&userIds=3. Диапазоны передаются как вложенные поля, например createdAtDateRange[from] и createdAtDateRange[to].

Пример запроса

Всегда проверяйте success/code и обрабатывайте cause ошибки — это ускорит диагностику интеграции.

Обновлено: 2026-07-14 23:56 UTC