Développeurs

Documentation développeur

Intègre Top-Server à ton serveur de jeu : récompense les voteurs via l'API, reçois les votes en temps réel par webhook, intègre des badges, et utilise le bot Discord.

API PULL PUSH Prêt à coller Widgets Bot Discord

API de vote

URL de base : https://top-server.net

Chaque serveur possède une clé d'API unique. Tu la trouves dans ton tableau de bord → ton serveur → Gérer → panneau API. La clé authentifie les endpoints PULL ; le secret de push (par serveur) signe les webhooks PUSH. Garde les deux secrets.

Deux modes d'intégration (combinables) : PULL (ton serveur nous interroge) et PUSH (on appelle ton webhook).

PULL

GET/api/v1/vote/check

Vérifie si un joueur a un vote en attente (non réclamé). La comparaison du pseudo est insensible à la casse.

curl

curl "https://top-server.net/api/v1/vote/check?key=VOTRE_CLE_API&player=Pseudo123"

200 OK — réponse

{
  "ok": true,
  "server": "Mon Serveur",
  "player": "Pseudo123",
  "hasPendingVote": true,
  "pending": 1,
  "votes": [{ "id": "ckv...", "votedAt": "2026-06-22T03:00:00.000Z" }]
}

POST/api/v1/vote/claim

Réclame (consomme) les votes en attente d'un joueur — appelle-le après avoir livré la récompense en jeu. Idempotent : un vote déjà réclamé n'est jamais recompté. Accepte JSON, form-urlencoded ou query string.

curl

curl -X POST "https://top-server.net/api/v1/vote/claim" \
  -H "Content-Type: application/json" \
  -d '{ "key": "VOTRE_CLE_API", "player": "Pseudo123" }'

200 OK — réponse

{ "ok": true, "claimed": 1 }

Erreurs : 400 (key/player manquant), 401 (clé d'API invalide).

PUSH (webhook)

Active le PUSH et renseigne ton URL de webhook dans le panneau API. À chaque nouveau vote, Top-Server envoie un POST signé à ton URL (timeout 8 s).

POST vers ton webhook — en-têtes + corps

x-topserver-event: vote
x-topserver-signature: sha256=<hmac_hex>
content-type: application/json

{
  "event": "vote",
  "serverId": "ckv...",
  "voteId": "ckv...",
  "player": "Pseudo123",
  "votedAt": "2026-06-22T03:00:00.000Z"
}

Vérifie la signature : calcule le HMAC-SHA256 du corps brut avec ton secret de push et compare-le à l'en-tête.

Node.js

import crypto from "node:crypto";

function verify(rawBody, header, pushSecret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", pushSecret).update(rawBody).digest("hex");
  // comparaison à temps constant
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Astuce : le PUSH te notifie en temps réel ; tu peux quand même utiliser PULL/claim comme source de vérité pour marquer les votes comme livrés.

Intégrations prêtes à coller

Tu n’as pas à écrire le code ci-dessus. Choisis ton jeu, colle le fichier, renseigne ta clé d’API.

Minecraft — Votifier / NuVotifier

Rien à installer : si ton serveur fait déjà tourner Votifier ou NuVotifier pour d’autres annuaires, on parle ce protocole. Ouvre Gérer → API & Widget → Votifier, renseigne l’adresse, le port (8192 par défaut) et ton token NuVotifier, puis clique sur « envoyer un vote de test ».

Le token se trouve dans plugins/NuVotifier/config.yml (tokens › default). L’ancien Votifier v1 est aussi géré : colle plutôt plugins/Votifier/rsa/public.key.

FiveM

Une resource prête à l’emploi qui interroge l’API PULL et récompense les voteurs (exemples ESX et QBCore inclus).

Télécharger server.lua

Rust (uMod / Oxide)

Dépose le fichier dans oxide/plugins/, renseigne ta clé d’API dans la config générée, recharge. uMod le compile tout seul.

Télécharger TopServerVotes.cs

Widgets intégrables

Badges SVG à intégrer partout (ton site, Discord). Pas d'authentification — utilise l'id de ton serveur (dans le panneau d'intégration de ton tableau de bord).

GET/api/widget/{serverId}?type=full

type = full · signature · votes · players · rank

À noter : si tu désactives « Afficher le nombre de joueurs » dans les réglages de ton serveur, les widgets players et signature affichent un tiret (—) à la place du compteur. La pastille en ligne / hors ligne, elle, reste visible.

HTML

<a href="https://top-server.net/server/votre-serveur">
  <img src="https://top-server.net/api/widget/SERVER_ID?type=full" alt="Top-Server" />
</a>

Bot Discord

Invite le bot Top-Server sur ta communauté pour afficher les classements directement dans Discord.

/vote

Renvoie le lien de vote (et un bouton) du serveur lié à ce Discord.

Features configurables (par serveur)

Rappels de vote : ping un salon (et un rôle optionnel) quand le cooldown de vote est écoulé.
Statut live : un message auto-actualisé avec le statut, les joueurs et la disponibilité 7 j.
Alertes hors-ligne quand le serveur tombe (et revient).
Annonces de progression : montées de rang dans la catégorie et paliers de votes du mois.
Alertes de nouvel avis dans un salon de ton choix.
Annonces de wipe / événement depuis ton calendrier (sous 24 h).
Synchro du rôle top-voteur (attribuer un rôle Discord à ton meilleur voteur du mois).
Annonce du gagnant de tombola dans un salon de ton choix.
Annonce quotidienne du classement dans un salon.
Top 10 voteurs en direct : un message auto-actualisé dans un salon (rafraîchi ~toutes les 10 min).

Active/désactive chaque feature (et l'interrupteur maître par serveur) dans ton tableau de bord → Gérer un serveur → panneau Bot Discord. Chaque feature nécessite l'ID de guilde/rôle/salon concerné.

Inviter le bot :

https://discord.com/api/oauth2/authorize?client_id=1518451791166177320&permissions=268437504&scope=bot%20applications.commands

Note : les commandes globales fraîchement enregistrées peuvent mettre jusqu'à ~1 h à apparaître dans Discord. La synchro du rôle top-voteur (attribuer un rôle Discord à ton meilleur voteur du mois) est prévue et nécessite la liaison des comptes Discord.