Vote-Belohnungs-API

Vote-Link

Schick Spieler auf diesen Link, mit ihrem Namen im Spiel in userid:

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

Du kommst von einer anderen Topliste? Du musst deinen Parameter nicht ändern. Wir lesen auch username, player_id, pingUsername, custom, postback, incentive und id. Namen dürfen Buchstaben, Ziffern, - und _ enthalten, bis zu 32 Zeichen.

Callback (Postback)

Lege in deinem Dashboard eine Callback-URL fest. Nach jedem Vote mit Spielernamen senden wir eine GET-Anfrage an diese URL, mit diesen Feldern im Query-String:

Jede Anfrage hat einen X-Signature: sha256=…-Header: ein HMAC-SHA256 der obigen Vote-Felder (in dieser Reihenfolge, URL-kodiert) mit deinem Callback-Secret. Prüfe ihn, damit niemand Votes fälschen kann, indem er deine URL aufruft. Wir versuchen es bis zu 3 Mal erneut, wenn dein Server nicht mit einem 2xx-Status antwortet. Enthält deine URL {userid}, ersetzen wir es durch den Spielernamen, für Skripte, die den Namen im Pfad erwarten.

Beispiel-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';

Nutze Test-Vote senden im Dashboard, um einen Callback für den Spieler TEST zu senden und die Antwort deines Servers zu sehen.

Vote4Buff-Abfrage

Jeder Vote gibt dem Spieler einen Buff, der 7 Tage hält, bis er wieder voten darf. Frag nach, ob der Buff eines Spielers aktiv ist, wenn er sich einloggt oder den Buff-NPC öffnet:

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"}

Bis zu 600 Anfragen pro Minute und Server. Votes, die Moderatoren als Betrug markieren, geben keinen Buff mehr.

Pull-API

Lieber selbst fragen, statt aufgerufen zu werden? Sende deinen API-Key im Header X-API-Key.

Hat dieser Spieler gevotet?

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"}

Noch nicht belohnte Votes

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"}]}

Votes als belohnt markieren

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

{"vote_ids":[1234,1235]}

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

Führe per Cronjob jede Minute erst unclaimed und dann claim aus, um Belohnungen genau einmal zu vergeben.

Grenzen

• Ein Vote pro Spieler alle 7 Tage pro Server, geprüft über IP und Spielernamen.
• Jeder Vote verlangt die Buchstaben aus einem Bild (Captcha).
• Die Pull-API liefert die Votes der letzten 7 Tage.