Développeurs

API de vote

Récompensez automatiquement les joueurs qui votent pour votre serveur : votre plugin vérifie le vote sur Rank-Serv et le marque comme réclamé.

Démarrage

Le fonctionnement se fait en trois étapes :

Récupérez le token de vote de votre serveur dans votre espace propriétaire.
Le joueur vote sur Rank-Serv en indiquant son pseudo en jeu.
Quand il tape une commande en jeu (par exemple /vote), votre plugin appelle /claim et donne la récompense si la réponse est CLAIMED.

Authentification

Chaque requête doit contenir le token de votre serveur dans l'en-tête HTTP suivant. Les plugins qui ne peuvent pas envoyer d'en-tête peuvent utiliser le paramètre ?token= à la place.

X-Server-Token: VOTRE_TOKEN

Vous trouverez le token dans la page d'édition de votre serveur, depuis Mes serveurs.

Gardez ce token secret : il permet de réclamer les votes de votre serveur. En cas de fuite, régénérez-le depuis la page d'édition. L'ancien token cesse aussitôt de fonctionner.

Vérifier un vote

GEThttps://api.rank-serv.com/v1/votes/check

Indique si le joueur a voté dans les 2 dernières heures et si sa récompense a déjà été réclamée. Cet appel ne modifie rien.

Paramètre	Obligatoire	Description
token	Oui	Token du serveur, dans l'en-tête X-Server-Token ou en paramètre ?token=.
username	Un des deux	Pseudo saisi par le joueur lors du vote (insensible à la casse).
ip	Un des deux	Adresse IP du joueur au moment du vote. N'envoyez pas username et ip ensemble.

curl -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/check?username=Steve"

{
  "status": "CLAIMABLE",
  "voted_at": "2026-11-05T14:02:11",
  "next_vote_in": 4320
}

Réclamer un vote

POSThttps://api.rank-serv.com/v1/votes/claim

Marque le dernier vote du joueur comme réclamé. Un vote ne peut être réclamé qu'une seule fois, même si deux requêtes arrivent en même temps : donnez la récompense uniquement quand le statut vaut CLAIMED.

Les paramètres sont les mêmes que pour /check.

curl -X POST -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/claim?username=Steve"

{
  "status": "CLAIMED",
  "voted_at": "2026-11-05T14:02:11",
  "next_vote_in": 4318
}

Réponses

Les deux routes renvoient toujours un code HTTP 200 avec ce format JSON, que le vote existe ou non.

Champs

status: Résultat de la requête (voir ci-dessous).
voted_at: Date et heure du vote, ou null si aucun vote n'a été trouvé.
next_vote_in: Nombre de secondes avant que le joueur puisse voter à nouveau, ou null.

Valeurs de status

NOT_FOUND: Aucun vote de ce joueur dans les 2 dernières heures.
CLAIMABLE: /check uniquement : le joueur a voté et sa récompense n'a pas encore été réclamée.
CLAIMED: /claim uniquement : le vote vient d'être réclamé, donnez la récompense.
ALREADY_CLAIMED: Le vote a déjà été réclamé, ne donnez pas la récompense une seconde fois.

{
  "status": "NOT_FOUND",
  "voted_at": null,
  "next_vote_in": null
}

Erreurs

Un code HTTP différent de 200 signale une requête invalide :

400: Paramètre manquant : envoyez username ou ip, mais pas les deux.
401: Token manquant.
404: Token invalide : aucun serveur ne correspond.

Exemples

Exemples complets pour réclamer un vote.

curl -X POST -H "X-Server-Token: VOTRE_TOKEN" \
  "https://api.rank-serv.com/v1/votes/claim?ip=203.0.113.42"

Bonnes pratiques

Préférez la recherche par pseudo : l'IP du navigateur au moment du vote peut différer de celle vue par votre serveur de jeu (IPv6/IPv4, mobile, VPN).
Appelez directement /claim quand le joueur tape la commande. Il n'est pas nécessaire d'appeler /check avant.
N'interrogez pas l'API en boucle pour tous les joueurs connectés : appelez-la seulement à la demande du joueur.
Faites les appels de manière asynchrone pour ne jamais bloquer votre serveur.
Utilisez de préférence l'en-tête X-Server-Token : un token passé dans l'URL peut finir dans des logs.