Documentation de l'API

L'API permet à ton plugin, ton bot ou ton site de vérifier les votes de tes joueurs pour leur donner une récompense. Elle suit le format habituel des API de vote (claim-username, check-ip…) : si ton système de récompenses est déjà relié à un autre site, il suffit le plus souvent de changer l'adresse et le jeton.

Authentification

Ton jeton se trouve dans Mon espace → ton serveur → API & récompenses. Passe-le de l'une de ces deux façons :

https://classement-serveurs-ark-asa.fr/v1/votes/last?server_token=TON_JETON
Authorization: Bearer TON_JETON

Toutes les réponses sont en JSON. Limite : 120 requêtes par minute et par serveur. Un vote reste valable 2 h.

Réclamer un vote par pseudo

GET /v1/votes/claim-username?playername=Pseudo. C'est la route principale : elle marque le vote comme réclamé, une seule fois.

{
  "success": true,
  "claimed": 1,
  "message": "Vote found and claimed: give the reward to the player.",
  "vote": { "id": 42, "playername": "Dodo", "voted_at": 1791700000, "claimed": true, "claimed_at": 1791700100 }
}

Autres routes

En cas d'erreur : { "success": false, "error": "Unauthorized", "message": "…" } (messages en anglais) avec le code HTTP correspondant (400, 401, 404, 429).

Exemple en JavaScript (Node.js 18+)

const res = await fetch(`https://classement-serveurs-ark-asa.fr/v1/votes/claim-username?playername=${encodeURIComponent(pseudo)}`, {
  headers: { Authorization: `Bearer ${process.env.VOTE_TOKEN}` },
});
const data = await res.json();
if (data.claimed === 1) {
  // donne la récompense, par exemple : addpoints EOS_ID 80
}

Exemple en PHP

$url = 'https://classement-serveurs-ark-asa.fr/v1/votes/claim-username?server_token=' . TOKEN . '&playername=' . urlencode($pseudo);
$data = json_decode(file_get_contents($url), true);
if ($data['claimed'] === 1) {
    // donne la récompense
}

Webhook de vote

Si tu renseignes une URL de webhook, le site t'envoie un POST JSON à chaque vote :

{
  "event": "vote",
  "server": { "id": 1, "slug": "mon-serveur", "name": "Mon serveur" },
  "vote": { "id": 42, "playername": "Dodo", "voted_at": 1791700000 }
}

Ton serveur doit répondre avec un code 2xx en moins de 5 secondes. Sinon, le site réessaie jusqu'à 6 fois : après 1 min, 5 min, 15 min, 1 h et 3 h. Le bouton « Envoyer un test » envoie "event": "test".

Vérifie toujours la signature, pour qu'on ne puisse pas t'envoyer de faux votes. Deux en-têtes accompagnent chaque requête : X-Vote-Timestamp et X-Vote-Signature. La signature vaut sha256= suivi du HMAC-SHA256 de timestamp + "." + corps brut, calculé avec ton secret.

// Node.js / Express
const crypto = require('crypto');
app.post('/vote-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Vote-Timestamp');
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(ts + '.' + req.body).digest('hex');
  const sig = req.get('X-Vote-Signature') || '';
  const valid = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!valid || Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(401);
  const { event, vote } = JSON.parse(req.body);
  if (event === 'vote') { /* donne la récompense à vote.playername */ }
  res.sendStatus(200);
});

// PHP
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_VOTE_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, WEBHOOK_SECRET);
if (!hash_equals($expected, $_SERVER['HTTP_X_VOTE_SIGNATURE'] ?? '') || abs(time() - (int)$ts) > 300) {
    http_response_code(401); exit;
}
$data = json_decode($body, true);

Le même vote peut exceptionnellement arriver deux fois (si ta réponse s'est perdue) : utilise vote.id pour ne pas récompenser deux fois.