Архитектура
OpenAPI-контракты
API-контракты микросервисов Karometr — эндпоинты, схемы и статус спецификации.
OpenAPI-контракты
Статус
Формальная OpenAPI-спецификация (
openapi.yaml) находится в разработке и будет добавлена в репозиторий по завершении этапа M1. Этот раздел фиксирует эндпоинты и схемы из ТЗ v1.Версия API
Все эндпоинты публичного API используют префикс /api/v1/.
Базовый URL: https://api.karometr.ru/api/v1
Эндпоинты v1
Аутентификация
POST /auth/login
body: { email, password }
response: { access_token, refresh_token, expires_in }
POST /auth/refresh
body: { refresh_token }
response: { access_token, expires_in }
Загрузка данных
POST /ingest/files
content-type: multipart/form-data
body: { file, dealer_id, period }
response: { job_id, status }
GET /ingest/jobs/{id}
response: { job_id, status, progress, errors, created_at, finished_at }
Аналитика и индексы
GET /indices
params: { brand_id?, region_id?, model_family_id?, date_from?, date_to?, period_type? }
response: { items: [{ date, demand_growth, dsr, z_t, inventory }] }
GET /forecasts
params: { brand_id?, region_id?, horizon_days? }
response: { items: [{ date, value, confidence_low, confidence_high }] }
GET /dashboard/summary
params: { brand_id?, region_id? }
response: { kpi: [...], alerts: [...], updated_at }
Подписка
GET /subscription/current
response: { plan, status, limits, expires_at }
Аутентификация запросов
Все защищённые эндпоинты требуют заголовок:
Authorization: Bearer <access_token>
Токены выдаёт Keycloak. Время жизни access token — короткое (по умолчанию 5 минут), refresh token — с ротацией.
Межсервисная авторизация
Для service-to-service вызовов используется схема client_credentials:
POST /auth/token
body: { grant_type: client_credentials, client_id, client_secret }
response: { access_token, expires_in }
Коды ошибок
| Код | Описание |
|---|---|
| 400 | Неверный запрос или формат данных |
| 401 | Токен отсутствует или истёк |
| 403 | Доступ запрещён ABAC-политикой |
| 404 | Ресурс не найден |
| 422 | Ошибка валидации бизнес-правил |
| 429 | Превышен rate limit |
| 500 | Внутренняя ошибка сервиса |
Планируемые артефакты
openapi.yaml— полная спецификация (цель: M1).asyncapi.yaml— схемы событий RabbitMQ (цель: M2).- Swagger UI / Redoc — интерактивная документация (цель: M2).