API Документация

Полная документация по API Document Processor

Base URL

http://localhost:8080/api

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

API Keys (dp_live_...)

Долгоживущие ключи для серверных интеграций. Генерируются через админ-панель. Не имеют срока действия, пока не будут отозваны.

JWT Tokens

Короткоживущие токены (24 часа). Получаются обменом API-ключа через POST /auth/token. Используются для сессий и фронтенд-клиентов.

Передавайте токен в заголовке:

Authorization: Bearer <token>

Обработка документов

Auth: None / API Key Content-Type: multipart/form-data

Загружает файл и запускает обработку. В синхронном режиме возвращает результат напрямую (200), в асинхронном — task_id (202).

Content-Type: multipart/form-data

file: (binary)        # Required. The document file
hint: "price list"    # Optional. Processing hint

// 200 OK (synchronous)
{
  "type": "PDF",
  "text": ["paragraph 1", "paragraph 2"],
  "tables": [
    {
      "source": "Sheet1",
      "columns": ["Name", "Value"],
      "data": [{"Name": "A", "Value": "1"}],
      "column_descriptions": {}
    }
  ],
  "metadata": {"page_count": 3, "author": "..."},
  "hash": "sha256:abc123...",
  "s3_key": "documents/abc123.pdf",
  "from_cache": false
}

// 202 Accepted (async)
{
  "task_id": "abc-123-def",
  "status": "queued",
  "queue_info": {
    "queue_position": 3,
    "estimated_wait_seconds": 12.5
  }
}

Auth: None / API Key Content-Type: application/json

Обрабатывает документ по пути на сервере. Полезно для интеграций, когда файл уже доступен на диске или в S3.

{
  "file_path": "/data/documents/invoice.pdf",
  "hint": "invoice"
}

{
  "type": "PDF",
  "text": ["..."],
  "tables": [],
  "metadata": {},
  "hash": "sha256:...",
  "from_cache": false
}

Auth: None / API Key Content-Type: multipart/form-data

Пакетная загрузка нескольких файлов за один запрос. Лимит зависит от плана (Free: 5, Enterprise: 10).

Content-Type: multipart/form-data

files[]: (binary)     # Required. Multiple files
hint: "invoices"      # Optional. Hint for all files

{
  "total_files": 3,
  "results": [
    {
      "file_name": "doc1.pdf",
      "status": "completed",
      "result": { "type": "PDF", "text": [...], ... }
    },
    {
      "file_name": "doc2.xlsx",
      "status": "accepted",
      "task_id": "abc-123"
    },
    {
      "file_name": "bad.txt",
      "status": "error",
      "error": "Unsupported file type"
    }
  ]
}

Auth: None

Проверяет статус асинхронной задачи. Используйте для polling при получении 202 ответа.

// PENDING
{
  "status": "PENDING",
  "queue_info": {
    "queue_position": 2,
    "estimated_wait_seconds": 8.0
  }
}

// SUCCESS
{
  "status": "SUCCESS",
  "result": { "type": "PDF", "text": [...], ... }
}

// FAILURE
{
  "status": "FAILURE",
  "error": "Processing failed: corrupt file"
}

Auth: None

Возвращает текущую статистику очереди задач.

{
  "total_in_queue": 5,
  "estimated_wait_seconds": 20.0,
  "sync_mode": false
}

Auth: None WebSocket

WebSocket-соединение для получения обновлений статуса задачи в реальном времени. Альтернатива polling.

const ws = new WebSocket('ws://localhost:8080/api/ws/task/abc-123');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.status);  // PENDING | STARTED | SUCCESS | FAILURE
  if (data.status === 'SUCCESS') {
    console.log(data.result);
    ws.close();
  }
};

// Progress update
{
  "status": "STARTED",
  "queue_info": { "queue_position": 0 }
}

// Completion
{
  "status": "SUCCESS",
  "result": { "type": "PDF", "text": [...], ... }
}

// Error
{
  "status": "FAILURE",
  "error": "Out of memory"
}

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

Auth: None (API key in body)

Обменивает API-ключ на короткоживущий JWT-токен (24 часа).

{
  "api_key": "dp_live_abc123def456..."
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400
}

Биллинг

Auth: API Key / JWT

Возвращает текущую статистику использования, лимиты плана и историю за прошлые месяцы.

{
  "plan": "starter",
  "current_month": {
    "year_month": "2025-02",
    "used": 142,
    "limit": 5000,
    "remaining": 4858
  },
  "plan_limits": {
    "requests_per_month": 5000,
    "requests_per_minute": 30,
    "max_file_size_mb": 25,
    "batch_size": 5
  },
  "history": [
    {
      "year_month": "2025-01",
      "request_count": 312,
      "bytes_processed": 52428800
    }
  ]
}

Auth: None

Возвращает список доступных тарифных планов с лимитами и ценами.

{
  "plans": {
    "free": {
      "label": "Free",
      "requests_per_month": 100,
      "requests_per_minute": 5,
      "max_file_size_mb": 10,
      "batch_size": 2,
      "price_monthly_usd": 0
    },
    "starter": { ... },
    "pro": { ... },
    "enterprise": { ... }
  }
}

Администрирование Admin Token Required

Auth: Admin Token

Создает новый API-ключ с указанным планом и владельцем.

{
  "owner": "acme-corp",
  "plan": "pro",
  "expires_days": 365
}

{
  "api_key": "dp_live_abc123def456ghi789...",
  "owner": "acme-corp",
  "plan": "pro",
  "created_at": "2025-02-18T10:30:00Z",
  "expires_at": "2026-02-18T10:30:00Z"
}

Auth: Admin Token

Отзывает (деактивирует) указанный API-ключ. Немедленно прекращает доступ.

{
  "api_key": "dp_live_abc123def456..."
}

{
  "status": "revoked",
  "api_key": "dp_live_abc1...6789"
}

Auth: Admin Token

Генерирует новый ключ, отзывая старый. Сохраняет владельца и план.

{
  "api_key": "dp_live_old_key..."
}

{
  "old_key": "dp_live_old_...",
  "new_key": "dp_live_new_abc123...",
  "owner": "acme-corp",
  "plan": "pro"
}

Auth: Admin Token

Возвращает список всех API-ключей с информацией о владельце, плане и статусе.

{
  "keys": [
    {
      "key_prefix": "dp_live_abc1...6789",
      "owner": "acme-corp",
      "plan": "pro",
      "is_active": true,
      "created_at": "2025-01-15T08:00:00Z",
      "expires_at": "2026-01-15T08:00:00Z",
      "last_used_at": "2025-02-17T14:22:00Z"
    }
  ]
}

Auth: Admin Token

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

{
  "total_keys": 12,
  "active_keys": 10,
  "total_requests_today": 456,
  "total_requests_month": 8923,
  "plans_distribution": {
    "free": 5, "starter": 3, "pro": 3, "enterprise": 1
  }
}

Auth: Admin Token

Журнал аудита всех административных действий.

Query parameters:

page - Page number (default: 1)
per_page - Items per page (default: 50)
event - Filter by event type

{
  "logs": [
    {
      "id": 42,
      "timestamp": "2025-02-18T10:30:00Z",
      "event": "key_created",
      "actor": "admin",
      "details": {"owner": "acme-corp", "plan": "pro"},
      "ip_address": "192.168.1.100"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 128
}

Системные

Auth: None

Проверка здоровья сервиса. Используйте для мониторинга и load balancer health checks.

{
  "status": "ok",
  "version": "3.0"
}

Auth: None

Экспорт метрик в формате Prometheus. Подключается к Grafana или другим системам мониторинга.

# HELP doc_processor_requests_total Total requests
# TYPE doc_processor_requests_total counter
doc_processor_requests_total{method="POST",endpoint="/process-document"} 1234

# HELP doc_processor_processing_seconds Processing duration
# TYPE doc_processor_processing_seconds histogram
doc_processor_processing_seconds_bucket{le="1.0"} 800
...

Auth: Admin Token

Очищает кеш обработанных документов. Следующие запросы будут обрабатываться заново.

{
  "status": "ok",
  "purged": 47
}

Коды ошибок

Код	Статус	Описание
200	Success	Запрос выполнен успешно
202	Accepted	Задача принята в обработку (асинхронный режим). Используйте task_id для отслеживания.
400	Bad Request	Некорректный запрос (отсутствует файл, неподдерживаемый формат, и т.д.)
401	Unauthorized	Отсутствует или недействительный токен аутентификации
403	Forbidden	Недостаточно прав (требуется админ-токен)
429	Rate Limited	Превышен лимит запросов. Подождите или обновите план.
500	Internal Error	Внутренняя ошибка сервера. Повторите позже или обратитесь к администратору.

Лимиты по планам

План	Запросов/мес	Запросов/мин	Макс. файл	Пакет	Цена
Free	100	5	10 MB	2 files	$0
Starter	5,000	30	25 MB	5 files	$29/mo
Pro	50,000	120	50 MB	5 files	$99/mo
Enterprise	500,000	600	100 MB	10 files	$499/mo