API ricompense voto

Link di voto

Manda i giocatori a questo link, con il loro nome in gioco in userid:

https://metin2privateservers.com/vote/YOUR-SERVER-SLUG?userid=PLAYER_NAME

Arrivi da un'altra toplist? Non serve cambiare il parametro. Leggiamo anche username, player_id, pingUsername, custom, postback, incentive e id. I nomi possono contenere lettere, numeri, - e _, fino a 32 caratteri.

Callback (postback)

Imposta un URL di callback nella tua dashboard. Dopo ogni voto con un nome giocatore, inviamo una richiesta GET a quell'URL con questi campi aggiunti alla query string:

Ogni richiesta ha un header X-Signature: sha256=…: un HMAC-SHA256 dei campi di voto sopra (in quest'ordine, codificati URL) calcolato con il tuo secret di callback. Controllalo, così nessuno può falsificare voti chiamando il tuo URL. Riproviamo fino a 3 volte se il tuo server non risponde con uno stato 2xx. Se il tuo URL contiene {userid}, lo sostituiamo con il nome del giocatore, per gli script che si aspettano il nome nel percorso.

Esempio di handler in PHP:

<?php
// vote-callback.php on your server
$secret = 'YOUR_CALLBACK_SECRET';           // from your dashboard

$query = $_SERVER['QUERY_STRING'];
// The signature covers the vote fields, which are always appended last.
$fields = ['userid','userip','voted','reset','server','vote_id','timestamp'];
$parts = [];
foreach ($fields as $f) { $parts[] = $f . '=' . rawurlencode($_GET[$f] ?? ''); }
$signed = implode('&', $parts);
$expected = 'sha256=' . hash_hmac('sha256', $signed, $secret);
$given = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

if (!hash_equals($expected, $given)) { http_response_code(403); exit('bad signature'); }
if (($_GET['voted'] ?? '0') !== '1') { exit('ignored'); }
if (abs(time() - (int)$_GET['timestamp']) > 300) { http_response_code(400); exit('too old'); }

$player = $_GET['userid'];
$voteId = (int)$_GET['vote_id'];
// TODO: skip if $voteId was already rewarded, then give the reward to $player.
echo 'ok';

Usa Invia un voto di prova nella dashboard per inviare un callback per il giocatore TEST e vedere la risposta del tuo server.

Controllo Vote4Buff

Ogni voto dà al giocatore un buff che dura 7 giorni, finché non può votare di nuovo. Chiedi se il buff di un giocatore è attivo quando entra in gioco o apre l'NPC dei buff:

GET https://metin2privateservers.com/api/v1/vote4buff?userid=PLAYER_NAME
X-API-Key: YOUR_API_KEY

{"userid":"PLAYER_NAME","voted":true,"buff_active":true,"vote_id":1234,
 "voted_at":"2026-11-09T18:02:11.000Z","buff_expires_at":"2026-11-16T18:02:11.000Z",
 "next_vote_at":"2026-11-16T18:02:11.000Z","seconds_left":604700}

{"userid":"PLAYER_NAME","voted":false,"buff_active":false,"vote_url":"/vote/your-server?userid=PLAYER_NAME"}

Fino a 600 richieste al minuto per server. I voti segnalati come frode dai moderatori smettono di dare il buff.

API pull

Preferisci chiedere invece di essere chiamato? Invia la tua chiave API nell'header X-API-Key.

Questo giocatore ha votato?

GET https://metin2privateservers.com/api/v1/votes/check?userid=PLAYER_NAME

{"voted":true,"userid":"PLAYER_NAME","vote_id":1234,"claimed":false,
 "voted_at":"2026-11-09T18:02:11.000Z","next_vote_at":"2026-11-10T06:02:11.000Z"}

Voti non ancora premiati

GET https://metin2privateservers.com/api/v1/votes/unclaimed?limit=50

{"votes":[{"vote_id":1234,"userid":"PLAYER_NAME","created_at":"2026-11-09T18:02:11.000Z"}]}

Segna i voti come premiati

POST https://metin2privateservers.com/api/v1/votes/claim
Content-Type: application/json

{"vote_ids":[1234,1235]}

{"claimed":[1234,1235],"already_claimed_or_unknown":[]}

Esegui unclaimed e poi claim ogni minuto da un cron job per dare le ricompense esattamente una volta.

Limiti

• Un voto per giocatore ogni 7 giorni per server, controllato tramite IP e nome del giocatore.
• Ogni voto richiede le lettere di un'immagine (captcha).
• L'API pull restituisce i voti degli ultimi 7 giorni.