Como Funciona
A API Vote Rewards do metin2.gg permite que seu servidor Metin2 detecte automaticamente quando jogadores votam e conceda recompensas no jogo. O fluxo é simples: jogadores votam no metin2.gg com o nome do personagem, e seu servidor consulta nossa API para verificar e reivindicar esses votos.
Existem dois modos de integração — escolha o que se encaixa na sua configuração:
Polling (Recomendado)
Seu servidor chama periodicamente nossa API para verificar novos votos. Mais simples de implementar — funciona com qualquer configuração de servidor Metin2. Basta adicionar uma requisição HTTP ao código do seu servidor.
Webhooks (Avançado)
metin2.gg envia uma notificação ao seu servidor no instante em que um jogador vota. Tempo real, mas requer um endpoint HTTPS acessível publicamente do seu lado.
Autenticação
Todas as requisições da API requerem uma chave API enviada pelo cabeçalho X-API-Key. As chaves seguem o formato mg_live_... e são geradas no painel do seu servidor.
X-API-Key: mg_live_5bef...1a70Sua chave API está vinculada a um servidor e é mostrada apenas uma vez quando gerada. Se perdê-la, regenere uma nova no painel (a chave antiga é invalidada imediatamente).
Como Obter Sua Chave API
- 1Vá para Meu Painel → Meus Servidores. Clique no nome do seu servidor para abrir a página de gerenciamento.
- 2Na página de gerenciamento, verifique a propriedade (registro DNS TXT ou meta tag) se ainda não o fez.
- 3Adicione um backlink para metin2.gg no site do seu servidor para desbloquear o status de Parceiro.
- 4Na página de gerenciamento do seu servidor, clique no botão "Configurações da API". Em seguida, clique em "Gerar Chave API" e copie-a — é mostrada apenas uma vez.
Verificar Status do Voto
Verifique se um jogador específico tem um voto não reivindicado. Se existir um voto pendente, ele é automaticamente reivindicado (marcado como usado) para que o mesmo voto não possa ser reivindicado duas vezes.
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 | O nome do personagem que o jogador usou ao votar. Não diferencia maiúsculas de minúsculas. |
Resposta
Jogador tem um voto não reivindicado (agora reivindicado)
{
"voted": true,
"player_id": "PlayerName",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"voted_at": "2026-03-02T14:30:00Z"
}Nenhum voto pendente para este jogador
{
"voted": false
}Listar Votos Não Reivindicados
Obtenha todos os votos não reivindicados do seu servidor. Útil para processamento em lote — por exemplo, um cron job que roda a cada 5 minutos e concede recompensas para todos os votos pendentes de uma 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 retornar (1–100, padrão 50). |
Resposta
{
"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
}Reivindicar Votos em Lote
Marque múltiplos votos como reivindicados em uma única requisição. Use isto após processar votos do 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"
]
}Corpo da Requisição (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| vote_ids | string[] | Yes | Array de UUIDs de votos para reivindicar. Máximo de 100 por requisição. |
Resposta
{
"claimed": 2,
"failed": 0
}Webhooks
Em vez de polling, você pode receber notificações push em tempo real quando um jogador vota. Configure a URL do webhook no painel do servidor em Configurações da API.
Payload do 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"
}Verificando a Assinatura
Cada requisição de webhook inclui um cabeçalho X-Metin2GG-Signature contendo um digest hex HMAC-SHA256 do corpo bruto da requisição, assinado com seu segredo API. Sempre verifique esta assinatura antes de confiar no 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');
// }Integração Metin2: Comando Python
Coloque este script no sistema de comandos Python do seu servidor de jogo. Quando um jogador digita /reward no jogo, ele verifica o metin2.gg para um voto pendente e concede a 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.")Integração Metin2: Arquivo Quest (Lua)
Este arquivo quest cria uma interação NPC onde jogadores podem verificar o status do voto. Ele chama um comando server-side que aciona a verificação 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
endIntegração Metin2: Painel Web PHP
Se seu servidor tem um painel web (baseado em PHP), use este snippet para verificar e reivindicar votos do painel. Funciona com qualquer ambiente PHP 7+ com 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.",
]);
}Limites de Taxa e Códigos de Erro
A API impõe limites de taxa para garantir uso justo. Limites atuais:
- 60 requests per minute per API key
- 1,000 requests per hour per API key
| Status | Descrição |
|---|---|
| 200 OK | Requisição bem-sucedida. |
| 400 Bad Request | Parâmetros ausentes ou inválidos. Verifique o formato de player_id ou vote_ids. |
| 401 Unauthorized | Chave API ausente ou inválida. Certifique-se de incluir o cabeçalho X-API-Key. |
| 403 Forbidden | Acesso à API desabilitado — geralmente porque o backlink foi removido. Adicione o backlink novamente e verifique. |
| 404 Not Found | O endpoint não existe. Verifique novamente o caminho da URL. |
| 429 Too Many Requests | Limite de taxa excedido. Aguarde e tente novamente após o valor do cabeçalho Retry-After (em segundos). |
| 500 Internal Server Error | Algo deu errado do nosso lado. Tente novamente após alguns segundos. |
Estratégia de Retentativa
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 de Solução de Problemas
Recebo 401 Unauthorized em toda requisição
Certifique-se de enviar a chave API no cabeçalho X-API-Key (não como parâmetro de consulta ou no corpo). A chave deve começar com mg_live_.
A API diz voted: false mas o jogador afirma que votou
O jogador pode ter votado sem inserir o nome do personagem, ou usado um nome diferente. Verifique a URL do link de voto — deve incluir ?player_id=NOME_EXATO. Os nomes não diferenciam maiúsculas de minúsculas.
Recebo 403 Forbidden
Seu acesso à API está pausado, provavelmente porque o backlink para metin2.gg foi removido do seu site. Adicione novamente e clique em 'Verificar Agora' no painel para re-verificar.
Posso testar a API sem votos reais?
Atualmente não há modo sandbox. Vote na sua própria listagem de servidor com um nome de personagem de teste para verificar a integração de ponta a ponta.
Meu script Python não consegue conectar (timeout ou erro SSL)
A maioria dos servidores Metin2 usa Python 2.7 que tem certificados SSL desatualizados. Use o fallback os.popen('curl ...') mostrado no exemplo Python, ou atualize o pacote CA do Python do seu servidor.
Com que frequência devo fazer polling na API?
Para o endpoint /check (por jogador): chame quando o jogador solicitar sua recompensa (ex. comando /reward). Para /unclaimed (em lote): a cada 3–5 minutos via cron é ideal. Não faça polling mais de uma vez por minuto.
Múltiplos servidores podem compartilhar uma chave API?
Não. Cada chave API está vinculada a uma listagem de servidor. Se você opera múltiplos servidores, gere uma chave separada para cada um nas respectivas páginas do painel.
O que acontece se meu endpoint de webhook estiver fora do ar?
metin2.gg retenta entregas de webhook falhadas até 5 vezes com backoff exponencial. Se todas as tentativas falharem, o voto permanece não reivindicado e ainda pode ser obtido pelos endpoints de polling.
Pronto para Integrar?
Adicione seu servidor ao metin2.gg, gere uma chave API e comece a recompensar votantes em minutos.