Cómo Funciona
La API Vote Rewards de metin2.gg permite a tu servidor Metin2 detectar automáticamente cuando los jugadores votan y otorgar recompensas en el juego. El flujo es simple: los jugadores votan en metin2.gg con su nombre de personaje, y tu servidor consulta nuestra API para verificar y reclamar esos votos.
Hay dos modos de integración — elige el que se adapte a tu configuración:
Polling (Recomendado)
Tu servidor llama periódicamente a nuestra API para verificar nuevos votos. Lo más sencillo de implementar — funciona con cualquier configuración de servidor Metin2. Solo añade una solicitud HTTP al código de tu servidor de juego.
Webhooks (Avanzado)
metin2.gg envía una notificación a tu servidor en el instante en que un jugador vota. En tiempo real, pero requiere un endpoint HTTPS accesible públicamente de tu lado.
Autenticación
Todas las solicitudes de la API requieren una clave API enviada mediante el encabezado X-API-Key. Las claves siguen el formato mg_live_... y se generan desde el panel de tu servidor.
X-API-Key: mg_live_5bef...1a70Tu clave API está vinculada a un servidor y se muestra solo una vez al generarla. Si la pierdes, regenera una nueva desde el panel (la clave anterior se invalida inmediatamente).
Cómo Obtener Tu Clave API
- 1Ve a Mi Panel → Mis Servidores. Haz clic en el nombre de tu servidor para abrir su página de gestión.
- 2En la página de gestión, verifica la propiedad (registro DNS TXT o meta tag) si aún no lo has hecho.
- 3Añade un enlace de retorno a metin2.gg en el sitio web de tu servidor para desbloquear el estado de Socio.
- 4En la página de gestión de tu servidor, haz clic en el botón "Configuración de API". Luego haz clic en "Generar Clave API" y cópiala — solo se muestra una vez.
Verificar Estado del Voto
Verifica si un jugador específico tiene un voto no reclamado. Si existe un voto pendiente, se reclama automáticamente (se marca como usado) para que el mismo voto no pueda reclamarse dos veces.
GET /api/v1/vote/check?player_id=PlayerName HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HEREParámetros de Consulta
| Parameter | Type | Required | Description |
|---|---|---|---|
| player_id | string | Yes | El nombre del personaje que el jugador usó al votar. No distingue mayúsculas de minúsculas. |
Respuesta
El jugador tiene un voto no reclamado (ahora reclamado)
{
"voted": true,
"player_id": "PlayerName",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"voted_at": "2026-03-02T14:30:00Z"
}No hay voto pendiente para este jugador
{
"voted": false
}Listar Votos No Reclamados
Obtén todos los votos no reclamados de tu servidor. Útil para procesamiento por lotes — por ejemplo, un cron job que se ejecuta cada 5 minutos y otorga recompensas para todos los votos pendientes de una vez.
GET /api/v1/vote/unclaimed?limit=50 HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HEREParámetros de Consulta
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Número máximo de votos a devolver (1–100, predeterminado 50). |
Respuesta
{
"votes": [
{
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"player_id": "PlayerName",
"voted_at": "2026-03-02T14:30:00Z"
},
{
"vote_id": "660e8400-e29b-41d4-a716-446655440001",
"player_id": "AnotherPlayer",
"voted_at": "2026-03-02T14:32:00Z"
}
],
"total": 2
}Reclamar Votos por Lotes
Marca múltiples votos como reclamados en una sola solicitud. Usa esto después de procesar votos del endpoint unclaimed.
POST /api/v1/vote/claim HTTP/1.1
Host: metin2.gg
Content-Type: application/json
X-API-Key: mg_live_YOUR_KEY_HERE
{
"vote_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
]
}Cuerpo de la Solicitud (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| vote_ids | string[] | Yes | Array de UUIDs de votos a reclamar. Máximo 100 por solicitud. |
Respuesta
{
"claimed": 2,
"failed": 0
}Webhooks
En lugar de polling, puedes recibir notificaciones push en tiempo real cuando un jugador vota. Configura tu URL de webhook en el panel del servidor en Configuración de API.
Payload del Webhook
POST https://your-server.com/api/vote-webhook HTTP/1.1
Content-Type: application/json
X-Metin2GG-Signature: a1b2c3d4e5f6...
{
"event": "vote.created",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"server_id": "your-server-uuid",
"player_id": "PlayerName",
"voted_at": "2026-03-02T14:30:00Z",
"timestamp": "2026-03-02T14:30:01Z"
}Verificación de la Firma
Cada solicitud de webhook incluye un encabezado X-Metin2GG-Signature que contiene un digest hex HMAC-SHA256 del cuerpo crudo de la solicitud, firmado con tu secreto API. Siempre verifica esta firma antes de confiar en el payload.
import hmac
import hashlib
def verify_webhook(request_body: bytes, signature: str, secret: str) -> bool:
"""Verify the X-Metin2GG-Signature header."""
expected = hmac.new(
secret.encode("utf-8"),
request_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, signature)
# Usage in your webhook handler:
# body = request.body (raw bytes)
# sig = request.headers["X-Metin2GG-Signature"]
# if not verify_webhook(body, sig, "your_api_secret"):
# return HttpResponse(status=403)<?php
function verifyWebhook(string $body, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $body, $secret);
return hash_equals($expected, $signature);
}
// Usage in your webhook handler:
// $body = file_get_contents('php://input');
// $sig = $_SERVER['HTTP_X_METIN2GG_SIGNATURE'] ?? '';
// if (!verifyWebhook($body, $sig, 'your_api_secret')) {
// http_response_code(403);
// exit('Invalid signature');
// }Integración Metin2: Comando Python
Coloca este script en el sistema de comandos Python de tu servidor de juego. Cuando un jugador escribe /reward en el juego, verifica metin2.gg para un voto pendiente y otorga la recompensa.
# vote_reward.py — Drop into your game server's command scripts
# Works with Python 2.7+ (common in Metin2 servers)
import json
import os
METIN2GG_API_KEY = "mg_live_YOUR_KEY_HERE"
METIN2GG_API_URL = "https://metin2.gg/api/v1/vote/check"
def check_vote(player_name):
"""Check if player has a pending vote and auto-claim it."""
url = "%s?player_id=%s" % (METIN2GG_API_URL, player_name)
# Method 1: Use urllib2 (Python 2) or urllib.request (Python 3)
try:
try:
import urllib2
req = urllib2.Request(url)
req.add_header("X-API-Key", METIN2GG_API_KEY)
resp = urllib2.urlopen(req, timeout=5)
data = json.loads(resp.read())
except ImportError:
import urllib.request
req = urllib.request.Request(url)
req.add_header("X-API-Key", METIN2GG_API_KEY)
resp = urllib.request.urlopen(req, timeout=5)
data = json.loads(resp.read().decode("utf-8"))
return data.get("voted", False)
except Exception:
pass
# Method 2: Fallback to curl (works even with broken SSL)
try:
cmd = 'curl -s -H "X-API-Key: %s" "%s"' % (METIN2GG_API_KEY, url)
raw = os.popen(cmd).read()
data = json.loads(raw)
return data.get("voted", False)
except Exception:
return None
# Example usage in your game command handler:
# def cmd_reward(player):
# result = check_vote(player.GetName())
# if result is True:
# player.GiveItem(50011, 10) # Example: 10x Dragon God Coins
# player.ChatInfoMessage("Vote reward claimed!")
# elif result is False:
# player.ChatInfoMessage("No pending vote. Vote at metin2.gg!")
# else:
# player.ChatInfoMessage("Could not reach metin2.gg. Try again.")Integración Metin2: Archivo Quest (Lua)
Este archivo quest crea una interacción NPC donde los jugadores pueden verificar el estado de su voto. Llama a un comando del lado del servidor que activa la verificación de voto Python.
quest vote_reward begin
state start begin
when login or letter begin
send_letter("Vote Reward")
end
when button or info begin
say_title("Vote Reward")
say("")
say("Vote for our server on metin2.gg")
say("and claim your reward here!")
say("")
local s = select("Check My Vote", "How to Vote", "Close")
if s == 1 then
-- Triggers the Python command that checks the API
cmdchat("checkvote "..pc.get_name())
elseif s == 2 then
say_title("How to Vote")
say("")
say("1. Open metin2.gg in your browser")
say("2. Find our server page")
say("3. Enter your character name")
say("4. Click the Vote button")
say("5. Come back here to claim your reward!")
say("")
end
end
end
endIntegración Metin2: Panel Web PHP
Si tu servidor tiene un panel web (basado en PHP), usa este snippet para verificar y reclamar votos desde el panel. Funciona con cualquier entorno PHP 7+ con cURL.
<?php
/**
* check_vote.php — Vote check for PHP-based web panels
* Requires PHP 7.0+ with cURL extension
*/
$apiKey = "mg_live_YOUR_KEY_HERE";
$playerName = $_GET["player"] ?? "";
if (empty($playerName)) {
echo json_encode(["error" => "Missing player name"]);
exit;
}
// Check vote status
$ch = curl_init(
"https://metin2.gg/api/v1/vote/check?player_id=" . urlencode($playerName)
);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
echo json_encode(["error" => "API returned HTTP $httpCode"]);
exit;
}
$data = json_decode($response, true);
if ($data["voted"] ?? false) {
// Player has voted — grant reward via your game DB
// Example: INSERT INTO player.reward_queue (player, item_vnum, count) ...
echo json_encode([
"success" => true,
"message" => "Vote reward granted!",
"vote_id" => $data["vote_id"],
]);
} else {
echo json_encode([
"success" => false,
"message" => "No pending vote found.",
]);
}Límites de Tasa y Códigos de Error
La API impone límites de tasa para asegurar un uso justo. Límites actuales:
- 60 requests per minute per API key
- 1,000 requests per hour per API key
| Estado | Descripción |
|---|---|
| 200 OK | Solicitud exitosa. |
| 400 Bad Request | Parámetros faltantes o inválidos. Verifica el formato de player_id o vote_ids. |
| 401 Unauthorized | Clave API faltante o inválida. Asegúrate de incluir el encabezado X-API-Key. |
| 403 Forbidden | El acceso a la API está deshabilitado — generalmente porque el enlace de retorno fue eliminado. Añade nuevamente el enlace y verifica. |
| 404 Not Found | El endpoint no existe. Verifica nuevamente la ruta de la URL. |
| 429 Too Many Requests | Límite de tasa excedido. Espera y reintenta después del valor del encabezado Retry-After (en segundos). |
| 500 Internal Server Error | Algo salió mal de nuestro lado. Reintenta después de unos segundos. |
Estrategia de Reintento
On 429 errors, read the Retry-After header (value in seconds) and wait before retrying. For 500 errors, retry with exponential backoff (1s, 2s, 4s).
FAQ Solución de Problemas
Recibo 401 Unauthorized en cada solicitud
Asegúrate de enviar la clave API en el encabezado X-API-Key (no como parámetro de consulta ni en el cuerpo). La clave debe comenzar con mg_live_.
La API dice voted: false pero el jugador afirma que votó
El jugador pudo haber votado sin ingresar su nombre de personaje, o usado un nombre diferente. Verifica la URL del enlace de voto — debe incluir ?player_id=NOMBRE_EXACTO. Los nombres no distinguen mayúsculas.
Recibo 403 Forbidden
Tu acceso a la API está pausado, probablemente porque el enlace de retorno a metin2.gg fue eliminado de tu sitio. Añádelo de nuevo y haz clic en 'Verificar Ahora' en el panel para re-verificar.
¿Puedo probar la API sin votos reales?
Actualmente no hay modo sandbox. Vota en tu propia lista de servidor con un nombre de personaje de prueba para verificar la integración de extremo a extremo.
Mi script Python no puede conectarse (timeout o error SSL)
La mayoría de los servidores Metin2 usan Python 2.7 que tiene certificados SSL desactualizados. Usa el respaldo os.popen('curl ...') mostrado en el ejemplo Python, o actualiza el paquete CA de Python de tu servidor.
¿Con qué frecuencia debo consultar la API?
Para el endpoint /check (por jugador): llámalo cuando el jugador solicite su recompensa (ej. comando /reward). Para /unclaimed (por lotes): cada 3–5 minutos vía cron es ideal. No consultes más de una vez por minuto.
¿Pueden varios servidores compartir una clave API?
No. Cada clave API está vinculada a una lista de servidor. Si operas múltiples servidores, genera una clave separada para cada uno desde sus respectivas páginas del panel.
¿Qué pasa si mi endpoint de webhook está caído?
metin2.gg reintenta las entregas de webhook fallidas hasta 5 veces con retroceso exponencial. Si todos los intentos fallan, el voto permanece no reclamado y aún puede obtenerse a través de los endpoints de polling.
¿Listo para Integrar?
Añade tu servidor a metin2.gg, genera una clave API y comienza a recompensar a los votantes en minutos.