Oy ödülü API'si

Oy linki

Oyuncuları, oyun içi adları userid içinde olacak şekilde bu linke gönder:

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

Başka bir toplistten mi geliyorsun? Parametreni değiştirmene gerek yok. username, player_id, pingUsername, custom, postback, incentive ve id parametrelerini de okuruz. Adlarda harf, rakam, - ve _ kullanılabilir, en fazla 32 karakter.

Callback (postback)

Panelinde bir callback URL'si ayarla. Oyuncu adı içeren her oydan sonra o URL'ye, query string'e şu alanlar eklenmiş bir GET isteği göndeririz:

Her istekte bir X-Signature: sha256=… header'ı bulunur: yukarıdaki oy alanlarının (bu sırayla, URL kodlanmış) callback secret'ınla hesaplanmış HMAC-SHA256 değeri. Bunu kontrol et ki kimse URL'ni çağırarak sahte oy üretemesin. Serverin 2xx durum koduyla yanıt vermezse en fazla 3 kez yeniden deneriz. URL'n {userid} içeriyorsa, adı yolda bekleyen scriptler için bunu oyuncu adıyla değiştiririz.

PHP ile örnek handler:

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

TEST oyuncusu için bir callback göndermek ve serverinin yanıtını görmek için paneldeki Test oyu gönder düğmesini kullan.

Vote4Buff kontrolü

Her oy, oyuncuya tekrar oy verebileceği zamana kadar 7 gün süren bir buff verir. Oyuncu giriş yaptığında veya buff NPC'sini açtığında buff'ının aktif olup olmadığını sor:

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

Server başına dakikada en fazla 600 istek. Moderatörlerin hile olarak işaretlediği oylar artık buff vermez.

Pull API

Çağrılmak yerine sormayı mı tercih edersin? API anahtarını X-API-Key header'ında gönder.

Bu oyuncu oy verdi mi?

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

Henüz ödüllendirilmemiş oylar

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

Oyları ödüllendirildi olarak işaretle

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

{"vote_ids":[1234,1235]}

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

Ödülleri tam olarak bir kez vermek için bir cron job ile her dakika önce unclaimed, sonra claim çalıştır.

Sınırlar

• Her server için her oyuncu 7 günde bir oy verebilir; IP'ye ve oyuncu adına göre kontrol edilir.
• Her oy için bir resimdeki harfleri yazmak gerekir (captcha).
• Pull API son 7 günün oylarını döndürür.