Documentación API

Sistema de verificación de votos de Metin2

Recompensas por votar fáciles, gratuitas y fiables para tu servidor privado de Metin2

¿Qué es el sistema de verificación de votos?

Nuestro Sistema de Verificación de Votos es una solución moderna e innovadora diseñada específicamente para servidores privados de Metin2. Ofrece una forma atractiva de que los jugadores voten por sus servidores favoritos mientras reciben beneficios dentro del juego.

El sistema es fácil de implementar y altamente confiable, lo que lo convierte en una excelente elección para los propietarios que desean aumentar la participación de los jugadores y la visibilidad del servidor.

Nuestro objetivo es crear una situación en la que todos ganan tanto para los jugadores como para los administradores. Los jugadores reciben recompensas por su lealtad, mientras que los servidores ganan visibilidad y mayor participación.

Sistema Vote4Buff (recomendado)

Sistema completo de votación y recompensas dentro del juego con interfaz personalizada

¿Qué es Vote4Buff?

Vote4Buff es nuestra solución premium todo en uno que incluye una atractiva interfaz dentro del juego, comunicación WebSocket e integración completa con el servidor. ¡Los jugadores pueden votar, elegir entre múltiples pools de bonus y recibir recompensas al instante sin salir del juego!

Arquitectura del sistema

El sistema Vote4Buff se compone de tres componentes principales:

Cliente

Sistema de interfaz en Python (uivote4buff.py)
Recursos gráficos personalizados
Integración WebSocket en C++
Soporte para 11 idiomas

Servidor

Integración con la API en C++
Gestión de pools de bonus
Sistema de recompensas con ítems
Seguimiento en tiempo real de afectaciones

Nuestra plataforma

API de verificación de votos
Seguimiento basado en cuentas
Protección anti-trampas
Estado de votos en tiempo real

Características clave

Múltiples pools de bonus: Hasta 3 pools configurables para que los jugadores elijan

Recompensas con ítems: Entrega automática de ítems tras un voto exitoso

Interfaz en tiempo real: Temporizadores y seguimiento de efectos dentro del juego

Comunicación WebSocket: Verificación instantánea sin recargar páginas

Multilenguaje: Compatible con 11 idiomas (EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ)

Recompensas personalizables: Configura bonus, duración y costes

Perfecto para: Propietarios que desean una solución profesional lista para usar sin invertir semanas en desarrollo personalizado. ¡Configura los pools, integra los archivos y listo!

Descargar archivos de Vote4Buff

Obtén todos los archivos necesarios para la integración en cliente y servidor

Requisitos

Vote4Buff está diseñado para la base de código martysama0134 v5.8. Si usas otra base, puede que necesites ajustar algunos cambios.

Contenido del paquete

Archivos de cliente

Archivos de UI en Python (uivote4buff.py)
Modificaciones de archivos del cliente
Gráficos y recursos de interfaz
Archivos de idioma (11 idiomas)
Implementación WebSocket en C++
Scripts de UI

Incluye libcurl.dll (32 bits incluido, 64 bits disponible)

Archivos de servidor

Configuración de char.h
Modificaciones del sistema de afectos
Integración de comandos de chat
Capa de comunicación con la API
Sistema de gestión de bonus

Incluye todas las modificaciones necesarias del código C++

Inicio de sesión requerido

Por favor, inicia sesión para descargar los archivos de Vote4Buff.

Guía de configuración

Configura pools de bonus, recompensas y ajustes de la API

Toda la configuración de Vote4Buff se realiza en el archivo char.h de tu servidor. A continuación encontrarás ejemplos detallados de cada opción.

Paso 1: Credenciales API

Empieza configurando tu ID de servidor y tu token API (disponibles en tu panel):

C++

// API SETTINGS from Metin2 Server List
static const std::string s_VOTE4BUFF_SERVER_ID = "YOUR_SERVER_ID"; // From dashboard
static const std::string s_VOTE4BUFF_API_TOKEN = "YOUR_API_TOKEN"; // From dashboard

static const int s_VOTE4BUFF_DURATION = 86400; // seconds (1 day) DO NOT MODIFY THIS !!!

Paso 2: Configura los pools de bonus

Puedes definir hasta 3 pools de bonus que los jugadores pueden elegir. Cada pool puede incluir múltiples bonificaciones:

C++

// Bonuses must be set with its APPLY_ declaration.
// You can add as many bonuses as you want per slot.
static std::vector<std::vector<std::pair<int, int>>> s_VOTE4BUFF_BONUSES =
{
    { // Bonus Pool 1: PvP Focused
        { APPLY_ATTBONUS_HUMAN, 5 },      // +5% vs Players
        { APPLY_DEF_GRADE_BONUS, 50 },    // +50 Defense
        // Add more bonuses if wanted
    },

    { // Bonus Pool 2: PvE Focused
        { APPLY_ATTBONUS_MONSTER, 5 },    // +5% vs Monsters
        { APPLY_ATTBONUS_INSECT, 5 },     // +5% vs Insects
        { APPLY_HP_REGEN, 10 },           // +10 HP Regen
    },

    { // Bonus Pool 3: Farm Focused
        { APPLY_ITEM_DROP_BONUS, 10 },    // +10% Drop Rate
        { APPLY_EXP_DOUBLE_BONUS, 10 },   // +10% EXP
        { APPLY_GOLD_FIND, 15 },          // +15% Gold
    },
};

Tipos APPLY disponibles

Bonos comunes: APPLY_ATTBONUS_HUMAN, APPLY_ATTBONUS_MONSTER, APPLY_DEF_GRADE_BONUS, APPLY_ITEM_DROP_BONUS, APPLY_EXP_DOUBLE_BONUS, APPLY_GOLD_FIND, APPLY_MAX_HP, APPLY_MAX_SP, APPLY_HP_REGEN, APPLY_SP_REGEN, APPLY_CRITICAL_PCT, APPLY_PENETRATE_PCT, entre muchos otros.

Paso 3: Recompensas con ítems (opcional)

Configura los ítems que los jugadores recibirán automáticamente al votar:

C++

static std::vector<std::pair<DWORD, int>> s_VOTE4BUFF_ITEM_REWARDS =
{
    // Leave empty if you don't want to give any items as rewards
    // Format: { vnum, count }
    { 27007, 5 },    // 5x Red Potion (XXL)
    { 50084, 1 },    // 1x Gold Bar
    { 71027, 10 },   // 10x Dragon Coin
};

Paso 4: Ajustes de cambio de bonus

Controla el tiempo de reutilización y el coste cuando los jugadores quieran cambiar de pool sin volver a votar:

C++

// Cooldown when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_COOLDOWN = 300; // seconds (5 minutes)

// Price when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_PRICE = 15000; // yang (0 = free)

Nota: Después de votar, los jugadores pueden elegir un pool de bonus gratis. El tiempo de espera y el precio solo se aplican si quieren cambiar sin volver a votar.

Guía de instalación

Instrucciones paso a paso para integrar Vote4Buff

Antes de comenzar

¡Haz copias de seguridad de tus archivos de cliente y servidor! Convención de nombres: los archivos con prefijo __ requieren fusionar cambios, los demás pueden copiarse directamente.

Instalación en el servidor

1

Configura char.h

Abre Source/Server/__char.h del paquete descargado.

Ubica class CBuffOnAttributes; y añade el código de configuración justo arriba (consulta la sección de configuración)
Establece tus valores de s_VOTE4BUFF_SERVER_ID y s_VOTE4BUFF_API_TOKEN
Configura los pools de bonus y las recompensas con ítems
Ubica bool DragonSoul_RefineWindow_CanRefine(); y agrega las declaraciones públicas necesarias

2

Aplica las modificaciones del servidor

Integra los archivos del lado del servidor incluidos en el paquete:

__affect.h - Fusiona los cambios en tu archivo affect.h existente
__chat_affect.cpp - Añade el manejo de efectos de Vote4Buff
__cmd_general.cpp - Añade el procesamiento de comandos
__desc_client.cpp - Ajustes al descriptor del cliente

Los archivos con prefijo __ indican que debes fusionar los cambios con tus archivos actuales.

3

Recompila el núcleo del juego

Compila tu servidor con las nuevas modificaciones.

make clean && make

Instalación en el cliente

4

Archivos de interfaz en Python

En la carpeta Client/root/:

Copia uivote4buff.py en la carpeta root/ de tu cliente
Modifica los siguientes archivos según las instrucciones:
- __constInfo.py
- __game.py
- __interfaceModule.py
- __uiAffectShower.py

5

Gráficos y scripts de UI

Copia la carpeta Client/ui/game/vote4buff/ a ui/game/ en tus paquetes
Copia Client/uiscript/vote4buffwindow.py en tu carpeta de uiscripts

6

Archivos de idioma

Añade las cadenas de idioma desde Client/locale/:

Anexa el contenido de __locale_game.txt a tu archivo locale_game.txt
Anexa el contenido de __locale_interface.txt a tu archivo locale_interface.txt

Idiomas disponibles: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ

7

Modificaciones del cliente en C++

En Source/Client/UserInterface/:

Copia M2WebSocket.cpp y M2WebSocket.h en el directorio UserInterface
Aplica las modificaciones de los archivos con prefijo __ a tus archivos existentes
Asegúrate de que libcurl.dll esté en tu directorio del cliente (32 bits incluido, descarga 64 bits si es necesario)

8

Agregar botón de UI (opcional)

Vote4Buff no agrega un botón por defecto. Debes llamar a ToggleVote4Buff() desde algún lugar de tu interfaz. Por ejemplo:

Añade un botón en tu SystemDialog
Asígnalo a un atajo de teclado
Inclúyelo en tu menú de accesos rápidos

O usa la clase incluida Vote4BuffButton, que crea un icono arrastrable.

9

Recompilar el cliente

Compila de nuevo tu ejecutable del cliente con las modificaciones.

10

Pruebas

Prueba la integración:

Inicia sesión en tu servidor
Abre la ventana de Vote4Buff
Vota en nuestra plataforma: https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
Vuelve al juego y verifica tu voto
Elige un pool de bonus y comprueba si se aplican los efectos
Comprueba que se hayan recibido las recompensas con ítems

¡Instalación completada!

Tus jugadores ahora pueden votar y recibir recompensas automáticamente. La interfaz Vote4Buff les mostrará cuándo pueden votar, les permitirá elegir pools de bonus y exhibirá temporizadores para los efectos activos.

Ventajas para administradores

Promoción gratuita

La mayoría de los jugadores descubren servidores a través de toplists, por lo que es una herramienta esencial de marketing

Configuración sencilla

Documentación detallada y guías paso a paso facilitan la puesta en marcha

Sin programar

Proceso de integración REST simple

Rendimiento optimizado

La verificación desde el cliente minimiza la carga para tu servidor

Alta fiabilidad

Sistema probado con protección incorporada contra fraude

Verificación de votos

Asegura que los jugadores realmente votaron antes de recompensarlos

Ventajas para jugadores

Reciben recompensas dentro del juego por votar

Interfaz de votación fácil de usar

Temporizador claro de tiempo de espera para votar de nuevo

Sistema fiable de entrega de recompensas

¿Cómo funciona el sistema?

El flujo es claro e intuitivo para los jugadores. Además, la comprobación del voto se realiza mediante nuestra API, garantizando que solo se verifiquen votos legítimos.

1

El jugador hace clic en votar

Desde tu sitio web o la interfaz dentro del juego

2

Redirección a la página de voto

El jugador es dirigido a la página de tu servidor en nuestra toplist

3

El jugador vota

Completa el CAPTCHA y envía su voto

4

Verificación por API

Tu servidor consulta nuestra API para verificar el voto

5

Recompensa al jugador

Tu servidor entrega la recompensa dentro del juego

Primeros pasos - Guía rápida

Elige el método de integración que mejor se adapte a tus necesidades:

RECOMENDADO

Sistema Vote4Buff

Solución completa con interfaz personalizada, comunicación WebSocket y recompensas automáticas.

✅ Interfaz completa dentro del juego
✅ Múltiples pools de bonus
✅ Recompensas automáticas con ítems
✅ Temporizadores en tiempo real
✅ Soporte para 11 idiomas

Comenzar con Vote4Buff

Integración API personalizada

Crea tu propia implementación usando nuestra API REST para tener máximo control.

🔧 Personalización total
🔧 Diseño de interfaz propio
🔧 Lógica de recompensas personalizada
🔧 Basado en IP o en cuenta

Usar API básica

Pasos generales

1

Registra tu servidor

Crea una cuenta y añade tu servidor en nuestra toplist en https://metin2-toplist.net/servers/create

2

Obtén tus credenciales API

Encuentra tu ID de servidor y token API en tu panel. Son necesarios para la autenticación.

3

Elige el método de integración

Descarga Vote4Buff para una solución lista o integra nuestra API para una implementación personalizada.

4

Prueba y despliega

Prueba el sistema de votación a fondo y luego publícalo en tu servidor en producción.

Endpoint API (para implementaciones personalizadas)

Nota

Si utilizas el sistema Vote4Buff (recomendado), esta API ya está integrada. Esta sección es para propietarios que deseen crear su propia implementación.

GET

https://metin2-toplist.net/api/check-vote

Parámetros necesarios

Parámetro	Tipo	Obligatorio	Descripción
`api_token`	string	Sí	Tu token API único
`ip`	string	Opcional*	Dirección IP del jugador (IPv4 o IPv6)
`account_id`	string	Opcional*	ID de cuenta o nombre de usuario del jugador para seguimiento preciso

*Debes enviar ip o account_id (o ambos)

Para mejores resultados, usa <code>account_id</code> y así identificar a cada jugador. El método con <code>ip</code> puede ser menos fiable si usan VPN o cambian de ubicación.

Formato de URL para votar

Envía a los jugadores a votar usando esta estructura de URL:

https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}

Ejemplos:
https://metin2-toplist.net/vote.en/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.de/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.tr/123-awesome-server/PlayerName

Idiomas disponibles: en, de, es, pl, tr, ro, it, pt, hu, gr, cz

Formato de respuesta

La API devuelve una respuesta JSON con la siguiente estructura:

Respuesta exitosa

{
    "success": true,
    "voted": true,
    "last_vote": "2025-11-11T14:30:00Z",
    "next_vote_in": 0,
    "message": "Vote verified successfully"
}

Respuesta sin voto válido

{
    "success": true,
    "voted": false,
    "message": "No recent vote found"
}

Respuesta de error

{
    "success": false,
    "message": "Invalid API token"
}

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la petición fue exitosa
`voted`	boolean	Indica si se encontró un voto válido (solo si success=true)
`last_vote`	string	Marca de tiempo ISO 8601 del último voto (solo si voted=true)
`next_vote_in`	integer	Segundos restantes para volver a votar (solo si voted=true)
`message`	string	Mensaje descriptivo con el resultado

Ejemplos de código

Ejemplo en PHP

Implementación con cURL en PHP

<?php
function checkVote($apiToken, $playerIP) {
    $url = "https://metin2-toplist.net/api/check-vote";
    $params = http_build_query([
        'api_token' => $apiToken,
        'ip' => $playerIP
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url . '?' . $params);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        return ['success' => false, 'message' => 'API request failed'];
    }

    return json_decode($response, true);
}

// Usage Example
$apiToken = 'YOUR_API_TOKEN_HERE';
$playerIP = $_SERVER['REMOTE_ADDR']; // Or get from your game server

$result = checkVote($apiToken, $playerIP);

if ($result['success'] && $result['voted']) {
    // Player has voted! Give reward
    echo "Vote verified! Rewarding player...";
    giveReward($playerName); // Your reward function
} else {
    echo "No valid vote found. Please vote first!";
}
?>

Ejemplo en Python

Implementación con Requests en Python

import requests
import json

def check_vote(api_token, player_ip):
    """
    Check if a player has voted for the server
    """
    url = "https://metin2-toplist.net/api/check-vote"
    params = {
        'api_token': api_token,
        'ip': player_ip
    }

    try:
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        return {'success': False, 'message': f'API request failed: {str(e)}'}

# Usage Example
api_token = 'YOUR_API_TOKEN_HERE'
player_ip = '123.456.789.012'

result = check_vote(api_token, player_ip)

if result.get('success') and result.get('voted'):
    print("Vote verified! Rewarding player...")
    # Give reward to player
else:
    print("No valid vote found. Please vote first!")

Ejemplo en C++ (para servidores)

Implementación con libcurl en C++

#include <curl/curl.h>
#include <string>
#include <sstream>

// Callback function for cURL
static size_t WriteCallback(void* contents, size_t size, size_t nmemb, void* userp) {
    ((std::string*)userp)->append((char*)contents, size * nmemb);
    return size * nmemb;
}

bool CheckVote(const std::string& apiToken, const std::string& playerIP) {
    CURL* curl;
    CURLcode res;
    std::string readBuffer;

    curl = curl_easy_init();
    if(curl) {
        std::ostringstream url;
        url << "https://metin2-toplist.net/api/check-vote"
            << "?api_token=" << apiToken
            << "&ip=" << playerIP;

        curl_easy_setopt(curl, CURLOPT_URL, url.str().c_str());
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &readBuffer);
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
        curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);

        if(res == CURLE_OK) {
            // Parse JSON response (you'll need a JSON library like nlohmann/json)
            // Check if readBuffer contains "\"voted\":true"
            return readBuffer.find("\"voted\":true") != std::string::npos;
        }
    }
    return false;
}

// Usage in your game server
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
    std::string apiToken = "YOUR_API_TOKEN_HERE";

    if(CheckVote(apiToken, playerIP)) {
        // Give reward to player
        GiveItemToPlayer(playerName, REWARD_ITEM_VNUM, REWARD_COUNT);
        SendNotice("Vote verified! You received your reward!");
    } else {
        SendNotice("No valid vote found. Please vote first!");
    }
}

Ejemplo en JavaScript/Node.js

Implementación con Fetch en Node.js

async function checkVote(apiToken, playerIP) {
    const url = new URL('https://metin2-toplist.net/api/check-vote');
    url.searchParams.append('api_token', apiToken);
    url.searchParams.append('ip', playerIP);

    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Accept': 'application/json'
            }
        });

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

        return await response.json();
    } catch (error) {
        console.error('API request failed:', error);
        return { success: false, message: error.message };
    }
}

const apiToken = 'YOUR_API_TOKEN_HERE';
const playerIP = '123.456.789.012';

checkVote(apiToken, playerIP).then(result => {
    if (result.success && result.voted) {
        console.log('Vote verified! Rewarding player...');
        // Give reward to player
    } else {
        console.log('No valid vote found. Please vote first!');
    }
});

Guía de integración

Buenas prácticas de seguridad

Guarda tu token API de forma segura y nunca lo expongas en código del lado del cliente. Las peticiones a la API deben realizarse desde tu backend.

Paso 1: Crea botón/comando de voto

Añade un botón en tu web o un comando dentro del juego que dirija a los jugadores a tu página de voto en https://metin2-toplist.net/servers/YOUR-SERVER-SLUG.

Paso 2: Implementa la comprobación

Cuando un jugador solicite su recompensa (desde la web o el juego), verifica si ya votó:

Obtén la IP del jugador
Realiza una petición a nuestro endpoint de verificación
Analiza la respuesta JSON
Si voted es true, concede la recompensa
Registra que ya entregaste la recompensa para evitar duplicados

Paso 3: Gestiona las recompensas

Buenas prácticas recomendadas:

Controla las recompensas entregadas: Guarda en tu base de datos qué votos ya han recibido recompensas
Respeta el cooldown: Asegúrate de mantener el periodo de 24 horas entre votos
Maneja los errores: Gestiona los fallos de la API y comunica al jugador qué ha ocurrido
Registro de eventos: Guarda logs de las verificaciones para análisis y depuración

Flujo de ejemplo

Jugador: usa el comando /vote en el juego

↓

Servidor: abre el navegador con la página de votos

↓

Jugador: vota en la toplist

↓

Jugador: usa /claim o hace clic en "Reclamar recompensa"

↓

Servidor: llama a la API con la IP del jugador

↓

API: devuelve voted=true

↓

Servidor: entrega la recompensa

Solución de problemas

Error "Invalid API token"

Solución: Comprueba que estás usando el token correcto desde tu panel y que no incluye espacios o caracteres adicionales.

El voto no se detecta tras votar

Posibles causas:

El jugador usa VPN o proxy (la IP no coincide)
El voto aún no se ha procesado (espera 30 segundos e inténtalo de nuevo)
Se está enviando una IP incorrecta a la API
El jugador votó para otro servidor

Tiempo de espera o errores de conexión en la API

Solución: Asegúrate de que tu servidor pueda hacer solicitudes HTTPS salientes. Revisa la configuración del firewall e implementa reintentos con backoff exponencial.

Los jugadores reciben varias recompensas por un voto

Solución: Lleva un registro local de las recompensas entregadas para evitar duplicados.

Problemas con direcciones IPv6

Solución: Envía la dirección IPv6 completa. Nuestra API acepta IPv4 e IPv6.

Soporte y recursos

Soporte por correo

Recibe ayuda por email

Contactar soporte

Comunidad en Discord

Únete a nuestra comunidad

Entrar a Discord

Consejo pro

Prueba tu integración a fondo con una cuenta de pruebas antes de subirla a producción. Asegúrate de cubrir todos los casos y posibles errores.

Accesos directos

Navegación rápida