API эндпоинты¶

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

Общая схема¶

Аутентификация реализована по схеме с внешним сервисом авторизации заказчика и проксированием запросов. Без прохождения аутентификации доступ к сервису невозможен.

┌──────────────────┐    redirect + JWT     ┌──────────────────┐
│ Сервис авторизации│ ──────────────────→  │    Frontend      │
│ заказчика        │   (ограниченный       │                  │
└──────────────────┘    набор данных)      └────────┬─────────┘
                                                    │
                                            запрос + JWT клиента
                                                    │
                                                    ▼
                                           ┌──────────────────┐
                                           │  Прокси заказчика│
                                           │  (валидация JWT) │
                                           └────────┬─────────┘
                                                    │
                                           подмена на статический токен
                                                    │
                                                    ▼
                                           ┌──────────────────┐
                                           │    Backend       │
                                           │  (проверка       │
                                           │  статического    │
                                           │  токена)         │
                                           └──────────────────┘

Поток аутентификации¶

Выдача JWT — клиентский сервис авторизации заказчика генерирует JWT-токен с ограниченным набором данных о клиенте (без полной информации).
Редирект на фронтенд — после успешной аутентификации пользователь перенаправляется на фронтенд платформы с полученным JWT-токеном.
Запрос через прокси — фронтенд отправляет все API-запросы через прокси заказчика, передавая JWT-токен в заголовке Authorization.
Валидация на прокси — прокси заказчика проверяет валидность JWT-токена (подпись, срок действия, данные клиента).
Подмена токена — при успешной валидации прокси заменяет клиентский JWT на статический токен (AUTH_PROXY_STATIC_TOKEN) и перенаправляет запрос на backend.
Проверка на backend — backend проверяет наличие и корректность статического токена. Запросы без валидного токена отклоняются.

Компоненты авторизации¶

Компонент	Ответственность
Сервис авторизации заказчика	Аутентификация пользователей, выдача JWT с ограниченными данными
Прокси заказчика	Валидация клиентского JWT, подмена на статический токен
AuthMiddleware (backend)	Проверка статического токена, опциональная проверка IP whitelist

Дополнительные механизмы¶

IP Whitelist — опциональное ограничение по IP-адресам (AUTH_IP_WHITELIST).

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

GET /health
GET /ready
GET /metrics

Системные эндпоинты¶

Health Check¶

GET /health

Ответ (200):

{
  "status": "ok"
}

Readiness Check¶

GET /ready

Проверяет доступность Redis, OpenAI API и Qdrant.

Ответ (200):

{
  "status": "ready",
  "redis": "ok",
  "openai": "ok",
  "qdrant": "ok"
}

Метрики Prometheus¶

GET /metrics

Возвращает метрики в формате Prometheus (количество и латентность HTTP-запросов, метрики OpenAI и др.).

Чат и диалог¶

HTTP-чат¶

POST /api/conversation

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

{
  "message": "Сгенерируй ТЗ на поставку серверного оборудования",
  "types": ["tech"],
  "features": ["GOSTS"]
}

Ответ (200):

{
  "response": "...",
  "chapters": ["..."],
  "metadata": {}
}

Чат в контексте документа¶

POST /api/chat

Взаимодействие с TZAgent — AI-агентом, который имеет доступ к текущему документу и может модифицировать его структуру.

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

{
  "message": "Добавь раздел о гарантийных обязательствах",
  "document_context": {
    "chapters": ["..."],
    "characteristics": ["..."]
  }
}

WebSocket-чат¶

WebSocket /ws/chat

Потоковый обмен сообщениями в реальном времени. Поддерживает JSON и текстовые сообщения.

Управление задачами (Jobs)¶

Длительные операции (генерация полного ТЗ) выполняются асинхронно через систему задач.

Запуск задачи¶

POST /api/jobs/start

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

{
  "message": "Поставка 10 серверов Dell PowerEdge R750 в Москву до 01.06.2026",
  "types": ["tech"],
  "features": ["RANGE", "GOSTS"]
}

Ответ (200):

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Info

Дедупликация: повторный запуск с теми же параметрами в течение 30 секунд вернёт тот же job_id.

Получение прогресса¶

GET /api/progress/{job_id}

Ответ (200):

{
  "job_id": "a1b2c3d4-...",
  "status": "running",
  "progress": 45,
  "stage": "chars",
  "message": "Генерация характеристик: 3/7"
}

Стадии выполнения:

Стадия	Доля прогресса	Описание
`parse_items`	10%	Извлечение позиций из описания
`chapters`	15%	Генерация глав документа
`chars`	50%	Генерация характеристик продукции
`fulfill`	5%	Заполнение дополнительных параметров
`cleanup`	5%	Очистка и нормализация данных
`spec_ch`	5%	Формирование спецификации
`assemble`	5%	Финальная сборка документа
`finish`	5%	Завершение

Получение результата¶

GET /api/jobs/{job_id}/result

Ответ (200):

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "result": {
    "chapters": [
      {
        "kind": "tech",
        "chapter_name": "Серверное оборудование",
        "item_name": "Сервер Dell PowerEdge R750",
        "okpd2": "26.20.14",
        "main_chars": [
          { "name": "Процессор", "value": "Intel Xeon Gold 6338 2.0GHz" },
          { "name": "Оперативная память", "value": "не менее 128 ГБ DDR4" }
        ],
        "dop_chars": ["..."]
      }
    ],
    "specification": {
      "items": ["..."],
      "total_price": 0
    }
  }
}

Редактирование¶

Редактирование ячейки¶

POST /api/edit

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

{
  "chapter_name": "Серверное оборудование",
  "description": {
    "name": "Процессор",
    "value": "Intel Xeon Gold 6338 2.0GHz"
  },
  "prompt": "Укажи диапазон допустимых частот от 2.0 до 3.2 GHz"
}

Ответ (200):

{
  "action": {
    "action_type": "update",
    "content": "Intel Xeon Gold 6338, тактовая частота от 2.0 до 3.2 GHz",
    "description": "Добавлен диапазон допустимых тактовых частот процессора"
  }
}

Редактирование таблицы¶

POST /api/edit-table

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

{
  "characteristics": [
    { "name": "Процессор", "value": "Intel Xeon Gold 6338" },
    { "name": "ОЗУ", "value": "128 ГБ" }
  ],
  "instruction": "Добавь характеристику 'Тип накопителя' со значением 'NVMe SSD не менее 1 ТБ'",
  "features": ["RANGE"]
}

Ответ (200):

{
  "result": [
    { "name": "Процессор", "value": "Intel Xeon Gold 6338" },
    { "name": "ОЗУ", "value": "128 ГБ" },
    { "name": "Тип накопителя", "value": "NVMe SSD не менее 1 ТБ" }
  ],
  "type": "modification"
}

Note

Если LLM определяет, что инструкция — это вопрос, а не команда на изменение, поле type будет "explanation", а result — текстовый ответ.

Инкрементальное обновление¶

POST /api/chapters/update-by-changes

Позволяет пересчитать затронутые главы при изменении параметров документа (например, замена товара, изменение количества).

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

{
  "changes": {
    "chapters[0].item_name": {
      "old": "Сервер Dell PowerEdge R750",
      "new": "Сервер HPE ProLiant DL380 Gen11"
    }
  },
  "content": { "chapters": ["..."] },
  "product_type": "tech",
  "history": []
}

Ответ (200):

{
  "updated_chapters": ["..."],
  "updated_characteristics": ["..."],
  "error": null
}

Подсказки ОКПД2¶

GET /api/suggest?query=серверное+оборудование

Автодополнение по классификатору ОКПД2.

Ответ (200):

{
  "suggestions": [
    { "code": "26.20.14", "name": "Серверы", "score": 0.89 },
    { "code": "26.20.15", "name": "Системы хранения данных", "score": 0.72 }
  ]
}

Rate limiting: 60 запросов/минуту, burst — 30 запросов.

Генерация главы по названию¶

POST /api/chapters/generate-from-title

Генерация содержимого отдельной главы по её названию в контексте всего документа.

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

{
  "chapter_title": "Требования к гарантийному обслуживанию",
  "document_context": { "chapters": ["..."] }
}