crm.clientright.ru/pdf_processor/API_DOCUMENTATION.md

📚 PDF Processor Microservice - API Документация

🚀 Быстрый старт

Base URL: http://147.45.146.17:8300

Аутентификация: Все POST endpoints требуют заголовок X-API-Key

---

📋 Endpoints

1. Health Check

GET /health

Ответ:

{
  "status": "healthy",
  "timestamp": "2025-12-29T12:00:00",
  "version": "1.0.0",
  "redis_connected": true
}

---

2. Синхронная обработка

POST /process
Headers:
  X-API-Key: your-api-key
Content-Type: application/json

Запрос:

{
  "data": {
    "files": [
      {
        "file": {
          "url": "https://example.com/document.pdf",
          "file_name": "document.pdf"
        }
      }
    ]
  },
  "mode": "--pdf-merge"
}

Ответ (успех):

{
  "success": true,
  "result": [
    {
      "group": "group_0",
      "session_token": "...",
      "pages": 5,
      "merged_base64": "JVBERi0xLjQKJeLjz9MK..."
    }
  ],
  "processing_time": 2.5,
  "logs": "..."
}

Ответ (ошибка):

{
  "success": false,
  "error": "Script execution failed",
  "processing_time": 1.2,
  "logs": "..."
}

---

3. Асинхронная обработка

POST /process/async
Headers:
  X-API-Key: your-api-key
Content-Type: application/json

Запрос: (тот же формат, что и синхронный)

Ответ:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Task created successfully",
  "status_url": "/process/status/550e8400-e29b-41d4-a716-446655440000"
}

Когда использовать:

• Большие файлы (> 10MB)
• Множественные файлы (> 5 файлов)
• Долгая обработка (> 30 секунд)

---

4. Проверка статуса задачи

GET /process/status/{task_id}
Headers:
  X-API-Key: your-api-key

Ответ (pending/processing):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2025-12-29T12:00:00",
  "updated_at": "2025-12-29T12:01:30",
  "result": null,
  "error": null,
  "processing_time": null,
  "logs": null
}

Ответ (completed):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-12-29T12:00:00",
  "updated_at": "2025-12-29T12:05:30",
  "result": [...],
  "processing_time": 330.5,
  "logs": "..."
}

Ответ (failed):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "created_at": "2025-12-29T12:00:00",
  "updated_at": "2025-12-29T12:02:15",
  "result": null,
  "error": "Script execution timed out",
  "processing_time": 300.0,
  "logs": "..."
}

Статусы:

• pending - Задача создана, ожидает обработки
• processing - Задача выполняется
• completed - Задача завершена успешно
• failed - Задача завершена с ошибкой

---

5. Метрики (JSON)

GET /metrics
Headers:
  X-API-Key: your-api-key

Ответ:

{
  "total_requests": 150,
  "successful_requests": 142,
  "failed_requests": 8,
  "async_tasks_created": 25,
  "async_tasks_completed": 23,
  "average_processing_time": 3.45,
  "errors_by_type": {
    "timeout": 3,
    "script_error": 4,
    "json_parse_error": 1
  }
}

---

6. Метрики (Prometheus)

GET /metrics/prometheus
Headers:
  X-API-Key: your-api-key
Accept: text/plain

Ответ:

# HELP pdf_processor_total_requests Total number of requests
# TYPE pdf_processor_total_requests counter
pdf_processor_total_requests 150

# HELP pdf_processor_successful_requests Number of successful requests
# TYPE pdf_processor_successful_requests counter
pdf_processor_successful_requests 142

...

---

🔧 Примеры использования

Python

import requests

API_URL = "http://147.45.146.17:8300"
API_KEY = "your-api-key"
headers = {"X-API-Key": API_KEY}

# Синхронная обработка
response = requests.post(
    f"{API_URL}/process",
    headers=headers,
    json={
        "data": {
            "files": [{
                "file": {
                    "url": "https://example.com/file.pdf",
                    "file_name": "document.pdf"
                }
            }]
        },
        "mode": "--pdf-merge"
    }
)
print(response.json())

# Асинхронная обработка
response = requests.post(
    f"{API_URL}/process/async",
    headers=headers,
    json={
        "data": {
            "files": [{
                "file": {
                    "url": "https://example.com/large-file.pdf",
                    "file_name": "large-document.pdf"
                }
            }]
        },
        "mode": "--pdf-merge"
    }
)
task_id = response.json()["task_id"]

# Проверка статуса
import time
while True:
    status_response = requests.get(
        f"{API_URL}/process/status/{task_id}",
        headers=headers
    )
    status = status_response.json()
    
    if status["status"] == "completed":
        print("Результат:", status["result"])
        break
    elif status["status"] == "failed":
        print("Ошибка:", status["error"])
        break
    
    time.sleep(2)  # Проверяем каждые 2 секунды

cURL

# Синхронная обработка
curl -X POST http://147.45.146.17:8300/process \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "files": [{
        "file": {
          "url": "https://example.com/file.pdf",
          "file_name": "document.pdf"
        }
      }]
    },
    "mode": "--pdf-merge"
  }'

# Асинхронная обработка
TASK_ID=$(curl -X POST http://147.45.146.17:8300/process/async \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "files": [{
        "file": {
          "url": "https://example.com/large-file.pdf",
          "file_name": "large-document.pdf"
        }
      }]
    },
    "mode": "--pdf-merge"
  }' | jq -r '.task_id')

# Проверка статуса
curl -X GET http://147.45.146.17:8300/process/status/$TASK_ID \
  -H "X-API-Key: your-api-key"

# Метрики
curl -X GET http://147.45.146.17:8300/metrics \
  -H "X-API-Key: your-api-key"

---

📊 Мониторинг

Интеграция с Prometheus

Добавьте в prometheus.yml:

scrape_configs:
  - job_name: 'pdf_processor'
    static_configs:
      - targets: ['147.45.146.17:8300']
    metrics_path: '/metrics/prometheus'
    basic_auth:
      username: 'api_key'
      password: 'your-api-key'

Grafana Dashboard

Метрики доступны для визуализации в Grafana:

• Общее количество запросов
• Успешные/неудачные запросы
• Среднее время обработки
• Ошибки по типам
• Асинхронные задачи

---

🔒 Безопасность

1. API Key - Все POST/GET endpoints требуют валидный API ключ
2. TTL задач - Результаты асинхронных задач хранятся 1 час
3. Таймауты - Максимальное время обработки: 5 минут
4. Валидация - Все входные данные валидируются через Pydantic

---

🐛 Обработка ошибок

Типы ошибок:

• script_error - Ошибка выполнения bash скрипта
• json_parse_error - Ошибка парсинга JSON результата
• timeout - Превышено время ожидания (5 минут)
• exception - Неожиданная ошибка
• unhandled_exception - Критическая ошибка

Коды HTTP:

• 200 - Успех
• 401 - Не указан API ключ
• 403 - Неверный API ключ
• 404 - Задача не найдена
• 500 - Внутренняя ошибка сервера
• 501 - Функция не реализована
• 504 - Таймаут

---

📝 Swagger UI

Интерактивная документация доступна по адресу:

• Swagger UI: http://147.45.146.17:8300/docs
• ReDoc: http://147.45.146.17:8300/redoc

---

Версия: 1.0.0
Дата обновления: 2025-12-29