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
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
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
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
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++
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):
// 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:
// 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
},
{ // 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
},
};
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:
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:
// 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
¡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
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_IDys_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
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.
Recompila el núcleo del juego
Compila tu servidor con las nuevas modificaciones.
make clean && make Instalación en el cliente
Archivos de interfaz en Python
En la carpeta Client/root/:
- Copia
uivote4buff.pyen la carpetaroot/de tu cliente - Modifica los siguientes archivos según las instrucciones:
__constInfo.py__game.py__interfaceModule.py__uiAffectShower.py
Gráficos y scripts de UI
- Copia la carpeta
Client/ui/game/vote4buff/aui/game/en tus paquetes - Copia
Client/uiscript/vote4buffwindow.pyen tu carpeta de uiscripts
Archivos de idioma
Añade las cadenas de idioma desde Client/locale/:
- Anexa el contenido de
__locale_game.txta tu archivolocale_game.txt - Anexa el contenido de
__locale_interface.txta tu archivolocale_interface.txt
Idiomas disponibles: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ
Modificaciones del cliente en C++
En Source/Client/UserInterface/:
- Copia
M2WebSocket.cppyM2WebSocket.hen el directorio UserInterface - Aplica las modificaciones de los archivos con prefijo
__a tus archivos existentes - Asegúrate de que
libcurl.dllesté en tu directorio del cliente (32 bits incluido, descarga 64 bits si es necesario)
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.
Recompilar el cliente
Compila de nuevo tu ejecutable del cliente con las modificaciones.
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
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
¿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.
Primeros pasos - Guía rápida
Elige el método de integración que mejor se adapte a tus necesidades:
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
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
Pasos generales
Registra tu servidor
Crea una cuenta y añade tu servidor en nuestra toplist en https://metin2-toplist.net/servers/create
Obtén tus credenciales API
Encuentra tu ID de servidor y token API en tu panel. Son necesarios para la autenticación.
Elige el método de integración
Descarga Vote4Buff para una solución lista o integra nuestra API para una implementación personalizada.
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)
Si utilizas el sistema Vote4Buff (recomendado), esta API ya está integrada. Esta sección es para propietarios que deseen crear su propia implementación.
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 |
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:
{
"success": true,
"voted": true,
"last_vote": "2025-11-11T14:30:00Z",
"next_vote_in": 0,
"message": "Vote verified successfully"
}
{
"success": true,
"voted": false,
"message": "No recent vote found"
}
{
"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
<?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);
}
$result = checkVote('YOUR_API_TOKEN', $_SERVER['REMOTE_ADDR']);
if ($result['success'] && $result['voted']) {
echo "Vote verified! Rewarding player...";
}
?>
Ejemplo en Python
import requests
def check_vote(api_token, player_ip):
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)}'}
result = check_vote('YOUR_API_TOKEN', '123.456.789.012')
if result.get('success') and result.get('voted'):
print("Vote verified! Rewarding player...")
Ejemplo en C++ (para servidores)
#include <curl/curl.h>
#include <string>
#include <sstream>
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 = curl_easy_init();
if (!curl) return false;
std::string readBuffer;
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);
CURLcode res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
return (res == CURLE_OK) && (readBuffer.find("\"voted\":true") != std::string::npos);
}
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
if (CheckVote("YOUR_API_TOKEN", playerIP)) {
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
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 ${response.status}`);
return await response.json();
} catch (error) {
return { success: false, message: error.message };
}
}
checkVote('YOUR_API_TOKEN', '123.456.789.012').then(result => {
if (result.success && result.voted) {
console.log('Vote verified! Rewarding player...');
}
});
Guía de integración
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
votedes 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
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.
Public Server Listing API (v1)
List, submit, and claim Metin2 servers programmatically. Perfect for other toplists, server management tools, or custom integrations.
https://metin2-toplist.net/api/v1
Rate Limits
| Endpoint | Method | Limit | Auth |
|---|---|---|---|
/api/v1/servers | GET | 60/min | — |
/api/v1/servers/{slug} | GET | 60/min | — |
/api/v1/servers | POST | 3/hour | — |
/api/v1/servers/claim | POST | 10/hour | ✅ |
List Servers
Retrieve a paginated list of active, launched servers. Supports filtering by category and language.
| Parameter | Type | Default | Description |
|---|---|---|---|
category | string | — | Filter by category: oldschool, newschool, fun, pvp, pvm, pve |
language | string | — | Filter by language code: EN, DE, TR, etc. |
sort | string | votes | Sort order: votes, newest, name |
page | integer | 1 | Page number |
per_page | integer | 25 | Results per page (max 50) |
curl -H "Accept: application/json" \
"https://metin2-toplist.net/api/v1/servers?category=pvp&language=EN&per_page=10"
Submit a New Server
Submit a new server listing via the API. The server enters a moderation queue and must be approved before it appears publicly.
All API-submitted servers start as inactive and require manual approval. This prevents spam and ensures listing quality.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Server name (max 255 chars, must be unique) |
description | string | ✅ | Server description (min 20, max 5000 chars) |
website_url | string | — | Server website URL |
discord_url | string | — | Discord invite URL |
languages | array | ✅ | Language codes, e.g. ["EN", "DE"] (min 1, max 5) |
category | string | — | One of: oldschool, newschool, fun, pvp, pvm, pve |
launch_date | string | — | Future launch date (YYYY-MM-DD) |
owner_email | string | — | Contact email (optional, not shown publicly) |
curl -X POST "https://metin2-toplist.net/api/v1/servers" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"name": "Dragon Kingdom",
"description": "A classic PvP experience with custom dungeons and weekly events.",
"languages": ["EN", "DE"],
"category": "pvp",
"website_url": "https://dragon-kingdom.com",
"discord_url": "https://discord.gg/example"
}'
{
"success": true,
"message": "Server submitted successfully!",
"data": {
"id": 42,
"slug": "dragon-kingdom",
"status": "pending_review"
},
"claim_token": "a1b2c3d4...80 characters",
"note": "Save this token! Use it to claim your listing."
}
Claim Token System
When you submit a server, you receive a unique 80-character claim token. This token lets you link the listing to your account later.
The claim token is shown only once in the API response. Save it immediately — we store only the hash.
Submit
POST your server to /api/v1/servers and save the claim_token from the response.
Register
Create an account and paste the token in the optional "Claim Token" field.
Manage
Your server is now linked to your account with full dashboard access.
Error Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Server created (pending review) |
401 | Authentication required (claim endpoint) |
404 | Server not found / invalid claim token |
409 | Server already claimed |
410 | Claim token expired |
422 | Validation error / spam rejected |
429 | Rate limit exceeded |
Integration Examples
$response = file_get_contents('https://metin2-toplist.net/api/v1/servers?per_page=10');
$data = json_decode($response, true);
foreach ($data['data'] as $server) {
echo $server['name'] . ' — ' . $server['vote_count'] . ' votes' . PHP_EOL;
}
const res = await fetch('https://metin2-toplist.net/api/v1/servers?category=pvp');
const { data, meta } = await res.json();
data.forEach(server => {
console.log(`${server.name}: ${server.vote_count} votes`);
});
import requests
resp = requests.get('https://metin2-toplist.net/api/v1/servers', params={
'language': 'DE',
'sort': 'newest',
'per_page': 20
})
servers = resp.json()['data']
for s in servers:
print(f"{s['name']} — {s['vote_count']} votes")
Soporte y recursos
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.