API et Votifier pour les serveurs

Trois façons de savoir qu’un joueur a voté (et une API de statistiques en bonus), à combiner selon ton serveur. Toutes sont gratuites. Configure-les dans Mes serveurs → ton serveur.

1. Votifier (instantané)

À chaque vote, le site contacte ton serveur et lui transmet le pseudo. Ton plugin de récompenses (VotingPlugin, SuperbVote, NuVotifier + commandes…) donne la récompense tout de suite.

Installe NuVotifier sur ton serveur, ou sur ton proxy BungeeCord / Velocity.
Ouvre le port Votifier (8192 par défaut) dans le pare-feu de ton hébergeur.
Protocole v2 (recommandé) : copie le jeton de plugins/nuvotifier/config.yml (section tokens). Pour un jeton dédié au site, ajoute une ligne MCVoteStats: ton-jeton.
Protocole v1 : copie le contenu de plugins/Votifier/rsa/public.key.
Clique sur « Tester » : un vote d’essai part vers ton serveur et le résultat s’affiche.

Nom du service envoyé avec chaque vote : MCVoteStats. Si ton serveur ne répond pas, le site réessaie 7 fois sur environ 9 heures ; l’onglet Livraisons montre chaque tentative.

2. API de vérification (sans port à ouvrir)

Ton plugin ou ton site demande au nôtre si un joueur a voté. Crée ta clé d’API dans l’onglet « API et webhooks ». La clé se passe en paramètre key, ou en en-tête X-Api-Key ou Authorization: Bearer. Limite : 600 requêtes par minute.

Vérifier un vote

GET https://mcvotestats.com/api/v1/votes/check?key=TA_CLE&pseudo=Steve
GET https://mcvotestats.com/api/v1/votes/check?key=TA_CLE&ip=203.0.113.7
GET https://mcvotestats.com/api/v1/votes/check?key=TA_CLE&pseudo=Steve&format=text   → 1 ou 0

{
  "ok": true,
  "hasVoted": true,
  "pseudo": "Steve",
  "votedAt": "2026-10-09T12:00:00.000Z",
  "nextVoteAt": "2026-10-09T14:00:00.000Z",
  "claimed": false,
  "window": 120
}

La recherche porte sur les 120 dernières minutes (le délai de vote). Paramètre window (ou duration) pour la changer, de 1 à 1 440 minutes. La vérification par IP reconnaît le joueur qu’il sorte en IPv4 ou en IPv6.

Réclamer la récompense

Pour ne donner qu’une récompense par vote, marque le vote comme réclamé :

POST https://mcvotestats.com/api/v1/votes/claim?key=TA_CLE&pseudo=Steve
→ { "ok": true, "claimed": true, "vote": { "id": "1234", "pseudo": "Steve", "votedAt": "…" } }
→ { "ok": true, "claimed": false, "reason": "ALREADY_CLAIMED" }   (déjà donnée)
→ { "ok": true, "claimed": false, "reason": "NO_VOTE" }           (pas de vote récent)

Lister les votes

GET https://mcvotestats.com/api/v1/votes?key=TA_CLE&since=2026-10-09T12:00:00Z&limit=100

Votes reçus depuis une date (7 jours au plus), du plus ancien au plus récent. Pour continuer, rappelle avec since = la valeur de next.

Statistiques du serveur

GET https://mcvotestats.com/api/v1/server?key=TA_CLE          (rang, votes du mois, meilleurs votants)
GET https://mcvotestats.com/api/v1/servers/{slug}              (public, sans clé)

Exemple en Java (Paper)

HttpClient http = HttpClient.newHttpClient();
URI uri = URI.create("https://mcvotestats.com/api/v1/votes/claim?key=" + KEY + "&pseudo=" + player.getName());
http.sendAsync(HttpRequest.newBuilder(uri).POST(HttpRequest.BodyPublishers.noBody()).build(),
               HttpResponse.BodyHandlers.ofString())
    .thenAccept(res -> {
        if (res.body().contains("\"claimed\":true")) {
            // Revenir sur le thread du joueur (Folia : player.getScheduler()) avant de donner la récompense
            player.getScheduler().run(plugin, t -> giveReward(player), null);
        }
    });

3. Webhook HTTP

À chaque vote, le site envoie une requête POST JSON à l’adresse de ton choix :

{
  "event": "vote",
  "server": { "id": "…", "slug": "mon-serveur", "name": "Mon serveur" },
  "vote": { "id": "1234", "pseudo": "Steve", "createdAt": "2026-10-09T12:00:00.000Z" },
  "monthlyVotes": 542
}

Vérifie la signature : en-tête X-TSM-Signature: sha256=… = HMAC-SHA256 du secret sur X-TSM-Timestamp + "." + corps brut. Refuse les requêtes dont l’horodatage a plus de 5 minutes.

// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.headers['x-tsm-timestamp'] + '.' + rawBody).digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-tsm-signature']))) return res.status(401).end()

4. Statistiques publiques (sans clé)

Le nombre de joueurs de chaque serveur suivi est mesuré toutes les 5 minutes. L’historique est public : pas de clé, 120 requêtes par minute et par adresse IP.

GET https://mcvotestats.com/api/v1/servers/{slug}/history?range=24h|7d|30d|90d|1y|all
GET https://mcvotestats.com/api/v1/servers/{slug}/history?range=30d&format=csv
GET https://mcvotestats.com/api/v1/stats/global?range=7d&mode=skyblock&edition=java

{
  "ok": true,
  "range": "7d",
  "step": "1 h",
  "summary": { "avg": 244, "median": 226, "min": 76, "peak": 553, "uptime": 0.998, "points": 2016 },
  "points": [ { "t": "2026-10-09T12:00:00.000Z", "avg": 236.5, "max": 251 }, … ]
}

avg est la moyenne de joueurs sur la tranche, max le pic. Les horodatages sont en UTC. Voir les statistiques.

Lien de vote et badge

Donne à tes joueurs le lien https://mcvotestats.com/serveur/ton-serveur/voter?pseudo=%player% : le pseudo est déjà rempli. Le badge « Votez pour nous » (onglet API et webhooks) affiche ton rang en direct sur ton site.

Récompenser les votes de tes joueurs