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

​
Базовый URL

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

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

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

Создание сервисного пользователя

Напишите в поддержку — мы создадим сервисного пользователя с нужными правами и выдадим API-токен.
Никогда не храните токен в коде или репозитории. Используйте переменные окружения. Токен даёт доступ к данным школы — не передавайте его третьим лицам.

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

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

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

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

Любой успешный ответ обёрнут в единую структуру:
​
success
boolean
required
true для успешных ответов (HTTP-коды 200–206).
​
code
integer
required
HTTP-код ответа (200, 201, и т.д.).
​
payload
any
required
Полезная нагрузка метода. Структура описана на странице конкретного метода и строго соответствует схеме ответа (лишние поля не возвращаются).
Успешный ответ
{
  "success": true,
  "code": 200,
  "payload": { /* method data */ }
}

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

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

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

HTTPcauseКогда возникает
400validationТело/параметры не прошли валидацию (тип, длина, формат, enum)
401UnauthorizedОтсутствует/невалиден токен (Invalid token credentials)
401BlockedПользователь токена неактивен или забанен
401ForbiddenНет доступа к ресурсу продавца/школы (недостаточно прав или ресурс не принадлежит школе)
403ForbiddenНедостаточно прав (RBAC): Доступ к ресурсу ограничен
429RateПревышен лимит запросов (см. ниже)
Конкретные cause-коды для каждого метода перечислены на его странице (раздел ответов «Error»). Например, при создании пользователя возможны UserAlreadyExist, EmailIsBusy, PhoneIsBusy, TgIdIsBusy.

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

Каждый метод требует у токена определённых прав. Если у метода указано несколько прав — достаточно любого одного из них (семантика OR). Примеры прав, используемых в SaaS API:
ПравоНазначение
SchoolManageUsersУправление пользователями школы (создание, обновление, удаление, группы, доступы)
SchoolManageSettingsНастройки школы, в т.ч. вебхуки
CourseCuratorКураторская работа: проверка практик, прогресс студентов
CourseStudentManageУправление студентами курса (зачисление, отчисление)
SellerSalesДоступ к продажам: счета, платежи, финансовые отчёты
FormManageУправление формами, макетами и значениями полей

​
Rate-limit

Часть методов ограничена по частоте вызовов. При превышении возвращается HTTP 429 с cause: "Rate":
Превышение лимита
{
  "success": false,
  "code": 429,
  "cause": "Rate",
  "message": "Rate limit exceeded",
  "data": { "retryAfter": "2025-01-18T12:45:10.000Z" }
}
  • Лимит считается по сервисному пользователю (токену).
  • Поле data.retryAfter подсказывает, когда можно повторить запрос.
  • Лимиты указаны на страницах методов. Например, генерация выгрузок — 100 запросов в час.
Реализуйте retry с учётом retryAfter и экспоненциальной задержкой для временных ошибок (429, 5xx).

​
Пагинация

Списочные методы (.../list/raw, прогресс по курсу и т.п.) принимают параметры пагинации в query:
​
take
integer
Размер страницы. От 1 до 1000. По умолчанию 100.
​
page
integer
Номер страницы (начиная с 1). Альтернатива skip.
​
skip
integer
Смещение (число пропускаемых записей). Игнорируется, если задан page.
Ответ списочного метода — единый конверт со страницей:
Структура страницы
{
  "success": true,
  "code": 200,
  "payload": {
    "items": [ /* items */ ],
    "page": 1,
    "count": 245,
    "pages": 3,
    "isFirst": true,
    "isLast": false,
    "next": { "skip": 100, "take": 100, "page": 2 },
    "prev": { "skip": 0, "take": 100, "page": 1 }
  }
}
Параметры-массивы передаются повторением ключа: userIds=1&userIds=2&userIds=3. Диапазоны передаются как вложенные поля, например createdAtDateRange[from] и createdAtDateRange[to].

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

curl --location 'https://api.exode.biz/saas/v2/user/find?extId=crm_12345' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}'
Всегда проверяйте success/code и обрабатывайте cause ошибки — это ускорит диагностику интеграции.