Базовые правила для всех публичных методов: как обращаться к платформе, как передавать ключи и токены, как читать ответы. Прочитайте этот раздел перед интеграцией.
Интерактивный справочник: Swagger UI, сводный индекс методов.
https://<host>/Все пути ниже — относительно base URL. В prod используется только HTTPS.
/api/v1/…/api/module/имя_расширения/…| Метод | Заголовок | Применение |
|---|---|---|
| токен доступа (JWT) | Authorization: Bearer <access_token> | Public Auth; Files API модуля 1.0.0 (access token) |
| API Key | X-API-Key: <key> | Mail, Database; Files — только с модулем медиатеки 1.0.0 |
| None | — | Register/login при public_api_access_mode: open; OpenAPI |
API-ключи создаются в админ-панели: Настройки → API-ключи. С 1.0.10 доступны типы:
| Тип | Назначение |
|---|---|
public | Site key для фронта (SPA, ЛК); назначается в системных настройках при api_key_required |
service | Backend-интеграции; обязательна привязка к сервису и whitelist таблиц для Database API |
Разрешения service-ключа:
| Permission | Доступ |
|---|---|
mail:send, mail:* | API почты |
db:query, db:* | API данных |
files:upload, files:download, files:* | Files API (модуль 1.0.0, не ядро) |
/api/v1/auth/*)Успех:
{
"success": true,
"data": { }
}Ошибка:
{
"success": false,
"error": {
"code": "invalid_credentials",
"message": "Human-readable message",
"retry_after": 60
}
}Используется при отправке почты и в методах некоторых расширений.
Успех:
{
"success": true,
"data": { },
"meta": { "trace_id": "...", "execution_ms": 12.3 },
"errors": []
}Ошибка:
{
"success": false,
"data": {},
"meta": {},
"errors": [{ "code": "validation_error", "message": "...", "details": {} }]
}/api/v1/db/*; Files — модуль 1.0.0)Успех:
{ "success": true, ...payload fields... }Ошибка:
{ "success": false, "error": "message string" }| Код | Значение |
|---|---|
| 200 | Успех |
| 201 | Ресурс создан (register) |
| 202 | Принято в очередь (async mail) |
| 400 | Ошибка валидации / бизнес-логики |
| 401 | Не авторизован (нет/неверный token/key) |
| 403 | Доступ запрещён (permissions, plugin policy) |
| 404 | Ресурс не найден |
| 422 | Ошибка проверка формата данных-валидации (Public Auth) |
| 429 | Rate limit |
| 502/503 | Сервис недоступен (mail provider, auth service) |
| Тип запроса | Header |
|---|---|
| JSON body | Content-Type: application/json |
| File upload | Content-Type: загрузка файлов (multipart) |
| Idempotency (mail) | ключ идемпотентности: <uuid> (опционально, дублирует body-поле) |
Public Auth применяет rate limit на login/register (код rate_limited, заголовок Retry-After). Прочие service API — по конфигурации платформы.
Настраивается администратором платформы. Если ваш сайт на другом домене — согласуйте список разрешённых адресов с оператором.
API почты поддерживает ключ идемпотентности (header или body idempotency_key) для предотвращения дублирования отправок.
public_api_separate)Если в конфигурации включено разделение портов, платформа слушает два адреса:
| Порт | Параметр | Назначение |
|---|---|---|
| Основной | web.port (обычно 5000) | Админ-панель; почта и файлы — при раздельных портах |
| Публичный | web.public_port (обычно 5001) | Авторизация, данные, расширения, Swagger UI |
На публичном порту доступны только методы для внешних приложений. На основном — управление платформой.
Важно: методы почты (/api/v1/mail/*) при раздельных портах — на основном порту (web.port). Files API (/api/v1/files/*, модуль 1.0.0) — по той же схеме, если модуль установлен; см. api-files.html.
Если разделение выключено (public_api_separate: false), все публичные методы доступны на одном порту.
Параметр web.public_api_access_mode:
| Значение | Поведение |
|---|---|
open | Public endpoints доступны без глобального API-ключа (как в 1.0.9) |
api_key_required | Все public prefixes, включая /api/v1/auth/*, требуют заголовок X-API-Key с site public key |
Фронт может получить публичные параметры без admin-секретов: GET /api/v1/public/runtime-config. Подробнее — справочник config.yml.
Site public key может отображаться во фронте — это осознанная модель для SPA. Защита обеспечивается rate limit, lockout и политиками платформы, а не сокрытием ключа.
В интерактивный справочник (/api/openapi.json) по умолчанию входят:
/v1/auth/*/v1/db/*/module/*Почта — Mail. Files API — контракт модуля «Медиатека файлов» 1.0.0: отдельная документация (не в OpenAPI ядра).
Каждый HTTP-метод описан на отдельной странице. Рекомендуемый порядок чтения:
https://<host>/ (на стенде часто http://localhost:5000).Authorization: Bearer) или X-API-Key с нужным scope.data и пример JSON с success: true.success: false с error.code.Актуальная схема полей на вашей версии ядра — всегда в GET /api/openapi.json и Swagger; статические страницы дополняют сценарии для интегратора.