smartsoltech_site/docs/API.md

# 🤖 SmartSolTech API Documentation

## 📡 API Endpoints Overview

SmartSolTech предоставляет RESTful API для взаимодействия с системой управления заказами и интеграции с внешними сервисами.

### Base URL
```
Production: https://smartsoltech.kr/api/
Development: http://localhost:8000/api/
```

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

### API Token Authentication

```http
Authorization: Token your-api-token-here
```

**Получение токена:**
```bash
# Через CLI
./cli manage drf_create_token <username>

# Через Django shell
./cli shell
>>> from django.contrib.auth.models import User
>>> from rest_framework.authtoken.models import Token
>>> user = User.objects.get(username='admin')
>>> token = Token.objects.create(user=user)
>>> print(token.key)
```

## 📋 Service Requests API

### Создание заявки на услугу

**POST** `/api/service-requests/`

```json
{
  "client_name": "Иван Иванов",
  "client_email": "ivan@example.com",
  "client_phone": "+7 900 123-45-67",
  "service_type": "web_development",
  "description": "Разработка корпоративного сайта",
  "budget_range": "50000-100000",
  "preferred_contact": "email"
}
```

**Response:**
```json
{
  "id": 15,
  "client_name": "Иван Иванов",
  "client_email": "ivan@example.com",
  "client_phone": "+7 900 123-45-67",
  "service_type": "web_development",
  "description": "Разработка корпоративного сайта",
  "budget_range": "50000-100000",
  "preferred_contact": "email",
  "status": "pending",
  "qr_code_url": "/static/qr_codes/request_15.png",
  "chat_id": null,
  "created_at": "2023-11-25T10:30:00Z",
  "updated_at": "2023-11-25T10:30:00Z"
}
```

### Получение списка заявок

**GET** `/api/service-requests/`

**Query Parameters:**
- `status` - Фильтр по статусу (`pending`, `confirmed`, `in_progress`, `completed`, `cancelled`)
- `service_type` - Фильтр по типу услуги
- `created_after` - Заявки после определенной даты (ISO format)
- `page` - Номер страницы
- `page_size` - Количество элементов на странице

```bash
curl -H "Authorization: Token your-token" \
     "https://smartsoltech.kr/api/service-requests/?status=pending&page=1"
```

### Получение конкретной заявки

**GET** `/api/service-requests/{id}/`

```bash
curl -H "Authorization: Token your-token" \
     "https://smartsoltech.kr/api/service-requests/15/"
```

### Обновление статуса заявки

**PATCH** `/api/service-requests/{id}/`

```json
{
  "status": "confirmed",
  "chat_id": "123456789"
}
```

### Проверка статуса заявки (публичный endpoint)

**GET** `/api/check-request-status/{id}/`

```json
{
  "status": "confirmed",
  "message": "Ваша заявка подтверждена! Мы свяжемся с вами в ближайшее время."
}
```

## 🏢 Companies API

### Получение информации о компании

**GET** `/api/companies/`

```json
[
  {
    "id": 1,
    "name": "SmartSolTech",
    "description": "Инновационные IT решения для бизнеса",
    "email": "info@smartsoltech.kr",
    "phone": "+7 800 555-35-35",
    "website": "https://smartsoltech.kr",
    "address": "г. Москва, ул. Технологическая, д. 1",
    "logo": "/media/company/logo.png",
    "founded_year": 2023,
    "employees_count": "10-50",
    "specializations": [
      "Веб-разработка",
      "Мобильные приложения",
      "DevOps"
    ]
  }
]
```

## 👥 Team API

### Получение команды

**GET** `/api/team-members/`

```json
[
  {
    "id": 1,
    "name": "Алексей Петров",
    "position": "Lead Developer",
    "bio": "10+ лет в веб-разработке",
    "photo": "/media/team/alexey.jpg",
    "linkedin": "https://linkedin.com/in/alexey",
    "github": "https://github.com/alexey",
    "email": "alexey@smartsoltech.kr",
    "skills": ["Python", "Django", "React", "Docker"]
  }
]
```

## 📊 Projects API

### Получение портфолио

**GET** `/api/projects/`

```json
[
  {
    "id": 1,
    "title": "E-commerce платформа",
    "description": "Современная платформа интернет-торговли",
    "image": "/media/projects/ecommerce.jpg",
    "url": "https://example-shop.com",
    "category": "Веб-разработка",
    "technologies": ["Django", "React", "PostgreSQL"],
    "completion_date": "2023-10-15",
    "client": "ООО Торговый Дом",
    "status": "completed"
  }
]
```

## 📝 Blog API

### Получение статей блога

**GET** `/api/blog/posts/`

**Query Parameters:**
- `category` - Фильтр по категории
- `tag` - Фильтр по тегу
- `published_after` - Статьи после даты
- `search` - Поиск по заголовку и содержанию

```json
[
  {
    "id": 1,
    "title": "Тренды веб-разработки 2024",
    "slug": "web-dev-trends-2024",
    "excerpt": "Обзор основных трендов в веб-разработке",
    "content": "Полный текст статьи...",
    "author": {
      "name": "Алексей Петров",
      "photo": "/media/team/alexey.jpg"
    },
    "category": {
      "name": "Разработка",
      "slug": "development"
    },
    "tags": ["веб-разработка", "тренды", "2024"],
    "featured_image": "/media/blog/trends-2024.jpg",
    "published_at": "2023-11-20T10:00:00Z",
    "reading_time": 8,
    "views_count": 1234,
    "is_featured": true
  }
]
```

### Получение конкретной статьи

**GET** `/api/blog/posts/{slug}/`

## 🏷️ Categories & Tags API

### Категории услуг

**GET** `/api/categories/`

```json
[
  {
    "id": 1,
    "name": "Веб-разработка",
    "slug": "web-development",
    "description": "Создание современных веб-приложений",
    "icon": "fas fa-code",
    "services_count": 15
  }
]
```

### Теги

**GET** `/api/tags/`

```json
[
  {
    "id": 1,
    "name": "Django",
    "slug": "django",
    "color": "#092E20",
    "posts_count": 12
  }
]
```

## 📞 Contact API

### Отправка сообщения

**POST** `/api/contact/`

```json
{
  "name": "Анна Смирнова",
  "email": "anna@example.com",
  "subject": "Вопрос по услугам",
  "message": "Здравствуйте! Интересует разработка мобильного приложения.",
  "phone": "+7 900 123-45-67"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Сообщение успешно отправлено. Мы ответим в ближайшее время.",
  "id": 42
}
```

## 📊 Analytics API (Admin only)

### Статистика заявок

**GET** `/api/analytics/service-requests/`

```json
{
  "total_requests": 156,
  "pending_requests": 23,
  "confirmed_requests": 89,
  "completed_requests": 44,
  "requests_by_month": [
    {"month": "2023-10", "count": 45},
    {"month": "2023-11", "count": 67}
  ],
  "popular_services": [
    {"service": "Веб-разработка", "count": 78},
    {"service": "Мобильные приложения", "count": 34}
  ]
}
```

### Статистика сайта

**GET** `/api/analytics/site-stats/`

```json
{
  "total_views": 12456,
  "unique_visitors": 3456,
  "popular_pages": [
    {"path": "/services/", "views": 2345},
    {"path": "/portfolio/", "views": 1876}
  ],
  "referrers": [
    {"source": "google.com", "visits": 1234},
    {"source": "direct", "visits": 987}
  ]
}
```

## 🤖 Telegram Integration API

### Webhook для Telegram Bot

**POST** `/api/telegram/webhook/`

Эндпоинт для получения обновлений от Telegram Bot API.

### Отправка уведомления

**POST** `/api/telegram/notify/`

```json
{
  "chat_id": "123456789",
  "message": "У вас новая заявка на услугу!",
  "parse_mode": "HTML",
  "disable_web_page_preview": true
}
```

## 🔧 Utilities API

### Генерация QR-кода

**POST** `/api/generate-qr/`

```json
{
  "data": "https://smartsoltech.kr/confirm/15/",
  "size": "200x200",
  "format": "PNG"
}
```

**Response:**
```json
{
  "qr_code_url": "/static/qr_codes/custom_qr_1234567890.png",
  "expires_at": "2023-11-26T10:30:00Z"
}
```

### Загрузка файлов

**POST** `/api/upload/`

```bash
curl -X POST \
     -H "Authorization: Token your-token" \
     -F "file=@document.pdf" \
     -F "category=documents" \
     "https://smartsoltech.kr/api/upload/"
```

## 📱 Mobile App API

### Конфигурация приложения

**GET** `/api/mobile/config/`

```json
{
  "app_name": "SmartSolTech",
  "version": "1.0.0",
  "api_version": "v1",
  "features": {
    "push_notifications": true,
    "offline_mode": true,
    "biometric_auth": true
  },
  "endpoints": {
    "base_url": "https://smartsoltech.kr/api/",
    "websocket_url": "wss://smartsoltech.kr/ws/"
  }
}
```

## 🚨 Error Handling

### Стандартные HTTP коды

- `200 OK` - Успешный запрос
- `201 Created` - Ресурс создан
- `400 Bad Request` - Некорректные данные
- `401 Unauthorized` - Необходима аутентификация
- `403 Forbidden` - Недостаточно прав
- `404 Not Found` - Ресурс не найден
- `429 Too Many Requests` - Превышен лимит запросов
- `500 Internal Server Error` - Ошибка сервера

### Формат ошибок

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Некорректные данные",
    "details": {
      "email": ["Введите корректный email адрес"],
      "phone": ["Номер телефона обязателен"]
    },
    "timestamp": "2023-11-25T10:30:00Z",
    "request_id": "req_1234567890"
  }
}
```

## 🔒 Rate Limiting

### Лимиты для разных типов пользователей

- **Anonymous**: 100 запросов в час
- **Authenticated**: 1000 запросов в час  
- **Premium**: 10000 запросов в час

### Headers ответа

```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1635724800
```

## 📚 SDK и библиотеки

### Python SDK

```python
from smartsoltech_api import SmartSolTechClient

client = SmartSolTechClient(
    api_key='your-api-key',
    base_url='https://smartsoltech.kr/api/'
)

# Создание заявки
request = client.service_requests.create({
    'client_name': 'Test Client',
    'service_type': 'web_development',
    'description': 'Test request'
})

# Получение статистики
stats = client.analytics.get_service_requests_stats()
```

### JavaScript SDK

```javascript
import { SmartSolTechAPI } from 'smartsoltech-js-sdk';

const api = new SmartSolTechAPI({
  apiKey: 'your-api-key',
  baseURL: 'https://smartsoltech.kr/api/'
});

// Создание заявки
const request = await api.serviceRequests.create({
  clientName: 'Test Client',
  serviceType: 'web_development',
  description: 'Test request'
});

// Получение проектов
const projects = await api.projects.list();
```

## 🧪 Testing

### Тестирование API

```bash
# Запуск тестов API
./cli manage test api.tests

# Тестирование конкретного эндпоинта
./cli manage test api.tests.test_service_requests

# Запуск coverage
./cli exec coverage run --source='.' manage.py test
./cli exec coverage report
```

### Примеры запросов

```bash
# Получение токена
curl -X POST http://localhost:8000/api/auth/token/ \
     -H "Content-Type: application/json" \
     -d '{"username": "admin", "password": "password"}'

# Создание заявки
curl -X POST http://localhost:8000/api/service-requests/ \
     -H "Authorization: Token your-token" \
     -H "Content-Type: application/json" \
     -d '{
       "client_name": "Test Client",
       "client_email": "test@example.com",
       "service_type": "web_development",
       "description": "Test request"
     }'
```

---

🎯 **Следующие шаги**: [Развертывание](DEPLOYMENT.md) | [Управление скриптами](SCRIPTS_README.md)