FastAPI Reference - ADOLF Platform

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

Изменения версии 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 Формат ошибок

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

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

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

1.5 Пагинация

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

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

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

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

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

2.1 Health Check

GET /health

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

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

GET /health/detailed

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

{
  "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 задачи

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

{
  "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

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

{
  "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 ключа. Доступ: Все авторизованные Тело запроса:

{
  "name": "New Integration Key"
}

DELETE /auth/api-keys/{key_id}

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

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

4.1 Поиск

POST /knowledge/search

Семантический поиск по базе знаний. Доступ: Все авторизованные Тело запроса:

{
  "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 — Мониторинг цен

6.1 Конкуренты

GET /watcher/competitors

Список отслеживаемых конкурентов. Доступ: Manager+

POST /watcher/competitors

Добавление конкурента. Доступ: Senior+

6.2 Цены

GET /watcher/prices

История цен с фильтрами. Доступ: Manager+

GET /watcher/prices/comparison

Сравнение с конкурентами. Доступ: Manager+

6.3 Алерты

GET /watcher/alerts

Алерты о изменениях цен. Доступ: Manager+

6.4 Agent API

GET /watcher/tasks/next

Получение задачи агентом. Доступ: Agent API Key

POST /watcher/tasks/{task_id}/report

Отправка результата задачи. Доступ: Agent API Key

POST /watcher/agents/heartbeat

Проверка состояния агента. Доступ: Agent API Key

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)

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

{
  "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+ (зависит от модуля) Тело запроса:

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

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

{
  "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"
}

Ошибка:

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

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

GET /launcher/modules

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

{
  "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 — обязателен)

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

{
  "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	Уникальный идентификатор агента

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

{
  "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	Количество записей

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

{
  "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	Уникальный идентификатор агента

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

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

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

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

POST /office/heartbeat/{agent_id}

Обновление last_activity без изменения статуса. Доступ: Agent API Key Пример ответа:

{
  "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	Фильтр по бренду

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

{
  "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+ Пример ответа:

{
  "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	Фильтр по артикулу

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

{
  "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)

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

{
  "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+ Тело запроса:

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

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

{
  "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	Фильтр по бренду

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

{
  "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+ Пример ответа:

{
  "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+ Пример ответа:

{
  "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 Тело запроса:

{
  "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	10	Competitors, Prices, Alerts, Agent 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
Итого	89

Приложение 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

Platform

​Изменения версии 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 Конкуренты

​GET /watcher/competitors

​POST /watcher/competitors

​6.2 Цены

​GET /watcher/prices

​GET /watcher/prices/comparison

​6.3 Алерты

​GET /watcher/alerts

​6.4 Agent API

​GET /watcher/tasks/next

​POST /watcher/tasks/{task_id}/report

​POST /watcher/agents/heartbeat

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

​7.1 Генерация

​POST /content/generate

​POST /content/generate/visual-prompt

​7.2 Черновики

​GET /content/drafts

​PUT /content/drafts/{id}

​POST /content/drafts/{id}/approve

​POST /content/drafts/{id}/publish

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

​8.1 Кампании

​GET /marketing/campaigns

​POST /marketing/campaigns

​PUT /marketing/campaigns/{id}

​POST /marketing/campaigns/{id}/pause

​POST /marketing/campaigns/{id}/resume

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

​GET /marketing/campaigns/{id}/keywords

​POST /marketing/campaigns/{id}/keywords

​8.3 Ставки

​PUT /marketing/bids

​GET /marketing/bids/recommendations

​8.4 Статистика

​GET /marketing/stats

Изменения версии 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 Конкуренты

GET /watcher/competitors

POST /watcher/competitors

6.2 Цены

GET /watcher/prices

GET /watcher/prices/comparison

6.3 Алерты

GET /watcher/alerts

6.4 Agent API

GET /watcher/tasks/next

POST /watcher/tasks/{task_id}/report

POST /watcher/agents/heartbeat

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

7.1 Генерация

POST /content/generate

POST /content/generate/visual-prompt

7.2 Черновики

GET /content/drafts

PUT /content/drafts/{id}

POST /content/drafts/{id}/approve

POST /content/drafts/{id}/publish

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

8.1 Кампании

GET /marketing/campaigns

POST /marketing/campaigns

PUT /marketing/campaigns/{id}

POST /marketing/campaigns/{id}/pause

POST /marketing/campaigns/{id}/resume

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

GET /marketing/campaigns/{id}/keywords

POST /marketing/campaigns/{id}/keywords

8.3 Ставки

PUT /marketing/bids

GET /marketing/bids/recommendations

8.4 Статистика

GET /marketing/stats

GET /marketing/reports/daily