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

Узнайте, как получить доступ к API ServerCon и правильно использовать ключи аутентификации.

🗝️ Получение API ключа

Для использования большинства эндпоинтов API ServerCon вам потребуется API ключ.

📝 Как получить ключ

Зарегистрируйтесь на платформе ServerCon
Войдите в личный кабинет
Перейдите в раздел "API" в настройках профиля
Создайте новый API ключ с необходимыми разрешениями
Скопируйте ключ - он больше не будет показан в интерфейсе

🎯 Типы ключей

Тип ключа	Описание	Лимиты (час/день/месяц)	Цена	Доступные эндпоинты
Free	Бесплатная для тестирования	50 / 500 / 10,000	$0.00	Серверы, игры, базовая аналитика
Basic	Для малого бизнеса	200 / 2,000 / 50,000	$9.99	+ Расширенная статистика
Premium	Активное использование	500 / 5,000 / 150,000	$29.99	+ История, графики, детальная аналитика
Professional	Крупные проекты	1,000 / 10,000 / 300,000	$79.99	+ Массовые операции, экспорт данных
Enterprise	Корпоративные решения	5,000 / 50,000 / 1,000,000	$299.99	+ Приоритетная поддержка, кастомные лимиты

🆓 Тестовый ключ

Для разработки и тестирования вы можете использовать наш тестовый ключ:

test_key_12345

Ограничения тестового ключа

Тестовый ключ имеет ограниченные возможности и предназначен только для разработки. Для продакшена необходимо получить полноценный API ключ.

🔑 Использование ключей

🎫 Bearer Token аутентификация

Все запросы к API должны содержать заголовок Authorization с Bearer токеном:

Authorization: Bearer ваш_api_ключ_здесь

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

🔧 Интерактивный API Тестер

Попробуйте наши API эндпоинты прямо здесь

⚠️ Примечание: Используется прокси для обхода CORS. Если запросы не работают, проверьте подключение к интернету.

API Ключ:

Тестовый ключ

🔥 Популярные эндпоинты

⚡ Лимиты и ограничения

📊 Лимиты запросов

Тип ключа	Запросов в час	Запросов в день	Запросов в месяц
Free	50	500	10,000
Basic	200	2,000	50,000
Premium	500	5,000	150,000
Professional	1,000	10,000	300,000
Enterprise	5,000	50,000	1,000,000

⚠️ Обработка превышения лимитов

При превышении лимитов API вернет ошибку 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Превышен лимит запросов",
    "details": "Лимит: 60 запросов в минуту. Попробуйте через 45 секунд.",
    "retry_after": 45
  }
}

📝 Примеры ответов с ошибками (API v3.2)

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Отсутствует или неверный API ключ",
    "status_code": 401,
    "details": {
      "hint": "Добавьте заголовок: Authorization: Bearer YOUR_API_KEY",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Недостаточно прав для операции",
    "status_code": 403,
    "details": {
      "hint": "Обновите тип API ключа или обратитесь к администратору",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Сервер не найден (ID: 99999)",
    "status_code": 404
  },
  "timestamp": 1640995200.0
}

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Ошибка валидации данных",
    "status_code": 422,
    "details": {
      "field_errors": {
        "server_id": "Должно быть положительным числом",
        "name": "Обязательное поле"
      }
    }
  },
  "timestamp": 1640995200.0
}

429 Too Many Requests (обновленный формат)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Превышен лимит запросов. Дождитесь сброса лимита",
    "status_code": 429,
    "details": {
      "hint": "Дождитесь сброса лимита или обновите подписку",
      "retry_after": "3600",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "DATABASE_ERROR",
    "message": "Внутренняя ошибка сервера",
    "status_code": 500,
    "details": {
      "hint": "Попробуйте позже или обратитесь в поддержку",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

📊 Формат ответов API v3.2

✅ Успешный ответ

{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "servers": [...],
    "total": 150,
    "page": 1,
    "per_page": 20
  },
  "timestamp": 1640995200.0
}

❌ Ответ с ошибкой

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Отсутствует или неверный API ключ",
    "status_code": 401,
    "details": {
      "hint": "Добавьте заголовок: Authorization: Bearer YOUR_API_KEY",
      "documentation": "/api/v1/docs"
    }
  },
  "timestamp": 1640995200.0
}

🔄 Структура ответа

success - булево значение, указывающее на успех операции
message - краткое описание результата (только для успешных ответов)
data - основные данные ответа (только для успешных ответов)
error - объект с информацией об ошибке (только для ошибок)
timestamp - время ответа в Unix timestamp

🛡️ Безопасность

🔒 Рекомендации по безопасности

Не раскрывайте API ключи
- Никогда не добавляйте ключи в публичные репозитории
- Используйте переменные окружения в продакшене
- Регулярно обновляйте ключи
Ограничивайте разрешения
- Создавайте ключи только с необходимыми правами
- Используйте разные ключи для разных приложений
- Отзывайте неиспользуемые ключи
Мониторинг использования
- Регулярно проверяйте статистику использования
- Настройте уведомления о подозрительной активности
- Отслеживайте IP адреса запросов

🌍 Переменные окружения

# .env файл
SERVERCON_API_KEY=ваш_api_ключ_здесь
SERVERCON_API_URL=http://138.124.109.53:5000

// Использование в коде
const apiKey = process.env.SERVERCON_API_KEY;
const apiUrl = process.env.SERVERCON_API_URL;

const response = await fetch(`${apiUrl}/api/v1/servers`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

❌ Коды ошибок аутентификации

Код	Ошибка	Описание	Решение
401	Unauthorized	Отсутствует или неверный API ключ	Проверьте заголовок Authorization
403	Forbidden	Недостаточно прав для операции	Обновите тип API ключа
429	Too Many Requests	Превышен лимит запросов	Дождитесь сброса лимита

📋 HTTP статус-коды API v3.2

Код	Название	Описание	Примеры использования
200	OK	Запрос выполнен успешно	Получение списка серверов, статистики
201	Created	Ресурс создан успешно	Создание нового API ключа
400	Bad Request	Некорректный запрос	Отсутствуют обязательные параметры
401	Unauthorized	Неверный API ключ	Отсутствует авторизация
403	Forbidden	Недостаточно прав	Обычный ключ для админских операций
404	Not Found	Ресурс не найден	Несуществующий сервер или игра
422	Unprocessable Entity	Ошибка валидации	Некорректные данные в запросе
429	Too Many Requests	Превышен лимит	Слишком много запросов
500	Internal Server Error	Внутренняя ошибка	Проблемы с базой данных

🔍 Коды ошибок API

Код ошибки	HTTP статус	Описание	Решение
UNAUTHORIZED	401	Отсутствует или неверный API ключ	Проверьте заголовок Authorization
INSUFFICIENT_PERMISSIONS	403	Недостаточно прав для операции	Обновите тип API ключа
RESOURCE_NOT_FOUND	404	Ресурс не найден	Проверьте правильность ID
VALIDATION_FAILED	422	Ошибка валидации данных	Проверьте формат данных
RATE_LIMIT_EXCEEDED	429	Превышен лимит запросов	Дождитесь сброса лимита
IP_BLOCKED	403	IP адрес заблокирован	Обратитесь в поддержку
DATABASE_ERROR	500	Ошибка базы данных	Попробуйте позже

🔗 Примеры интеграции

🟨 JavaScript/Node.js

class ServerConAPI {
  constructor(apiKey, baseUrl = 'http://138.124.109.53:5000') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    };

    try {
      const response = await fetch(url, {
        ...options,
        headers
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }

      return await response.json();
    } catch (error) {
      console.error('API Error:', error);
      throw error;
    }
  }

  // Получить все серверы
  async getServers(params = {}) {
    const query = new URLSearchParams(params).toString();
    return this.request(`/api/v1/servers${query ? '?' + query : ''}`);
  }

  // Получить сервер по ID
  async getServer(serverId) {
    return this.request(`/api/v1/servers/${serverId}`);
  }
}

// Использование
const api = new ServerConAPI(process.env.SERVERCON_API_KEY);

async function example() {
  try {
    const servers = await api.getServers({ game_id: 30, limit: 10 });
    console.log('Minecraft серверы:', servers.data);
  } catch (error) {
    console.error('Ошибка получения серверов:', error);
  }
}

🐍 Python

import requests
import os
from typing import Dict, Any, Optional

class ServerConAPI:
    def __init__(self, api_key: str, base_url: str = "http://138.124.109.53:5000"):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def request(self, endpoint: str, method: str = 'GET', **kwargs) -> Dict[Any, Any]:
        url = f"{self.base_url}{endpoint}"
        
        try:
            response = self.session.request(method, url, **kwargs)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise
    
    def get_servers(self, **params) -> Dict[Any, Any]:
        return self.request('/api/v1/servers', params=params)
    
    def get_server(self, server_id: int) -> Dict[Any, Any]:
        return self.request(f'/api/v1/servers/{server_id}')

# Использование
api = ServerConAPI(os.getenv('SERVERCON_API_KEY'))

try:
    servers = api.get_servers(game_id=30, limit=10)
    print("Minecraft серверы:", servers['data'])
except Exception as e:
    print(f"Ошибка: {e}")

💻 cURL

# Получить статистику API ключа
curl -H "Authorization: Bearer ваш_api_ключ" \
     http://138.124.109.53:5000/api/v1/stats

# Получить серверы Minecraft
curl -H "Authorization: Bearer ваш_api_ключ" \
     "http://138.124.109.53:5000/api/v1/servers?game_id=30&limit=10"

# Получить информацию о конкретном сервере
curl -H "Authorization: Bearer ваш_api_ключ" \
     http://138.124.109.53:5000/api/v1/servers/12345

🐛 Отладка

✅ Проверка валидности ключа

Если у вас возникают проблемы с аутентификацией, используйте эндпоинт /api/v1/stats для проверки вашего ключа:

async function checkApiKey(apiKey) {
  try {
    const response = await fetch('http://138.124.109.53:5000/api/v1/stats', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    if (response.ok) {
      const data = await response.json();
      console.log('API ключ валиден:', data.data.api_key_info);
      return true;
    } else {
      console.error('Невалидный API ключ:', response.status);
      return false;
    }
  } catch (error) {
    console.error('Ошибка проверки ключа:', error);
    return false;
  }
}

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

1️⃣ Получите API ключ

Используйте тестовый ключ test_key_12345 или получите свой в личном кабинете.

2️⃣ Сделайте первый запрос

curl -H "Authorization: Bearer test_key_12345" \
     http://138.124.109.53:5000/api/v1/servers?limit=5

3️⃣ Изучите ответ

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "name": "Мой сервер",
      "game_id": 30,
      "game_name": "Minecraft",
      "players": {
        "online": 45,
        "max": 100
      },
      "status": "online"
    }
  ]
}

📚 Дополнительные ресурсы

🆘 Поддержка

Если у вас возникли проблемы с аутентификацией:

Проверьте правильность API ключа
Убедитесь в корректности заголовка Authorization
Проверьте лимиты запросов
Обратитесь в поддержку через личный кабинет

Совет

Всегда используйте переменные окружения для хранения API ключей в продакшене!

🗝️ Получение API ключа​

📝 Как получить ключ​

🎯 Типы ключей​

🆓 Тестовый ключ​

🔑 Использование ключей​

🎫 Bearer Token аутентификация​

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

🔧 Интерактивный API Тестер

🔥 Популярные эндпоинты

⚡ Лимиты и ограничения​

📊 Лимиты запросов​

⚠️ Обработка превышения лимитов​

📝 Примеры ответов с ошибками (API v3.2)​

401 Unauthorized​

403 Forbidden​

404 Not Found​

422 Unprocessable Entity​

429 Too Many Requests (обновленный формат)​

500 Internal Server Error​

📊 Формат ответов API v3.2​

✅ Успешный ответ​

❌ Ответ с ошибкой​

🔄 Структура ответа​

🛡️ Безопасность​

🔒 Рекомендации по безопасности​

🌍 Переменные окружения​

❌ Коды ошибок аутентификации​

📋 HTTP статус-коды API v3.2​

🔍 Коды ошибок API​

🔗 Примеры интеграции​

🟨 JavaScript/Node.js​

🐍 Python​

💻 cURL​

🐛 Отладка​

✅ Проверка валидности ключа​

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

1️⃣ Получите API ключ​

2️⃣ Сделайте первый запрос​

3️⃣ Изучите ответ​

📚 Дополнительные ресурсы​

🆘 Поддержка​