API de récompenses de vote

Lien de vote

Envoyez les joueurs vers ce lien, avec leur nom en jeu dans userid :

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

Vous venez d'une autre toplist ? Inutile de changer votre paramètre. Nous lisons aussi username, player_id, pingUsername, custom, postback, incentive et id. Les noms peuvent contenir des lettres, des chiffres, - et _, jusqu'à 32 caractères.

Callback (postback)

Définissez une URL de callback dans votre tableau de bord. Après chaque vote comportant un nom de joueur, nous envoyons une requête GET à cette URL avec ces champs ajoutés à la query string :

Chaque requête porte un en-tête X-Signature: sha256=… : un HMAC-SHA256 des champs de vote ci-dessus (dans cet ordre, encodés en URL) calculé avec votre secret de callback. Vérifiez-le, pour que personne ne puisse simuler des votes en appelant votre URL. Nous réessayons jusqu'à 3 fois si votre serveur ne répond pas avec un statut 2xx. Si votre URL contient {userid}, nous le remplaçons par le nom du joueur, pour les scripts qui attendent le nom dans le chemin.

Exemple de handler en 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';

Utilisez Envoyer un vote de test dans le tableau de bord pour envoyer un callback pour le joueur TEST et voir la réponse de votre serveur.

Vérification Vote4Buff

Chaque vote donne au joueur un buff qui dure 7 jours, jusqu'à ce qu'il puisse revoter. Demandez si le buff d'un joueur est actif quand il se connecte ou ouvre le PNJ de 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"}

Jusqu'à 600 requêtes par minute et par serveur. Les votes signalés comme frauduleux par les modérateurs ne donnent plus de buff.

API pull

Vous préférez interroger plutôt qu'être appelé ? Envoyez votre clé API dans l'en-tête X-API-Key.

Ce joueur a-t-il voté ?

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

Votes pas encore récompensés

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

Marquer des votes comme récompensés

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

{"vote_ids":[1234,1235]}

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

Lancez unclaimed puis claim chaque minute depuis une tâche cron pour distribuer les récompenses exactement une fois.

Limites

• Un vote par joueur tous les 7 jours et par serveur, vérifié par IP et par nom de joueur.
• Chaque vote demande de recopier les lettres d'une image (captcha).
• L'API pull renvoie les votes des 7 derniers jours.