Come Funziona
L'API Vote Rewards di metin2.gg consente al tuo server Metin2 di rilevare automaticamente quando i giocatori votano e assegnare ricompense nel gioco. Il flusso è semplice: i giocatori votano su metin2.gg con il nome del personaggio, e il tuo server interroga la nostra API per verificare e riscattare quei voti.
Ci sono due modalità di integrazione — scegli quella adatta alla tua configurazione:
Polling (Consigliato)
Il tuo server chiama periodicamente la nostra API per verificare nuovi voti. Il più semplice da implementare — funziona con qualsiasi configurazione di server Metin2. Basta aggiungere una richiesta HTTP al codice del tuo game server.
Webhooks (Avanzato)
metin2.gg invia una notifica al tuo server nel momento in cui un giocatore vota. In tempo reale, ma richiede un endpoint HTTPS accessibile pubblicamente dal tuo lato.
Autenticazione
Tutte le richieste API richiedono una chiave API inviata tramite l'header X-API-Key. Le chiavi seguono il formato mg_live_... e vengono generate dal pannello del tuo server.
X-API-Key: mg_live_5bef...1a70La tua chiave API è legata a un singolo server e viene mostrata solo una volta alla generazione. Se la perdi, rigenerane una nuova dal pannello (la vecchia chiave viene invalidata immediatamente).
Come Ottenere la Tua Chiave API
- 1Vai su Il Mio Pannello → I Miei Server. Clicca sul nome del tuo server per aprire la pagina di gestione.
- 2Nella pagina di gestione, verifica la proprietà (record DNS TXT o meta tag) se non l'hai già fatto.
- 3Aggiungi un backlink a metin2.gg sul sito del tuo server per sbloccare lo stato Partner.
- 4Nella pagina di gestione del tuo server, clicca sul pulsante "Impostazioni API". Poi clicca su "Genera Chiave API" e copiala — viene mostrata una sola volta.
Verifica Stato del Voto
Verifica se un giocatore specifico ha un voto non riscattato. Se esiste un voto in sospeso, viene automaticamente riscattato (segnato come usato) così lo stesso voto non può essere riscattato due volte.
GET /api/v1/vote/check?player_id=PlayerName HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HEREParametri di Query
| Parameter | Type | Required | Description |
|---|---|---|---|
| player_id | string | Yes | Il nome del personaggio che il giocatore ha usato per votare. Non sensibile alle maiuscole. |
Risposta
Il giocatore ha un voto non riscattato (ora riscattato)
{
"voted": true,
"player_id": "PlayerName",
"vote_id": "550e8400-e29b-41d4-a716-446655440000",
"voted_at": "2026-03-02T14:30:00Z"
}Nessun voto in sospeso per questo giocatore
{
"voted": false
}Elenca Voti Non Riscattati
Recupera tutti i voti non riscattati per il tuo server. Utile per l'elaborazione in batch — ad esempio, un cron job che gira ogni 5 minuti e assegna ricompense per tutti i voti in sospeso in una volta.
GET /api/v1/vote/unclaimed?limit=50 HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HEREParametri di Query
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Numero massimo di voti da restituire (1–100, predefinito 50). |
Risposta
{
"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
}Riscatta Voti in Batch
Segna più voti come riscattati in una singola richiesta. Usa questo dopo aver elaborato i voti dall'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 della Richiesta (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| vote_ids | string[] | Yes | Array di UUID dei voti da riscattare. Massimo 100 per richiesta. |
Risposta
{
"claimed": 2,
"failed": 0
}Webhooks
Invece del polling, puoi ricevere notifiche push in tempo reale quando un giocatore vota. Configura il tuo URL webhook nel pannello del server sotto Impostazioni 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"
}Verifica della Firma
Ogni richiesta webhook include un header X-Metin2GG-Signature contenente un digest hex HMAC-SHA256 del corpo grezzo della richiesta, firmato con il tuo segreto API. Verifica sempre questa firma prima di fidarti del 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');
// }Integrazione Metin2: Comando Python
Inserisci questo script nel sistema di comandi Python del tuo game server. Quando un giocatore digita /reward nel gioco, controlla metin2.gg per un voto in sospeso e assegna la ricompensa.
# 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.")Integrazione Metin2: File Quest (Lua)
Questo file quest crea un'interazione NPC dove i giocatori possono verificare lo stato del voto. Chiama un comando lato server che attiva la verifica del 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
endIntegrazione Metin2: Pannello Web PHP
Se il tuo server ha un pannello web (basato su PHP), usa questo snippet per verificare e riscattare voti dal pannello. Funziona con qualsiasi ambiente 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.",
]);
}Limiti di Frequenza e Codici di Errore
L'API impone limiti di frequenza per garantire un utilizzo equo. Limiti attuali:
- 60 requests per minute per API key
- 1,000 requests per hour per API key
| Stato | Descrizione |
|---|---|
| 200 OK | Richiesta riuscita. |
| 400 Bad Request | Parametri mancanti o non validi. Controlla il formato di player_id o vote_ids. |
| 401 Unauthorized | Chiave API mancante o non valida. Assicurati di includere l'header X-API-Key. |
| 403 Forbidden | L'accesso API è disabilitato — di solito perché il backlink è stato rimosso. Aggiungi nuovamente il backlink e controlla. |
| 404 Not Found | L'endpoint non esiste. Ricontrolla il percorso dell'URL. |
| 429 Too Many Requests | Limite di frequenza superato. Attendi e riprova dopo il valore dell'header Retry-After (in secondi). |
| 500 Internal Server Error | Qualcosa è andato storto dalla nostra parte. Riprova dopo qualche secondo. |
Strategia di Riprova
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 Risoluzione Problemi
Ricevo 401 Unauthorized ad ogni richiesta
Assicurati di inviare la chiave API nell'header X-API-Key (non come parametro di query o nel corpo). La chiave deve iniziare con mg_live_.
L'API dice voted: false ma il giocatore afferma di aver votato
Il giocatore potrebbe aver votato senza inserire il nome del personaggio, o usato un nome diverso. Controlla l'URL del link di voto — deve includere ?player_id=NOME_ESATTO. I nomi non sono sensibili alle maiuscole.
Ricevo 403 Forbidden
Il tuo accesso API è in pausa, probabilmente perché il backlink a metin2.gg è stato rimosso dal tuo sito. Aggiungilo di nuovo e clicca su 'Verifica Ora' nel pannello per ri-verificare.
Posso testare l'API senza voti reali?
Attualmente non c'è modalità sandbox. Vota sulla tua stessa inserzione del server con un nome di personaggio di test per verificare l'integrazione end-to-end.
Il mio script Python non riesce a connettersi (timeout o errore SSL)
La maggior parte dei server Metin2 usa Python 2.7 che ha certificati SSL obsoleti. Usa il fallback os.popen('curl ...') mostrato nell'esempio Python, o aggiorna il bundle CA Python del tuo server.
Quanto spesso dovrei interrogare l'API?
Per l'endpoint /check (per giocatore): chiamalo quando il giocatore richiede la ricompensa (es. comando /reward). Per /unclaimed (batch): ogni 3–5 minuti via cron è ideale. Non interrogare più di una volta al minuto.
Più server possono condividere una chiave API?
No. Ogni chiave API è legata a un'inserzione di server. Se gestisci più server, genera una chiave separata per ciascuno dalle rispettive pagine del pannello.
Cosa succede se il mio endpoint webhook è inattivo?
metin2.gg riprova le consegne webhook fallite fino a 5 volte con backoff esponenziale. Se tutti i tentativi falliscono, il voto resta non riscattato e può ancora essere recuperato tramite gli endpoint di polling.
Pronto per l'Integrazione?
Aggiungi il tuo server a metin2.gg, genera una chiave API e inizia a premiare i votanti in pochi minuti.