Documentación API

API completa para interactuar con el sistema de servidores Counter-Strike 1.6. Envía datos, obtén rankings y accede a estadísticas en tiempo real.

Introducción

Bienvenido a la API de 5YA.COM.AR. Esta API permite a los desarrolladores integrar sus aplicaciones con nuestro sistema de ranking de servidores Counter-Strike 1.6.

URL Base: http://5ya.com.ar

Características principales:

  • ✅ Envío de datos de servidores en tiempo real
  • ✅ Consulta de rankings dinámicos
  • ✅ Estadísticas detalladas por servidor
  • ✅ Historial de actividad
  • ✅ Validaciones automáticas

Autenticación

La mayoría de endpoints son públicos y no requieren autenticación. Los endpoints que modifican datos requieren validación específica.

Importante: El endpoint /api/data implementa validaciones automáticas basadas en IP, frecuencia y contenido para prevenir spam.

API de Datos de Servidores

POST Enviar datos del servidor
http://5ya.com.ar/api/data

Permite a los servidores enviar su información actual para ser incluida en el ranking.

Parámetros requeridos:

Parámetro Tipo Descripción Ejemplo
ip string Dirección IP del servidor 192.168.1.1
port string Puerto del servidor (5 dígitos) 27015
hostname string Nombre del servidor Mi Servidor CS 1.6
nombre string Nombre del reportante Admin
msg string Mensaje descriptivo Servidor activo 24/7
max_players integer Máximo de jugadores (≤32) 20
current_players integer Jugadores actuales 15
current_map string Mapa actual de_dust2
tipo string Tipo de servidor MIX, PUBLICO, DEATHMATCH

Ejemplo de solicitud:

POST /api/data
{
  "ip": "192.168.1.1",
  "port": "27015",
  "hostname": "Mi Servidor Counter-Strike",
  "nombre": "AdminPlayer",
  "msg": "Servidor activo 24/7 con mods personalizados",
  "max_players": 20,
  "current_players": 15,
  "current_map": "de_dust2",
  "tipo": "MIX",
  "username": "ServerBot"
}

Respuesta exitosa (200):

200 OK
{
  "success": true,
  "message": "Data procesada exitosamente",
  "data": {
    "id": 12345,
    "server": {
      "ip": "192.168.1.1",
      "port": "27015",
      "hostname": "Mi Servidor Counter-Strike"
    },
    "detection": {
      "tipo_validado": "MIX",
      "has_special_config": false
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processing_time_ms": 45
}

Respuesta de error (400):

400 Bad Request
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Faltan datos obligatorios",
    "details": "La data no pudo ser procesada debido a validaciones fallidas"
  },
  "validation_info": {
    "required_fields": ["ip", "port", "hostname", "nombre", "msg", "max_players", "current_players", "current_map", "tipo"],
    "constraints": {
      "max_players": "Máximo 32",
      "frequency": "Mínimo 2 minutos entre envíos"
    }
  }
}

API de Ranking

POST Obtener ranking de servidores
http://5ya.com.ar/api/ranking

Obtiene el ranking paginado de servidores ordenado por puntos de popularidad.

Parámetros opcionales:

Parámetro Tipo Por defecto Descripción
page integer 1 Número de página
limit integer 50 Servidores por página (máx. 100)
tipo string null Filtrar por tipo: PUBLICO, MIX, DEATHMATCH, etc.

Ejemplo de solicitud:

POST /api/ranking
{
  "page": 1,
  "limit": 10,
  "tipo": "MIX"
}

Respuesta exitosa (200):

200 OK
{
  "success": true,
  "data": {
    "rankings": [
      {
        "current_position": 1,
        "ip": "192.168.1.1",
        "port": "27015",
        "hostname": "Servidor #1",
        "current_players": 28,
        "avg_players_month": 22.5,
        "peak_players_month": 32,
        "ranking_points": 2847.5,
        "status": "online",
        "server_type": "MIX"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_servers": 47,
      "per_page": 10,
      "filter_type": "MIX"
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Filtros disponibles

  • Sin filtro: Omite el parámetro "tipo" o envía null para obtener todos los servidores
  • PUBLICO: Servidores públicos con muchos jugadores
  • MIX: Servidores para partidas competitivas y gather
  • DEATHMATCH: Servidores de entrenamiento y práctica
  • Posiciones originales: Los servidores mantienen su posición del ranking global

API de Servidores Específicos

GET Obtener detalles de un servidor
http://5ya.com.ar/api/server/{ip}/{port}

Obtiene información detallada de un servidor específico, incluyendo historial.

Parámetros de URL:

Parámetro Tipo Descripción Ejemplo
ip string Dirección IP del servidor 192.168.1.1
port string Puerto del servidor 27015

Ejemplo de solicitud:

GET http://5ya.com.ar/api/server/192.168.1.1/27015

API de Estadísticas

POST Actividad del servidor
http://5ya.com.ar/api/server-activity

Obtiene la actividad de las últimas 24 horas de un servidor específico, incluyendo el historial de jugadores por hora.

Parámetros requeridos:

Parámetro Tipo Descripción Ejemplo
ip string Dirección IP del servidor 192.168.1.1
port string Puerto del servidor 27015

Ejemplo de solicitud:

POST /api/server-activity
{
  "ip": "192.168.1.1",
  "port": "27015"
}

Respuesta exitosa (200):

200 OK
{
  "activity": [
    {
      "hora": "08:15",
      "current_players": 5
    },
    {
      "hora": "09:30",
      "current_players": 12
    },
    {
      "hora": "10:45",
      "current_players": 18
    },
    {
      "hora": "11:00",
      "current_players": 22
    },
    {
      "hora": "12:15",
      "current_players": 28
    }
  ]
}

Respuesta de error (400):

400 Bad Request
{
  "error": "Faltan datos",
  "message": "Los parámetros 'ip' y 'port' son obligatorios"
}

Respuesta cuando no hay datos (200):

200 OK
{
  "activity": []
}
POST Historial mensual del servidor
http://5ya.com.ar/api/server-history

Obtiene el historial mensual y posiciones en el ranking de un servidor durante los últimos 12 meses.

Parámetros requeridos:

Parámetro Tipo Descripción Ejemplo
ip string Dirección IP del servidor 192.168.1.1
port string Puerto del servidor 27015

Ejemplo de solicitud:

POST /api/server-history
{
  "ip": "192.168.1.1",
  "port": "27015"
}

Respuesta exitosa (200):

200 OK
{
  "history": [
    {
      "year": 2024,
      "month": 1,
      "avg_players": 18.5,
      "peak_players": 32,
      "total_samples": 892,
      "rank": 3
    },
    {
      "year": 2023,
      "month": 12,
      "avg_players": 15.2,
      "peak_players": 28,
      "total_samples": 756,
      "rank": 7
    },
    {
      "year": 2023,
      "month": 11,
      "avg_players": 12.8,
      "peak_players": 25,
      "total_samples": 634,
      "rank": 12
    }
  ]
}

Respuesta de error (400):

400 Bad Request
{
  "error": "Faltan datos",
  "message": "Los parámetros 'ip' y 'port' son obligatorios"
}

Respuesta cuando no hay historial (200):

200 OK
{
  "history": []
}

Información adicional

  • Actividad: Se muestran datos de las últimas 24 horas con registros por hora
  • Historial: Incluye los últimos 12 meses de estadísticas con posición en ranking
  • Rank: Posición del servidor en el ranking mensual (1 = mejor posición)
  • Total samples: Cantidad total de reportes de actividad en el período

Códigos de Error

Código HTTP Código Interno Descripción
400 MISSING_REQUIRED_FIELDS Faltan campos obligatorios en la solicitud
400 INVALID_IP_PORT Formato de IP o puerto inválido
400 MAX_PLAYERS_EXCEEDED Máximo de jugadores excede el límite (32)
403 IP_BLACKLISTED IP está en lista negra
404 NOT_FOUND Servidor no encontrado
429 FREQUENCY_LIMIT_EXCEEDED Demasiadas solicitudes (mín. 2 min entre envíos)
429 TOO_MANY_CONSECUTIVE Máximo 2 envíos consecutivos por IP:PORT
500 INTERNAL_SERVER_ERROR Error interno del servidor

Ejemplos de Uso

JavaScript (Fetch API):

JavaScript
// Enviar datos del servidor
async function sendServerData() {
    const response = await fetch('http://5ya.com.ar/api/data', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            ip: "192.168.1.1",
            port: "27015",
            hostname: "Mi Servidor CS",
            nombre: "Admin",
            msg: "Servidor activo",
            max_players: 20,
            current_players: 15,
            current_map: "de_dust2",
            tipo: "MIX"
        })
    });
    
    const data = await response.json();
    console.log(data);
}

// Obtener ranking
async function getRanking() {
    const response = await fetch('http://5ya.com.ar/api/ranking', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            page: 1,
            limit: 10,
            tipo: "MIX"
        })
    });
    
    const data = await response.json();
    console.log(data.data.rankings);
}

// Obtener actividad del servidor
async function getServerActivity() {
    const response = await fetch('http://5ya.com.ar/api/server-activity', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            ip: "192.168.1.1",
            port: "27015"
        })
    });
    
    const data = await response.json();
    console.log(data.activity);
}

// Obtener historial mensual del servidor
async function getServerHistory() {
    const response = await fetch('http://5ya.com.ar/api/server-history', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            ip: "192.168.1.1",
            port: "27015"
        })
    });
    
    const data = await response.json();
    console.log(data.history);
}

PHP (cURL):

PHP
// Enviar datos del servidor
$data = [
    'ip' => '192.168.1.1',
    'port' => '27015',
    'hostname' => 'Mi Servidor CS',
    'nombre' => 'Admin',
    'msg' => 'Servidor activo',
    'max_players' => 20,
    'current_players' => 15,
    'current_map' => 'de_dust2',
    'tipo' => 'MIX'
];

$ch = curl_init('http://5ya.com.ar/api/data');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

print_r($result);

// Obtener actividad del servidor
$activityData = [
    'ip' => '192.168.1.1',
    'port' => '27015'
];

$ch = curl_init('http://5ya.com.ar/api/server-activity');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($activityData));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$activityResult = json_decode($response, true);
curl_close($ch);

print_r($activityResult);

Python (requests):

Python
import requests
import json

# Enviar datos del servidor
data = {
    'ip': '192.168.1.1',
    'port': '27015',
    'hostname': 'Mi Servidor CS',
    'nombre': 'Admin',
    'msg': 'Servidor activo',
    'max_players': 20,
    'current_players': 15,
    'current_map': 'de_dust2',
    'tipo': 'MIX'
}

response = requests.post(
    'http://5ya.com.ar/api/data',
    json=data,
    headers={'Content-Type': 'application/json'}
)

result = response.json()
print(json.dumps(result, indent=2))

# Obtener historial mensual del servidor
history_data = {
    'ip': '192.168.1.1',
    'port': '27015'
}

response = requests.post(
    'http://5ya.com.ar/api/server-history',
    json=history_data,
    headers={'Content-Type': 'application/json'}
)

history_result = response.json()
print("Historial del servidor:")
for month in history_result['history']:
    print(f"  {month['year']}/{month['month']:02d}: Promedio {month['avg_players']} jugadores, Ranking #{month['rank']}")

Límites y Restricciones

Política de Uso Justo

  • Frecuencia mínima: 2 minutos entre envíos del mismo servidor
  • Límite consecutivo: Máximo 2 envíos seguidos por IP:PORT
  • Jugadores máximo: 32 jugadores por servidor
  • Validación de tipos: Solo tipos válidos de la tabla modos
  • Blacklist automática: IPs problemáticas son bloqueadas automáticamente

Recomendaciones

  • Implementa manejo de errores para todos los códigos de respuesta
  • Respeta los límites de frecuencia para evitar bloqueos
  • Usa HTTPS cuando esté disponible
  • Incluye un User-Agent descriptivo en tus solicitudes