КАСКАД 360 КАСКАД 360CASCAD 360

Общие соглашения Public API

Базовые правила для всех публичных методов: как обращаться к платформе, как передавать ключи и токены, как читать ответы. Прочитайте этот раздел перед интеграцией.

Адрес платформы

https://<host>/

Все пути ниже — относительно base URL. В prod используется только HTTPS.

Версионирование API

Методы аутентификации

МетодЗаголовокПрименение
токен доступа (JWT)Authorization: Bearer <access_token>Public Auth, Files API (access token, audience public для auth routes)
API KeyX-API-Key: <key>Mail, Database, Files (service integration)
None—Register/login, plugin routes (policy-based), OpenAPI

API-ключи создаются в админ-панели: Настройки → API-ключи. Каждому ключу назначаются разрешения:

PermissionДоступ
mail:send, mail:*Mail Service
db:query, db:*Database Service
files:upload, files:download, files:*Files Service

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

формат ответа A — Public Auth (/api/v1/auth/*)

Успех:

{
  "success": true,
  "data": { }
}

Ошибка:

{
  "success": false,
  "error": {
    "code": "invalid_credentials",
    "message": "Human-readable message",
    "retry_after": 60
  }
}

Формат ответа B — почта и расширения

Используется при отправке почты и в методах некоторых расширений.

Успех:

{
  "success": true,
  "data": { },
  "meta": { "trace_id": "...", "execution_ms": 12.3 },
  "errors": []
}

Ошибка:

{
  "success": false,
  "data": {},
  "meta": {},
  "errors": [{ "code": "validation_error", "message": "...", "details": {} }]
}

формат ответа C — Legacy JSON (/api/v1/db/*, Files)

Успех:

{ "success": true, ...payload fields... }

Ошибка:

{ "success": false, "error": "message string" }

Общие HTTP-коды

КодЗначение
200Успех
201Ресурс создан (register)
202Принято в очередь (async mail)
400Ошибка валидации / бизнес-логики
401Не авторизован (нет/неверный token/key)
403Доступ запрещён (permissions, plugin policy)
404Ресурс не найден
422Ошибка проверка формата данных-валидации (Public Auth)
429Rate limit
502/503Сервис недоступен (mail provider, auth service)

Content-Type

Тип запросаHeader
JSON bodyContent-Type: application/json
File uploadContent-Type: загрузка файлов (multipart)
Idempotency (mail)ключ идемпотентности: <uuid> (опционально, дублирует body-поле)

Rate limiting

Public Auth применяет rate limit на login/register (код rate_limited, заголовок Retry-After). Прочие service API — по конфигурации платформы.

CORS

Настраивается администратором платформы. Если ваш сайт на другом домене — согласуйте список разрешённых адресов с оператором.

Idempotency

Mail Service поддерживает ключ идемпотентности (header или body idempotency_key) для предотвращения дублирования отправок.

Два порта (public_api_separate)

Если в конфигурации включено разделение портов, платформа слушает два адреса:

ПортПараметрНазначение
Основнойweb.port (обычно 5000)Админ-панель; почта и файлы — при раздельных портах
Публичныйweb.public_port (обычно 5001)Авторизация, данные, расширения, Swagger UI

На публичном порту доступны только методы для внешних приложений. На основном — управление платформой.

Важно: методы почты (/api/v1/mail/*) и файлов (/api/v1/files/*) при раздельных портах вызываются на основном порту (web.port), а не на публичном.

Если разделение выключено (public_api_separate: false), все публичные методы доступны на одном порту.

Что попадает в OpenAPI автоматически

В интерактивный справочник (/api/openapi.json) по умолчанию входят:

Почта и файлы описаны отдельно в разделах Mail и Files.