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-клиента (его получает сервисный пользователь, созданный на странице API-ключей) — иначе SaaS-эндпоинты вернут 403 Forbidden, даже если остальные права на месте.

Как получить токен и идентификаторы

1

Создайте API-ключ

Владелец школы открывает Управление → Школа → Для разработчиков → API-ключи (/manage/school/api-keys) и создаёт ключ — вместе с ним создаётся сервисный пользователь и выпускается токен. В школе может быть не больше 5 ключей. Там же — список ключей с превью токена и датой выпуска и ротация (перевыпуск) токена.
2

Сохраните токен

Скопируйте токен сразу — целиком он показывается только один раз (см. ниже). Это значение заголовка Authorization: Bearer <TOKEN>.
3

Скопируйте Seller-Id и School-Id

На той же странице в карточке «Данные для интеграции → Идентификаторы» указаны оба ID в виде Seller-Id: 123; School-Id: 456 — по клику строка копируется. Это числа; они не меняются при ротации токена.
Если удобнее — напишите в поддержку, поможем с настройкой.
Токен показывается целиком только в момент создания или ротации — сохраните его сразу. В списке ключей отображается только превью (первые и последние 4 символа) и дата выпуска. Ротация выпускает новый токен и немедленно отзывает старый.
Новый ключ сразу получает все права, нужные методам SaaS API, — первый запрос сработает без настройки. Состав зависит от сегмента школы (school.segment: Commerce — коммерческая онлайн-школа, Corporate — корпоративное обучение сотрудников): коммерческие дополнительно получают «Продажи школы» и «Возвраты школы», корпоративные — «Управление персоналом» и «Просмотр персонала» (синк сотрудников из HR/1С работает из коробки). Набор можно изменить на странице ключа, подробнее — в разделе «Права доступа».
Никогда не храните токен в коде или репозитории. Используйте переменные окружения. Токен даёт доступ к данным школы — не передавайте его третьим лицам.

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

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

string
обязательно
API-токен сервисного пользователя в формате Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете: Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».
integer
обязательно
Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
integer
обязательно
Числовой ID школы, берётся там же, где Seller-Id. Значение должно совпадать со школой продавца — иначе вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".
Отсутствие или невалидность Authorization приводит к 401 Unauthorized. Без Seller-Id (или с ID продавца, к которому токен не относится) методы вернут 401 Forbidden. Школу API определяет по продавцу, а School-Id сверяет с ней: если передан ID другой школы — 400 ForbiddenSchoolMismatch.
В примерах на страницах методов значения заголовков записаны как {{ sellerId }} и {{ schoolId }} — это переменные Postman-коллекции. При запуске cURL из терминала замените их на числовые ID, а YOUR_TOKEN — на токен.

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

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

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

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

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

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

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

Каждый метод проверяет права API-ключа — галочки на странице ключа в кабинете. Если у метода указано несколько прав, достаточно любого одного из них. Без нужного права метод вернёт 401 с сообщением Forbidden seller resource - permissions <Код>.

Права API-ключа

Какие галочки включить под задачу интеграции, какие методы открывает каждое право и какие права получает новый ключ.

Rate-limit

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

Пагинация

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

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

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

Обновлено: 2026-09-28 05:04 UTC