Обзор API

MARV предоставляет V2 как основную клиентскую API; V1 поддерживается для обратной совместимости. ACP - административный профиль; EXT - внешние вебхуки мерчантов.

Авторизация (V2)

Требуемые и дополнительные заголовки запроса:

Заголовок	Обязателен	Описание
X-Api-Token	да	Токен платформы (подписанный секретом платформы)
X-Api-Type	да	Тип API (целое), выбирает конфигурацию платформы
X-Api-Uid	да	UID пользователя в целевой платформе
X-Session-Token	да*	Токен сессии (single-session режим)
X-Client-Version	нет	Версия клиента; валидируется согласно конфигу
X-Inviter-Uid	нет	UID пригласившего (для первичного входа)

Порядок проверки: валидация заголовков → проверка минимальной версии → проверка токена платформы → создание/получение пользователя и обновление атрибутов → (опц.) выдача X-Set-Session-Token.

Получение Session Token (vX/users):

• Если включён single-session режим (см. app.session.single_mode.* в config/main.md), после первого запроса к vX/users без X-Session-Token сервер вернёт заголовок X-Set-Session-Token с новым значением токена.
• Далее этот токен нужно передавать в заголовке X-Session-Token во всех последующих запросах (V2).
• V2: используйте POST /v2/users/me или другой метод v2/users/* для первичного получения токена. Для V1 - аналогичные методы v1/users/*.
• При истечении/отзыве токена сервер вернёт ошибку; сбросьте локальный токен и повторите первичный запрос к vX/users.

Request ID и страна клиента

• Клиент может (но не обязан) передавать X-Request-Id. Если заголовок не задан, MARV сгенерирует UUID самостоятельно.
• Каждый ответ содержит X-Request-Id — его можно использовать для сопоставления с логами (trace_id добавляется в zerolog контекст).
• При работе через Cloudflare заголовок CF-IPCountry проксируется в ответ как X-Client-Country-Code, поэтому страна клиента доступна даже без отдельного API.
• В ответ также добавляется X-Server-Id: это идентификатор узла (app.server.id из конфига либо автогенерированное значение), что упрощает отладку и мониторинг лидерства.

Верификация IAP

• ApiType/ApiUid всегда берутся из аутентифицированного пользователя; значения в теле запроса игнорируются.
• Поле user_id опционально. Если его нет, MARV подставляет ApiUid текущего пользователя. Указывайте user_id явно только на платформах, где IAP использует другой идентификатор (например, Discord).

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

• Успех (V2): { "time": <unix>, "data": <payload> }
• Ошибка (V2/ACP): { "time": <unix>, "error": { "code": "...", "http_status": N, "message": "...", "details": { ... }}}

Подробно про ошибки и соответствия доменных ошибок см. в V2 Errors.

Практики для контроллеров

• HTTP-слой держим тонким: каждый контроллер объявляет локальные интерфейсы сервисов и передаёт в домен ctx.Request.Context().

Конфигурация и таймауты

• HTTP‑таймауты и бакеты метрик настраиваются в config/main.md, секциях app.http.timeouts.* и observability.metrics.http_buckets_ms.

EXT (мерчанты)

• Общие принципы и требования описаны в EXT Guide. Для каждого мерчанта используется собственная авторизация/подпись.

Метрики и наблюдаемость (ACP)

• Системные метрики доступны по эндпоинту GET /acp/system/metrics. Описание полей и настройки - в Observability.

Реклама (ACP → Ads)

• /acp/ads/list возвращает все объявления и runtime‑снимок контроллерных метрик (количество вызовов, ошибки, p95) по префиксу /acp/ads/*. Эндпоинт read-only, отдельная роль не требуется.
• /acp/ads/create|update|delete|toggle требуют роль AccessAds (1024). После модификаций ответы всегда содержат commit: ["ads"] и актуальный список ads, чтобы UI мог обновить состояние без повторного запроса.
• DTO и поля объявлений описаны в openapi.yaml (AcpAd, AcpCreateAdDTO, ...). Поля title/description/data — произвольные JSON‑структуры, weight задаёт приоритет показа.

Alert Center (ACP)

• /acp/alerts/list — фильтрует критические уведомления (type, severity, status, tags, диапазон дат). Требует роль AccessAlerts (2048).
• /acp/alerts/detail — возвращает карточку уведомления и историю доставок (Slack/Telegram webhooks).
• /acp/alerts/ack — подтверждает обработку, сохраняет комментарий (виден всем операторам).
• Конфигурация каналов и шаблонов описана в config/main.md; подробный контракт — в openapi.yaml.

Реклама (V1 → Ads)

• POST /v1/ads/fetch возвращает доступные объявления (только включённые и отфильтрованные по весу). Дополнительно формируется video_url по domain.stream.subdomain из конфигурации.
• POST /v1/ads/impression и POST /v1/ads/click инкрементируют счётчики просмотров/кликов по sid. Эти вызовы не возвращают payload.
• Все V1 Ads маршруты используют стандартную платформенную авторизацию (X-Api-*). См. структуры V1Ad, V1AdImpressionDTO, V1AdClickDTO в openapi.yaml.

Реклама (V2 → Ads)

• POST /v2/ads возвращает массив объявлений (V2Ad) с теми же полями, что и V1 (включая вычисленный video_url).
• POST /v2/ads/impression и POST /v2/ads/click принимают DTO (V2AdImpressionDTO, V2AdClickDTO) и увеличивают счётчики по sid.
• Все вызовы требуют стандартную V2 авторизацию (X-Api-*). Ответы следуют формату { "time": ..., "data": ... }. Схемы перечислены в openapi.yaml.