FastAPI Reference

Проект: Корпоративная AI-система автоматизации E-commerce
Компонент: Единый API Gateway
Версия: 1.2
Дата: Февраль 2026

Изменения версии 1.2

Раздел	Изменение
Watcher	Полностью переработан раздел 6 — добавлены 25+ endpoints из репозитория Sign25/watcher

Изменения версии 1.1

Раздел	Изменение
Launcher	Добавлен раздел 15 — API для баннерного подменю
Office	Добавлен раздел 16 — API для дашборда AI-агентов
Logistic	Добавлен раздел 17 — API для управления логистикой
Shop	Добавлена справка — модуль работает через MCP без REST API

1. Общие сведения

1.1 Базовая информация

Параметр	Значение
Base URL	`https://adolf.su/api/v1`
Версионирование	Через URL path (`/api/v1/...`)
Формат данных	JSON
Аутентификация	API ключи (привязаны к пользователям)
Пагинация	offset-based (`?offset=0&limit=20`)

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

Все запросы требуют заголовка авторизации:

Authorization: Bearer {API_KEY}

API ключ наследует роль и brand_id пользователя, который его создал.

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

json

{
  "error": "Описание ошибки"
}

1.4 Стандартные HTTP-коды

Код	Описание
200	Успешный запрос
201	Ресурс создан
204	Нет контента (успешное удаление)
400	Некорректный запрос
401	Не авторизован
403	Доступ запрещён
404	Ресурс не найден
429	Превышен лимит запросов
500	Внутренняя ошибка сервера

1.5 Пагинация

Для списковых endpoints используются параметры:

Параметр	Тип	По умолчанию	Описание
`offset`	int	0	Смещение от начала
`limit`	int	20	Количество записей (макс. 100)

Ответ содержит метаданные пагинации:

json

{
  "items": [...],
  "total": 150,
  "offset": 0,
  "limit": 20
}

2. Служебные Endpoints

2.1 Health Check

GET /health

Проверка работоспособности API.

Доступ: Публичный (без авторизации)

Пример ответа:

json

{
  "status": "healthy",
  "version": "1.1.0",
  "timestamp": "2026-01-31T10:30:00Z"
}

GET /health/detailed

Детальная проверка состояния компонентов.

Доступ: Administrator

Пример ответа:

json

{
  "status": "healthy",
  "components": {
    "database": {"status": "healthy", "latency_ms": 5},
    "redis": {"status": "healthy", "latency_ms": 2},
    "celery": {"status": "healthy", "workers": 4},
    "timeweb_ai": {"status": "healthy", "latency_ms": 150},
    "timeweb_kb": {"status": "healthy", "latency_ms": 80}
  },
  "timestamp": "2026-01-31T10:30:00Z"
}

2.2 Метрики

GET /metrics

Метрики системы в формате Prometheus.

Доступ: Administrator

2.3 Celery Tasks

GET /tasks/{task_id}

Статус асинхронной задачи Celery.

Доступ: Manager+

Параметры пути:

Параметр	Тип	Описание
task_id	string	UUID задачи

Пример ответа:

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "result": {"processed": 150, "errors": 0},
  "created_at": "2026-01-31T10:00:00Z",
  "completed_at": "2026-01-31T10:05:00Z"
}

Возможные статусы: PENDING, STARTED, SUCCESS, FAILURE, RETRY

3. Auth — Аутентификация

3.1 Сессия

GET /auth/session

Информация о текущей сессии пользователя.

Доступ: Все авторизованные

Пример ответа:

json

{
  "user_id": 42,
  "username": "ivanov",
  "role": "manager",
  "brand_id": "ohana_market",
  "permissions": ["reputation.read", "reputation.write"]
}

3.2 API ключи

GET /auth/api-keys

Список API ключей текущего пользователя.

Доступ: Все авторизованные

POST /auth/api-keys

Создание нового API ключа.

Доступ: Все авторизованные

Тело запроса:

json

{
  "name": "New Integration Key"
}

DELETE /auth/api-keys/{key_id}

Отзыв API ключа.

Доступ: Все авторизованные (только свои ключи)

4. Knowledge — База знаний

4.1 Поиск

POST /knowledge/search

Семантический поиск по базе знаний.

Доступ: Все авторизованные

Тело запроса:

json

{
  "query": "состав артикула OM-001",
  "top_k": 3,
  "filters": {
    "category": "product",
    "brand_id": "ohana_market"
  }
}

4.2 Информация о товаре

GET /knowledge/product/{sku}

Структурированные данные о товаре (внутренний endpoint для модулей).

Доступ: Internal (Reputation, Content Factory)

4.3 Документы

GET /knowledge/documents

Список документов в базе знаний.

Доступ: Senior+

POST /knowledge/documents/{id}/approve

Модерация документа.

Доступ: Senior+

5. Reputation — Управление отзывами

5.1 Элементы (отзывы/вопросы)

GET /reputation/items

Список элементов для обработки.

Доступ: Manager+ (фильтрация по brand_id)

GET /reputation/items/{id}

Детали элемента.

Доступ: Manager+

POST /reputation/items/{id}/approve

Утверждение сгенерированного ответа.

Доступ: Manager+

POST /reputation/items/{id}/edit

Редактирование и утверждение ответа.

Доступ: Manager+

POST /reputation/items/{id}/regenerate

Перегенерация ответа с инструкциями.

Доступ: Manager+

5.2 Массовые операции

POST /reputation/items/bulk-approve

Массовое утверждение элементов.

Доступ: Senior+

5.3 Аналитика

GET /reputation/stats

Статистика по отзывам и вопросам.

Доступ: Senior+

GET /reputation/analytics

Аналитика: тональность, темы, AI-рекомендации.

Доступ: Senior+

6. Watcher — Мониторинг продавцов

Версия: 2.0
Архитектура: Node.js REST API + CDP Pool + Telegram Bot
Репозиторий: Sign25/watcher
Base URL: https://agent.adolf.su/api/v1

Система мониторинга продавцов на маркетплейсах (Wildberries, Ozon, Яндекс.Маркет). Собирает данные каталогов через реальные браузеры на домашних ПК, подключённых по FRP-туннелям.

6.1 Продавцы (Sellers)

GET /sellers

Список отслеживаемых продавцов.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
marketplace	string	Фильтр по маркетплейсу (wb, ozon, ymarket)
status	string	Фильтр по статусу (active, paused, removed)

Пример ответа:

json

{
  "items": [
    {
      "id": 1,
      "marketplace": "wb",
      "seller_id": "125487",
      "name": "Конкурент А",
      "slug": "konkurent-a",
      "status": "active",
      "priority": 1,
      "schedule_hours": 72,
      "enrich_schedule_hours": 24,
      "last_scan_at": "2026-01-31T03:15:00Z",
      "next_scan_at": "2026-02-03T03:15:00Z",
      "last_enriched_at": "2026-01-31T06:00:00Z",
      "next_enrich_at": "2026-02-01T06:00:00Z",
      "products_count": 450
    }
  ],
  "total": 25
}

GET /sellers/{id}

Детали продавца + информация о последнем скане.

Доступ: Manager+

Пример ответа:

json

{
  "id": 1,
  "marketplace": "wb",
  "seller_id": "125487",
  "name": "Конкурент А",
  "slug": "konkurent-a",
  "url": "https://www.wildberries.ru/seller/125487",
  "status": "active",
  "priority": 1,
  "schedule_hours": 72,
  "enrich_schedule_hours": 24,
  "last_scan": {
    "id": 156,
    "status": "completed",
    "products_found": 450,
    "new_products": 12,
    "removed_products": 3,
    "price_changes": 28,
    "duration_sec": 245,
    "completed_at": "2026-01-31T03:19:05Z"
  },
  "stats": {
    "total_scans": 45,
    "successful_scans": 43,
    "avg_products": 445,
    "avg_duration_sec": 230
  }
}

POST /sellers

Добавление нового продавца для мониторинга.

Доступ: Senior+

Тело запроса:

json

{
  "marketplace": "wb",
  "seller_id": "125487",
  "name": "Конкурент А",
  "url": "https://www.wildberries.ru/seller/125487",
  "slug": "konkurent-a"
}

Пример ответа:

json

{
  "id": 26,
  "marketplace": "wb",
  "seller_id": "125487",
  "name": "Конкурент А",
  "status": "active",
  "created_at": "2026-01-31T10:00:00Z"
}

PUT /sellers/{id}

Обновление настроек продавца.

Доступ: Senior+

Тело запроса:

json

{
  "name": "Конкурент А (обновлено)",
  "priority": 2,
  "schedule_hours": 48,
  "status": "active",
  "enrich_schedule_hours": 12
}

DELETE /sellers/{id}

Удаление продавца (мягкое — status=removed).

Доступ: Senior+

GET /sellers/{id}/products

Товары из последнего скана продавца.

Доступ: Manager+

Пример ответа:

json

{
  "seller_id": 1,
  "scan_id": 156,
  "scanned_at": "2026-01-31T03:19:05Z",
  "items": [
    {
      "sku": "12345678",
      "name": "Платье летнее",
      "price": 2990,
      "old_price": 4500,
      "discount": 34,
      "rating": 4.8,
      "reviews_count": 156,
      "badges": ["bestseller", "sale"]
    }
  ],
  "total": 450
}

GET /sellers/{id}/enriched

Обогащённые данные товаров продавца.

Доступ: Manager+

Пример ответа:

json

{
  "seller_id": 1,
  "enriched_at": "2026-01-31T06:00:00Z",
  "items": [
    {
      "sku": "12345678",
      "name": "Платье летнее",
      "brand": "NoName",
      "category": "Женская одежда / Платья",
      "composition": "95% хлопок, 5% эластан",
      "sizes": ["42", "44", "46", "48", "50"],
      "colors": ["красный", "синий", "чёрный"],
      "seller_rating": 4.9,
      "delivery_days": 2,
      "warehouse": "Коледино"
    }
  ],
  "total": 450
}

GET /sellers/{id}/diff

Сравнение двух последних сканов (новые, удалённые, изменения цен).

Доступ: Manager+

Пример ответа:

json

{
  "seller_id": 1,
  "current_scan_id": 156,
  "previous_scan_id": 155,
  "diff": {
    "new_products": [
      {"sku": "99999999", "name": "Новый товар", "price": 1990}
    ],
    "removed_products": [
      {"sku": "11111111", "name": "Удалённый товар"}
    ],
    "price_changes": [
      {
        "sku": "12345678",
        "name": "Платье летнее",
        "old_price": 3490,
        "new_price": 2990,
        "change_percent": -14.3
      }
    ]
  },
  "summary": {
    "new_count": 12,
    "removed_count": 3,
    "price_up_count": 5,
    "price_down_count": 23
  }
}

6.2 Сканирование (Scans)

GET /scans

История сканирований.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
seller_id	int	Фильтр по продавцу
status	string	completed, failed, running, queued
limit	int	Количество записей (по умолчанию 50)

Пример ответа:

json

{
  "items": [
    {
      "id": 156,
      "seller_id": 1,
      "seller_name": "Конкурент А",
      "marketplace": "wb",
      "task_type": "scan",
      "status": "completed",
      "source": "schedule",
      "products_found": 450,
      "new_products": 12,
      "removed_products": 3,
      "price_changes": 28,
      "pc_port": 9312,
      "duration_sec": 245,
      "started_at": "2026-01-31T03:15:00Z",
      "completed_at": "2026-01-31T03:19:05Z"
    }
  ],
  "total": 1250
}

GET /scans/{id}

Детали скана + список товаров.

Доступ: Manager+

POST /scans

Создание задачи сканирования вручную.

Доступ: Senior+

Тело запроса:

json

{
  "seller_id": 1
}

Пример ответа:

json

{
  "id": 157,
  "seller_id": 1,
  "status": "queued",
  "source": "manual",
  "created_at": "2026-01-31T10:00:00Z"
}

POST /enrichments

Создание задачи обогащения вручную.

Доступ: Senior+

Тело запроса:

json

{
  "seller_id": 1
}

6.3 Товары и история цен (Products)

GET /products/{sku}

Данные товара по SKU.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
marketplace	string	wb, ozon, ymarket

Пример ответа:

json

{
  "sku": "12345678",
  "marketplace": "wb",
  "name": "Платье летнее",
  "current_price": 2990,
  "old_price": 4500,
  "discount": 34,
  "rating": 4.8,
  "reviews_count": 156,
  "seller_id": 1,
  "seller_name": "Конкурент А",
  "last_seen_at": "2026-01-31T03:19:05Z"
}

GET /products/{sku}/enriched

Обогащённые данные товара.

Доступ: Manager+

GET /products/{sku}/history

История цен товара.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
limit	int	Количество записей (по умолчанию 100)

Пример ответа:

json

{
  "sku": "12345678",
  "history": [
    {
      "price": 2990,
      "old_price": 4500,
      "discount": 34,
      "recorded_at": "2026-01-31T03:19:05Z"
    },
    {
      "price": 3490,
      "old_price": 4500,
      "discount": 22,
      "recorded_at": "2026-01-28T03:15:00Z"
    }
  ]
}

6.4 Файлы результатов

GET /files/catalog

Список файлов каталога (архив сканов).

Доступ: Manager+

GET /files/enriched

Список файлов обогащения.

Доступ: Manager+

GET /files/{type}/{filename}

Скачивание файла результата.

Доступ: Manager+

Параметры пути:

Параметр	Тип	Описание
type	string	catalog или enriched
filename	string	Имя файла (например, wb_seller_1_2026-01-31.json)

6.5 CDP Pool API

GET /pool/status

Статус всех ПК в пуле (проксирует CDP Pool /status).

Доступ: Administrator

Пример ответа:

json

{
  "pcs": [
    {
      "port": 9312,
      "name": "office-pc-1",
      "status": "stable",
      "busy": false,
      "current_task": null,
      "online_since": "2026-01-31T08:00:00Z",
      "chrome_version": "121.0.6167.85"
    },
    {
      "port": 9315,
      "name": "home-pc-2",
      "status": "busy",
      "busy": true,
      "current_task": "scan_156",
      "online_since": "2026-01-31T07:30:00Z"
    }
  ]
}

GET /pool/summary

Сводка по пулу ПК.

Доступ: Administrator

Пример ответа:

json

{
  "total": 8,
  "online": 6,
  "stable": 5,
  "busy": 2,
  "free": 3
}

6.6 Задачи и статистика

GET /tasks

Текущие running + queued задачи.

Доступ: Manager+

Пример ответа:

json

{
  "running": [
    {
      "id": 157,
      "seller_name": "Конкурент А",
      "task_type": "scan",
      "pc_port": 9312,
      "started_at": "2026-01-31T10:05:00Z",
      "progress": "scrolling catalog"
    }
  ],
  "queued": [
    {
      "id": 158,
      "seller_name": "Конкурент Б",
      "task_type": "enrich",
      "queued_at": "2026-01-31T10:00:00Z"
    }
  ]
}

GET /stats

Общая статистика системы.

Доступ: Manager+

Пример ответа:

json

{
  "sellers": {
    "total": 25,
    "active": 22,
    "paused": 2,
    "removed": 1
  },
  "scans": {
    "total": 1250,
    "today": 15,
    "success_rate": 95.6
  },
  "products": {
    "total_tracked": 11250,
    "price_changes_today": 156
  },
  "pool": {
    "total_pcs": 8,
    "online": 6,
    "busy": 2
  }
}

6.7 Monitor Web UI API

Base URL: https://agent.adolf.su/api
Назначение: Веб-интерфейс мониторинга и настройки

GET /api/agents

Статус ПК с логами.

Доступ: Administrator (Web Auth)

GET /api/summary

Сводка пула.

Доступ: Administrator

GET /api/config

Конфигурация системы + схема валидации.

Доступ: Administrator

PUT /api/config

Обновление параметра конфигурации.

Доступ: Administrator

Тело запроса:

json

{
  "key": "scheduler.defaultScanScheduleHours",
  "value": 48
}

GET /api/sellers

Список продавцов с очередями и статистикой.

Доступ: Manager+

POST /api/sellers

Добавление продавца через Web UI.

Доступ: Senior+

PUT /api/sellers/{id}/status

Обновление статуса продавца.

Доступ: Senior+

Тело запроса:

json

{
  "status": "paused"
}

GET /api/frp

Карта FRP-портов (статус, прокси, трафик).

Доступ: Administrator

GET /api/sftp/config

SFTP-конфигурация (пароль маскирован).

Доступ: Administrator

PUT /api/sftp/config

Обновление SFTP-настроек.

Доступ: Administrator

POST /api/sftp/test

Тест SFTP-подключения.

Доступ: Administrator

GET /api/sftp/transfers

История SFTP-выгрузок + статистика.

Доступ: Administrator

GET /api/frp-client

Скачать ZIP с FRP-клиентом для домашнего ПК.

Доступ: Administrator

6.8 Telegram Bot команды

Точка входа: node bot.js
Управление: Через Telegram-чат с ботом

Команда	Описание
`WB125487` / `OZ465656` / `YM213246`	Быстрый скан (префикс определяет маркетплейс)
`/add <mp> <id> <имя>`	Добавить продавца
`/scan <id>`	Запустить скан вручную
`/enrich <id>`	Обогатить данные продавца
`/autoenrich <id> [часы]`	Автообогащение (0 = выкл, по умолчанию 24ч)
`/list`	Список продавцов
`/queue`	Текущая очередь
`/running`	Активные задачи
`/history [N]`	История сканов
`/status`	Общий статус системы
`/pc`	Статус ПК в пуле
`/screenshot`	Скриншот браузера
`/result <id>` / `/diff <id>` / `/file <id>`	Результаты
`/retry`	Повторить упавшие задачи
`/summary`	Сводка

7. Content Factory — Генерация контента

7.1 Генерация

POST /content/generate

Генерация title/description/attributes.

Доступ: Senior+

POST /content/generate/visual-prompt

Генерация ТЗ для дизайнера.

Доступ: Senior+

7.2 Черновики

GET /content/drafts

Список черновиков.

Доступ: Senior+

PUT /content/drafts/{id}

Редактирование черновика.

Доступ: Senior+

POST /content/drafts/{id}/approve

Утверждение черновика.

Доступ: Senior+

POST /content/drafts/{id}/publish

Публикация на маркетплейс.

Доступ: Senior+

8. Marketing — Рекламные кампании

8.1 Кампании

GET /marketing/campaigns

Список кампаний.

Доступ: Manager+

POST /marketing/campaigns

Создание кампании.

Доступ: Manager+

PUT /marketing/campaigns/{id}

Обновление настроек.

Доступ: Manager+

POST /marketing/campaigns/{id}/pause

Приостановка кампании.

Доступ: Manager+

POST /marketing/campaigns/{id}/resume

Возобновление кампании.

Доступ: Manager+

8.2 Ключевые слова

GET /marketing/campaigns/{id}/keywords

Список ключевых слов кампании.

Доступ: Manager+

POST /marketing/campaigns/{id}/keywords

Добавление ключевых слов.

Доступ: Manager+

8.3 Ставки

PUT /marketing/bids

Обновление ставок (batch).

Доступ: Manager+

GET /marketing/bids/recommendations

AI-рекомендации по ставкам.

Доступ: Manager+

8.4 Статистика

GET /marketing/stats

Общая статистика.

Доступ: Manager+

GET /marketing/reports/daily

Ежедневный отчёт.

Доступ: Senior+

9. Scout — Аналитика ниш

POST /scout/analyze

Запуск анализа ниши.

Доступ: Senior+

GET /scout/analyses/{id}

Результаты анализа.

Доступ: Senior+

GET /scout/analyses

История анализов.

Доступ: Senior+

10. CFO — Финансовая отчётность

10.1 P&L Отчёты

GET /cfo/pnl

Отчёт P&L с группировкой (sku/category/brand/marketplace).

Доступ: Senior+

GET /cfo/pnl/sku/{sku}

Детальный P&L по SKU.

Доступ: Director+

10.2 ABC-анализ

GET /cfo/abc

ABC-классификация SKU.

Доступ: Senior+

10.3 AI Insights

GET /cfo/insights

AI-инсайты по финансам.

Доступ: Director+

10.4 Себестоимость

GET /cfo/costs

Справочник себестоимости.

Доступ: Director+

POST /cfo/costs/import

Импорт себестоимости из файла.

Доступ: Director+

11. Lex — Правовой мониторинг

11.1 Документы

GET /lex/documents

Список правовых документов.

Доступ: Manager+

GET /lex/documents/{id}

Детали документа с действиями.

Доступ: Manager+

11.2 Алерты

GET /lex/alerts

Правовые алерты.

Доступ: Manager+

11.3 Ключевые слова

GET /lex/keywords

Ключевые слова для мониторинга.

Доступ: Administrator

POST /lex/keywords

Добавление ключевого слова.

Доступ: Administrator

11.4 Статистика

GET /lex/stats

Статистика мониторинга.

Доступ: Senior+

12. Notifications — Уведомления

12.1 Уведомления пользователя

GET /notifications

Список уведомлений текущего пользователя.

Доступ: Все авторизованные

POST /notifications/{id}/read

Отметить как прочитанное.

Доступ: Все авторизованные

POST /notifications/read-all

Отметить все как прочитанные.

Доступ: Все авторизованные

12.2 WebSocket

WS /ws/notifications

WebSocket для real-time уведомлений.

Доступ: Все авторизованные

13. Webhooks — Внутренние события

POST /webhooks/alerts

Приём алертов от модулей.

Доступ: Internal

14. Chat — AI Completions

POST /chat/completions

Запрос к AI с контекстом модуля.

Доступ: Все авторизованные

15. Launcher — Баннерное подменю

> Версия: Core 3.1
> Назначение: Двухуровневая навигация с визуальным выбором действий

15.1 Конфигурация модуля

GET /launcher/config/{module}

Получение конфигурации баннеров для модуля.

Доступ: Manager+ (зависит от модуля)

Параметры пути:

Параметр	Тип	Описание
module	string	Идентификатор модуля (cfo, reputation, watcher, content_factory, marketing, scout, knowledge, lex, logistic)

Пример ответа:

json

{
  "module": "logistic",
  "version": "1.0",
  "title": "Логистика",
  "description": "Оптимизация распределения товаров по складам WB",
  "icon": "truck",
  "color": "#14B8A6",
  "banners": [
    {
      "id": "stocks_overview",
      "title": "Остатки на складах",
      "description": "Текущие остатки по всем складам Wildberries",
      "icon": "package",
      "action": "stocks_overview",
      "enabled": true,
      "badge": null
    },
    {
      "id": "critical_stocks",
      "title": "Критические остатки",
      "description": "SKU с остатками ниже порога",
      "icon": "alert-triangle",
      "action": "critical_stocks",
      "enabled": true,
      "badge": {
        "type": "count",
        "source": "alerts_critical"
      }
    }
  ],
  "quick_actions": [
    {
      "id": "sync_stocks",
      "title": "Обновить остатки",
      "icon": "refresh-cw",
      "action": "sync_stocks"
    }
  ]
}

15.2 Выполнение действия

POST /launcher/execute

Выполнение действия баннера.

Доступ: Manager+ (зависит от модуля)

Тело запроса:

json

{
  "module": "logistic",
  "action": "stocks_overview",
  "banner_id": "stocks_overview"
}

Пример ответа:

json

{
  "success": true,
  "action": "stocks_overview",
  "title": "Остатки на складах",
  "data": {
    "warehouses": [
      {
        "name": "Коледино",
        "total_sku": 450,
        "critical_count": 12,
        "warning_count": 35
      }
    ],
    "summary": {
      "total_sku": 1000,
      "critical": 45,
      "warning": 120
    }
  },
  "timestamp": "2026-01-31T12:00:00Z"
}

Ошибка:

json

{
  "success": false,
  "error": "Module not found",
  "timestamp": "2026-01-31T12:00:00Z"
}

15.3 Список модулей

GET /launcher/modules

Список доступных модулей для текущего пользователя.

Доступ: Все авторизованные

Пример ответа:

json

{
  "modules": [
    {
      "key": "reputation",
      "title": "Отзывы",
      "icon": "thumbs-up",
      "color": "#F97316",
      "badge_count": 15
    },
    {
      "key": "watcher",
      "title": "Мониторинг цен",
      "icon": "eye",
      "color": "#EF4444",
      "badge_count": 0
    },
    {
      "key": "logistic",
      "title": "Логистика",
      "icon": "truck",
      "color": "#14B8A6",
      "badge_count": 12
    }
  ]
}

16. Office — Дашборд AI-агентов

> Версия: 1.0
> Назначение: Визуальный мониторинг состояния AI-агентов системы

16.1 Чтение (Dashboard)

GET /office/agents

Все агенты, сгруппированные по модулям (отделам).

Доступ: Director+ (Administrator видит все, Director — только свой бренд)

Query параметры:

Параметр	Тип	Описание
brand	string	Фильтр по бренду (для Director — обязателен)

Пример ответа:

json

{
  "departments": [
    {
      "key": "watcher",
      "name": "Watcher",
      "color": "#4A90D9",
      "agents": [
        {
          "id": "watcher_price_monitor",
          "name": "Мониторинг цен",
          "brand": "ohana_market",
          "status": "ok",
          "last_activity": "2026-01-31T14:32:15Z",
          "task": "Сканирование Wildberries",
          "metrics": {
            "products_monitored": 230,
            "price_changes_today": 15
          },
          "salary_equivalent": 60000,
          "fte_coefficient": 1.0
        },
        {
          "id": "watcher_night_agent",
          "name": "Ночной агент",
          "brand": "ohana_market",
          "status": "offline",
          "last_activity": "2026-01-31T03:15:00Z",
          "task": null,
          "metrics": {},
          "salary_equivalent": 60000,
          "fte_coefficient": 0.5
        }
      ]
    },
    {
      "key": "reputation",
      "name": "Reputation",
      "color": "#7ED321",
      "agents": []
    }
  ],
  "total_agents": 12,
  "total_savings": 480000,
  "updated_at": "2026-01-31T14:35:00Z"
}

GET /office/agents/{agent_id}

Детальный статус одного агента.

Доступ: Director+

Параметры пути:

Параметр	Тип	Описание
agent_id	string	Уникальный идентификатор агента

Пример ответа:

json

{
  "id": "watcher_price_monitor",
  "department": "watcher",
  "name": "Мониторинг цен",
  "brand": "ohana_market",
  "status": "ok",
  "last_activity": "2026-01-31T14:32:15Z",
  "task": "Сканирование Wildberries",
  "metrics": {
    "products_monitored": 230,
    "price_changes_today": 15
  },
  "salary_equivalent": 60000,
  "fte_coefficient": 1.0,
  "created_at": "2026-01-20T10:00:00Z",
  "updated_at": "2026-01-31T14:32:15Z"
}

GET /office/history/{agent_id}

История статусов агента за 24 часа.

Доступ: Director+

Query параметры:

Параметр	Тип	По умолчанию	Описание
limit	int	100	Количество записей

Пример ответа:

json

{
  "agent_id": "watcher_price_monitor",
  "history": [
    {
      "status": "ok",
      "task": "Сканирование Wildberries",
      "metrics": {
        "products_monitored": 230,
        "price_changes_today": 15
      },
      "recorded_at": "2026-01-31T14:32:15Z"
    },
    {
      "status": "ok",
      "task": "Ожидание",
      "metrics": {
        "products_monitored": 230,
        "price_changes_today": 14
      },
      "recorded_at": "2026-01-31T14:30:00Z"
    }
  ]
}

16.2 Запись (для агентов)

PUT /office/agents/{agent_id}

Регистрация или обновление статуса агента (UPSERT).

Доступ: Agent API Key

Параметры пути:

Параметр	Тип	Описание
agent_id	string	Уникальный идентификатор агента

Тело запроса:

json

{
  "department": "watcher",
  "name": "Ночной агент",
  "brand": "ohana_market",
  "status": "ok",
  "task": "Сканирование цен конкурентов",
  "metrics": {
    "products_scanned": 1250,
    "price_changes_found": 23
  },
  "salary_equivalent": 60000,
  "fte_coefficient": 0.5
}

Пример ответа:

json

{
  "success": true,
  "created": false,
  "updated_at": "2026-01-31T14:32:15Z"
}

POST /office/heartbeat/{agent_id}

Обновление last_activity без изменения статуса.

Доступ: Agent API Key

Пример ответа:

json

{
  "success": true,
  "last_activity": "2026-01-31T14:35:00Z"
}

16.3 Статусы агентов

status	task	Визуализация	Описание
ok	есть	💡 Зелёный	Активно работает
ok	null	⏸️ Зелёный	Ожидает задачу
warning	любой	⚠️ Жёлтый	Требует внимания
error	любой	🛑 Красный	Произошла ошибка
offline	—	💤 Серый	Нет связи с агентом

17. Logistic — Управление логистикой

> Версия: 1.0
> Назначение: Оптимизация распределения товаров по складам WB, минимизация кросс-докинга

17.1 Остатки

GET /logistic/stocks

Текущие остатки по всем складам.

Доступ: Manager+ (фильтрация по brand_id)

Query параметры:

Параметр	Тип	Описание
sku	string	Фильтр по артикулу
warehouse_id	int	Фильтр по складу
status	string	`critical`, `warning`, `normal`
brand_id	string	Фильтр по бренду

Пример ответа:

json

{
  "items": [
    {
      "sku": "OM-12345",
      "barcode": "2000000000001",
      "product_name": "Платье летнее, размер 44",
      "brand_id": "ohana_market",
      "warehouses": [
        {
          "warehouse_id": 507,
          "warehouse_name": "Коледино",
          "quantity": 45,
          "in_way_to_client": 3,
          "in_way_from_client": 1,
          "status": "normal"
        },
        {
          "warehouse_id": 1733,
          "warehouse_name": "Краснодар",
          "quantity": 8,
          "in_way_to_client": 2,
          "in_way_from_client": 0,
          "status": "warning"
        }
      ],
      "total_quantity": 53,
      "threshold_critical": 10,
      "threshold_warning": 30
    }
  ],
  "total": 450,
  "updated_at": "2026-01-31T14:30:00Z"
}

GET /logistic/stocks/{sku}

Детальные остатки по артикулу.

Доступ: Manager+

Пример ответа:

json

{
  "sku": "OM-12345",
  "barcode": "2000000000001",
  "product_name": "Платье летнее, размер 44",
  "brand_id": "ohana_market",
  "warehouses": [
    {
      "warehouse_id": 507,
      "warehouse_name": "Коледино",
      "quantity": 45,
      "in_way_to_client": 3,
      "in_way_from_client": 1,
      "status": "normal",
      "avg_daily_sales": 8.5,
      "days_of_stock": 5.3
    }
  ],
  "history": [
    {
      "date": "2026-01-30",
      "total_quantity": 60
    },
    {
      "date": "2026-01-31",
      "total_quantity": 53
    }
  ],
  "threshold_critical": 10,
  "threshold_warning": 30
}

17.2 Кросс-докинг

GET /logistic/cross-docking

Отчёт по кросс-докингу за период.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
date_from	date	Начало периода (YYYY-MM-DD)
date_to	date	Конец периода (YYYY-MM-DD)
brand_id	string	Фильтр по бренду
sku	string	Фильтр по артикулу

Пример ответа:

json

{
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "summary": {
    "total_orders": 1247,
    "cross_dock_orders": 47,
    "cross_dock_percent": 3.8,
    "additional_costs": 12400.00,
    "currency": "RUB"
  },
  "by_sku": [
    {
      "sku": "OM-12345",
      "product_name": "Платье летнее, размер 44",
      "cross_dock_count": 12,
      "additional_costs": 3200.00
    },
    {
      "sku": "OM-67890",
      "product_name": "Блузка шелковая, размер 46",
      "cross_dock_count": 8,
      "additional_costs": 2100.00
    }
  ],
  "by_route": [
    {
      "from_warehouse": "Новосибирск",
      "to_region": "Москва",
      "count": 15,
      "avg_additional_cost": 280.00
    }
  ]
}

GET /logistic/cross-docking/events

Список событий кросс-докинга.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
date_from	date	Начало периода
date_to	date	Конец периода
sku	string	Фильтр по артикулу
offset	int	Смещение
limit	int	Количество (макс. 100)

Пример ответа:

json

{
  "items": [
    {
      "id": 12345,
      "order_id": "WB-123456789",
      "order_date": "2026-01-31T10:30:00Z",
      "sku": "OM-12345",
      "product_name": "Платье летнее, размер 44",
      "customer_region": "Москва",
      "warehouse_actual": "Новосибирск",
      "warehouse_optimal": "Коледино",
      "tariff_actual": 280.00,
      "tariff_optimal": 50.00,
      "additional_cost": 230.00
    }
  ],
  "total": 47,
  "offset": 0,
  "limit": 20
}

17.3 Рекомендации

POST /logistic/recommendations

Генерация рекомендации по распределению поставки.

Доступ: Manager+

Тело запроса:

json

{
  "sku": "OM-12345",
  "quantity": 500
}

Пример ответа:

json

{
  "sku": "OM-12345",
  "product_name": "Платье летнее, размер 44",
  "total_quantity": 500,
  "distribution": [
    {
      "warehouse_id": 507,
      "warehouse_name": "Коледино",
      "quantity": 200,
      "percent": 40,
      "reason": "Основной спрос ЦФО",
      "acceptance_coefficient": 0,
      "current_stock": 45
    },
    {
      "warehouse_id": 1733,
      "warehouse_name": "Краснодар",
      "quantity": 120,
      "percent": 24,
      "reason": "Высокий спрос ЮФО",
      "acceptance_coefficient": 1.5,
      "current_stock": 8
    },
    {
      "warehouse_id": 2737,
      "warehouse_name": "Казань",
      "quantity": 100,
      "percent": 20,
      "reason": "Покрытие ПФО",
      "acceptance_coefficient": 0,
      "current_stock": 0
    },
    {
      "warehouse_id": 686,
      "warehouse_name": "Новосибирск",
      "quantity": 80,
      "percent": 16,
      "reason": "Покрытие СФО/УФО",
      "acceptance_coefficient": 2.0,
      "current_stock": 12
    }
  ],
  "forecast": {
    "expected_cross_dock_percent": 1.8,
    "estimated_savings_monthly": 8500.00
  },
  "warnings": [
    "Краснодар: коэффициент приёмки 1.5x",
    "Новосибирск: коэффициент приёмки 2.0x"
  ],
  "generated_at": "2026-01-31T12:00:00Z"
}

17.4 Алерты

GET /logistic/alerts

Список активных алертов логистики.

Доступ: Manager+

Query параметры:

Параметр	Тип	Описание
type	string	`critical_stock`, `cross_dock`, `imbalance`
is_read	bool	Фильтр по прочитанности
brand_id	string	Фильтр по бренду

Пример ответа:

json

{
  "items": [
    {
      "id": 1,
      "type": "critical_stock",
      "severity": "high",
      "sku": "OM-12345",
      "product_name": "Платье летнее, размер 44",
      "warehouse_name": "Коледино",
      "current_stock": 3,
      "threshold": 10,
      "avg_daily_sales": 8,
      "days_to_zero": 0.4,
      "message": "Критический остаток: обнуление через 9 часов",
      "recommended_action": "Срочная поставка или перемещение со склада Новосибирск (остаток 45 шт)",
      "created_at": "2026-01-31T10:00:00Z",
      "is_read": false
    }
  ],
  "total": 12,
  "unread": 5
}

POST /logistic/alerts/{id}/read

Отметить алерт как прочитанный.

Доступ: Manager+

17.5 Склады

GET /logistic/warehouses

Справочник складов WB с тарифами.

Доступ: Manager+

Пример ответа:

json

{
  "items": [
    {
      "warehouse_id": 507,
      "name": "Коледино",
      "region": "Москва",
      "acceptance_coefficient": 0,
      "base_tariff": 50.00,
      "optimal_regions": ["Москва", "Московская область", "Тула"]
    }
  ],
  "updated_at": "2026-01-31T06:00:00Z"
}

17.6 Настройки

GET /logistic/settings

Настройки порогов алертов.

Доступ: Senior+

Пример ответа:

json

{
  "thresholds": {
    "critical_stock": 10,
    "warning_stock": 30,
    "cross_dock_alert_min_loss": 100.00
  },
  "sync_intervals": {
    "stocks_minutes": 30,
    "orders_minutes": 30,
    "tariffs_hours": 24
  }
}

PUT /logistic/settings

Обновление настроек.

Доступ: Administrator

Тело запроса:

json

{
  "thresholds": {
    "critical_stock": 5,
    "warning_stock": 20
  }
}

18. Shop — Интернет-магазин (WooCommerce)

> Важно: Модуль Shop не имеет собственных REST API endpoints.
> Все данные получаются через WooCommerce MCP напрямую из Open WebUI.

18.1 Архитектура

User → Open WebUI → Claude + MCP Tools → WooCommerce MCP Server → ohana.market

18.2 Доступные MCP Tools

Tool	Описание
`woocommerce/orders-list`	Список заказов с фильтрацией
`woocommerce/orders-get`	Детали заказа по ID
`woocommerce/products-list`	Список товаров
`woocommerce/products-get`	Детали товара по ID

18.3 Celery Tasks

Фоновые задачи модуля Shop используют MCP для polling:

Задача	Периодичность	Описание
`shop.poll_orders`	1 минута	Проверка новых заказов
`shop.detect_events`	По событию	Выявление отмен, возвратов
`shop.send_notification`	По событию	Отправка уведомления

18.4 События уведомлений

Событие	Уровень	Получатели
`shop.order.new`	info	Senior+
`shop.order.cancelled`	warning	Senior+
`shop.order.refunded`	warning	Senior+
`shop.order.failed`	error	Senior+

Приложение A: Количество endpoints по модулям

Модуль	Endpoints	Примечание
Служебные	4	Health, Metrics, Tasks
Auth	4	Session, API Keys
Knowledge	4	Search, Product, Documents
Reputation	9	Items, Bulk, Analytics
Watcher	28	Sellers, Scans, Products, Files, Pool, Tasks, Stats, Monitor API
Content Factory	7	Generate, Drafts, Publish
Marketing	12	Campaigns, Keywords, Bids, Stats
Scout	3	Analyze, Analyses
CFO	6	P&L, ABC, Insights, Costs
Lex	6	Documents, Alerts, Keywords, Stats
Notifications	4	List, Read, WebSocket
Webhooks	1	Alerts
Chat	1	Completions
Launcher	3	Config, Execute, Modules
Office	5	Agents, History, Heartbeat
Logistic	10	Stocks, Cross-docking, Recommendations, Alerts, Warehouses, Settings
Shop	0	Работает через MCP
Итого	107

Приложение B: Матрица доступа по ролям

Endpoint Group	Staff	Manager	Senior	Director	Admin
Health	✅	✅	✅	✅	✅
Health Detailed	❌	❌	❌	❌	✅
Metrics	❌	❌	❌	❌	✅
Auth	✅	✅	✅	✅	✅
Knowledge Search	✅	✅	✅	✅	✅
Knowledge Docs	❌	❌	✅	✅	✅
Reputation	❌	Бренд	✅	✅	✅
Watcher	❌	✅	✅	✅	✅
Content Factory	❌	❌	✅	✅	✅
Marketing	❌	Бренд	✅	✅	✅
Scout	❌	❌	✅	✅	✅
CFO Basic	❌	❌	✅	✅	✅
CFO Full	❌	❌	❌	✅	✅
Lex	❌	✅	✅	✅	✅
Notifications	✅	✅	✅	✅	✅
Chat	✅	✅	✅	✅	✅
Launcher	❌	Модуль	Модуль	Модуль	✅
Office	❌	❌	❌	Бренд	✅
Logistic	❌	Бренд	✅	✅	✅

Приложение C: Конфигурации Launcher

Файл	Модуль	Описание
`cfo.json`	CFO	Финансовые отчёты
`reputation.json`	Reputation	Работа с отзывами
`watcher.json`	Watcher	Мониторинг цен
`content_factory.json`	Content Factory	Генерация контента
`marketing.json`	Marketing	Рекламные кампании
`scout.json`	Scout	Аналитика ниш
`knowledge.json`	Knowledge	База знаний
`lex.json`	Lex	Правовой мониторинг
`logistic.json`	Logistic	Логистика

Документ подготовлен: Январь 2026
Версия: 1.1
Статус: Актуальная версия
Заменяет: adolf_fastapi_reference_v1_0.md

FastAPI Reference ​

Изменения версии 1.2 ​

Изменения версии 1.1 ​

1. Общие сведения ​

1.1 Базовая информация ​

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

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

1.4 Стандартные HTTP-коды ​

1.5 Пагинация ​

2. Служебные Endpoints ​

2.1 Health Check ​

GET /health ​

GET /health/detailed ​

2.2 Метрики ​

GET /metrics ​

2.3 Celery Tasks ​

GET /tasks/{task_id} ​

3. Auth — Аутентификация ​

3.1 Сессия ​

GET /auth/session ​

3.2 API ключи ​

GET /auth/api-keys ​

POST /auth/api-keys ​

DELETE /auth/api-keys/{key_id} ​

4. Knowledge — База знаний ​

4.1 Поиск ​

POST /knowledge/search ​

4.2 Информация о товаре ​

GET /knowledge/product/{sku} ​

4.3 Документы ​

GET /knowledge/documents ​

POST /knowledge/documents/{id}/approve ​

5. Reputation — Управление отзывами ​

5.1 Элементы (отзывы/вопросы) ​

GET /reputation/items ​

GET /reputation/items/{id} ​

POST /reputation/items/{id}/approve ​

POST /reputation/items/{id}/edit ​

POST /reputation/items/{id}/regenerate ​

5.2 Массовые операции ​

POST /reputation/items/bulk-approve ​

5.3 Аналитика ​

GET /reputation/stats ​

GET /reputation/analytics ​

6. Watcher — Мониторинг продавцов ​

6.1 Продавцы (Sellers) ​

GET /sellers ​

GET /sellers/{id} ​

POST /sellers ​

PUT /sellers/{id} ​

DELETE /sellers/{id} ​

GET /sellers/{id}/products ​

GET /sellers/{id}/enriched ​

GET /sellers/{id}/diff ​

6.2 Сканирование (Scans) ​

GET /scans ​

GET /scans/{id} ​

POST /scans ​

POST /enrichments ​

6.3 Товары и история цен (Products) ​

GET /products/{sku} ​

GET /products/{sku}/enriched ​

GET /products/{sku}/history ​

6.4 Файлы результатов ​

GET /files/catalog ​

GET /files/enriched ​

GET /files/{type}/{filename} ​

6.5 CDP Pool API ​

GET /pool/status ​

GET /pool/summary ​

6.6 Задачи и статистика ​

GET /tasks ​

GET /stats ​

6.7 Monitor Web UI API ​

GET /api/agents ​

GET /api/summary ​

GET /api/config ​

PUT /api/config ​

GET /api/sellers ​

POST /api/sellers ​

FastAPI Reference

Изменения версии 1.2

Изменения версии 1.1

1. Общие сведения

1.1 Базовая информация

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

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

1.4 Стандартные HTTP-коды

1.5 Пагинация

2. Служебные Endpoints

2.1 Health Check

GET /health

GET /health/detailed

2.2 Метрики

GET /metrics

2.3 Celery Tasks

GET /tasks/{task_id}

3. Auth — Аутентификация

3.1 Сессия

GET /auth/session

3.2 API ключи

GET /auth/api-keys

POST /auth/api-keys

DELETE /auth/api-keys/{key_id}

4. Knowledge — База знаний

4.1 Поиск

POST /knowledge/search

4.2 Информация о товаре

GET /knowledge/product/{sku}

4.3 Документы

GET /knowledge/documents

POST /knowledge/documents/{id}/approve

5. Reputation — Управление отзывами

5.1 Элементы (отзывы/вопросы)

GET /reputation/items

GET /reputation/items/{id}

POST /reputation/items/{id}/approve

POST /reputation/items/{id}/edit

POST /reputation/items/{id}/regenerate

5.2 Массовые операции

POST /reputation/items/bulk-approve

5.3 Аналитика

GET /reputation/stats

GET /reputation/analytics

6. Watcher — Мониторинг продавцов

6.1 Продавцы (Sellers)

GET /sellers

GET /sellers/{id}

POST /sellers

PUT /sellers/{id}

DELETE /sellers/{id}

GET /sellers/{id}/products

GET /sellers/{id}/enriched

GET /sellers/{id}/diff

6.2 Сканирование (Scans)

GET /scans

GET /scans/{id}

POST /scans

POST /enrichments

6.3 Товары и история цен (Products)

GET /products/{sku}

GET /products/{sku}/enriched

GET /products/{sku}/history

6.4 Файлы результатов

GET /files/catalog

GET /files/enriched

GET /files/{type}/{filename}

6.5 CDP Pool API

GET /pool/status

GET /pool/summary

6.6 Задачи и статистика

GET /tasks

GET /stats

6.7 Monitor Web UI API

GET /api/agents

GET /api/summary

GET /api/config

PUT /api/config

GET /api/sellers

POST /api/sellers