Skip to main content
> Версия: 1.0 (черновик)
> Статус: MVP
> Дата: 2025-01-24

​
Обзор

Два типа эндпоинтов:
  1. Чтение — Office Dashboard запрашивает статусы агентов
  2. Запись — агенты обновляют свой статус

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

API Key в заголовке X-API-Key. Ключи привязаны к ролям и агентам.

​
Эндпоинты чтения (для Dashboard)

​
GET /api/v1/office/agents

Все агенты, сгруппированные по модулям. Доступ: Administrator, Director Query параметры:
ПараметрТипОписание
brandstringФильтр по бренду (для Director — обязателен)
Ответ: 
{
  "departments": [
    {
      "key": "watcher",
      "name": "Watcher",
      "color": "#4A90D9",
      "agents": [
        {
          "id": "watcher_price_monitor",
          "name": "Мониторинг цен",
          "brand": "ohana_market",
          "status": "ok",
          "last_activity": "2025-01-24T14: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": "2025-01-24T03: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": "2025-01-24T14:35:00Z"
}

​
GET /api/v1/office/agents/{agent_id}

Детальный статус одного агента. Доступ: Administrator, Director Path параметры:
ПараметрТипОписание
agent_idstringУникальный идентификатор агента
Ответ: 
{
  "id": "watcher_price_monitor",
  "department": "watcher",
  "name": "Мониторинг цен",
  "brand": "ohana_market",
  "status": "ok",
  "last_activity": "2025-01-24T14:32:15Z",
  "task": "Сканирование Wildberries",
  "metrics": {
    "products_monitored": 230,
    "price_changes_today": 15
  },
  "salary_equivalent": 60000,
  "fte_coefficient": 1.0,
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-24T14:32:15Z"
}

​
GET /api/v1/office/history/{agent_id}

История статусов агента за 24 часа. Доступ: Administrator, Director Path параметры:
ПараметрТипОписание
agent_idstringУникальный идентификатор агента
Query параметры:
ПараметрТипОписание
limitintКоличество записей (default: 100)
Ответ: 
{
  "agent_id": "watcher_price_monitor",
  "history": [
    {
      "status": "ok",
      "current_task": "Сканирование Wildberries",
      "metrics": {
        "products_monitored": 230,
        "price_changes_today": 15
      },
      "recorded_at": "2025-01-24T14:32:15Z"
    },
    {
      "status": "ok",
      "current_task": "Ожидание",
      "metrics": {
        "products_monitored": 230,
        "price_changes_today": 14
      },
      "recorded_at": "2025-01-24T14:30:00Z"
    }
  ]
}

​
Эндпоинты записи (для агентов)

​
PUT /api/v1/office/agents/{agent_id}

Регистрация или обновление статуса агента (UPSERT). Доступ: API Key агента Path параметры:
ПараметрТипОписание
agent_idstringУникальный идентификатор агента
Тело запроса: 
{
  "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": "2025-01-24T14:32:15Z"
}
При первой регистрации created: true.

​
POST /api/v1/office/heartbeat/{agent_id}

Обновление last_activity без изменения статуса. Доступ: API Key агента Path параметры:
ПараметрТипОписание
agent_idstringУникальный идентификатор агента
Ответ: 
{
  "success": true,
  "last_activity": "2025-01-24T14:35:00Z"
}

​
Коды ошибок

КодОписание
400Неверные параметры запроса
401Отсутствует или неверный API Key
403Нет доступа (Director к чужому бренду)
404Агент не найден
500Внутренняя ошибка сервера
Формат ошибки: 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied to brand ohana_kids"
  }
}

​
Диаграмма взаимодействия

​
Права доступа

ЭндпоинтAdministratorDirectorАгент
GET /agents✓ все✓ свой бренд✗
GET /agents/{id}✓ все✓ свой бренд✗
GET /history/{id}✓ все✓ свой бренд✗
PUT /agents/{id}✗✗✓ свой agent_id
POST /heartbeat/{id}✗✗✓ свой agent_id