API de vote

Récompensez vos joueurs quand ils votent pour votre serveur. L'API vous indique qui a voté, et vous permet de marquer les votes comme récompensés pour ne jamais distribuer deux fois la même récompense.

Vous n'avez sans doute pas besoin de cette API. Si votre serveur dispose de Votifier : c'est le cas de la plupart des serveurs déjà référencés ailleurs, il suffit de coller un jeton pour que vos plugins de récompense fonctionnent, sans écrire une ligne de code. Voir la mise en place avec Votifier.

L'API reste utile si vous ne pouvez pas ouvrir de port, ou si vous voulez piloter les récompenses depuis votre propre code.

Authentification

Chaque serveur dispose d'une clé d'API unique, visible depuis la page de gestion du serveur. Transmettez-la dans l'en-tête Authorization ou dans le paramètre key.

Authorization: Bearer VOTRE_CLE_API

Ne publiez jamais cette clé côté client : elle donne accès aux votes de votre serveur.

GET/api/v1/vote

Vérifie si un joueur a un vote en attente de récompense. C'est l'appel à utiliser dans une commande /vote en jeu.

curl "https://cubevote.net/api/v1/vote?username=Steve" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse :

{
  "server": "nordcraft",
  "username": "Steve",
  "hasPendingVote": true,
  "pending": 1,
  "voteIds": ["clx8f2k1p0001"],
  "lastVoteAt": "2026-09-20T14:31:02.000Z"
}

Sans le paramètre username, l'appel renvoie jusqu'à 200 votes en attente, tous joueurs confondus.

POST/api/v1/vote/claim

Marque les votes comme récompensés. Appelez-le juste après avoir donné la récompense en jeu.

curl -X POST "https://cubevote.net/api/v1/vote/claim" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"username":"Steve"}'

Réponse :

{ "claimed": 1 }

Vous pouvez aussi cibler des votes précis avec {"voteIds": ["…"]}.

GET/api/v1/servers

Classement public, sans authentification. Pratique pour afficher le top des serveurs sur votre propre site.

curl "https://cubevote.net/api/v1/servers?mode=skyblock&version=1.21&tri=votes"

Paramètres : mode (survie, faction, skyblock…), version (1.21, 1.20…), bedrock=1, crack=1, q, tri (votes, players, rating, recent, name), page, limite (100 maximum).

Exemple d'intégration

Une boucle de vérification toutes les trente secondes, à adapter à votre plateforme (plugin Bukkit/Paper, script Node, extension Velocity…).

const KEY = process.env.CUBEVOTE_KEY;
const BASE = "https://cubevote.net/api/v1";

async function distribuerRecompenses() {
  const res = await fetch(`${BASE}/vote`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  const { votes } = await res.json();

  for (const vote of votes) {
    await donnerRecompenseEnJeu(vote.username); // votre logique
  }

  if (votes.length > 0) {
    await fetch(`${BASE}/vote/claim`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ voteIds: votes.map((v) => v.id) }),
    });
  }
}

setInterval(distribuerRecompenses, 30_000);

Limites et codes d'erreur

401, clé d'API absente ou invalide.
403, le serveur n'est pas encore validé par la modération.
429, plus de 120 requêtes par minute et par serveur.

Chaque vote porte un pseudo Minecraft, obligatoire pour voter : un même pseudo ne vote qu'une fois par délai, quelle que soit sa connexion.

Vous préférez ne rien coder ? Renseignez un webhook Discord dans la fiche de votre serveur : chaque vote y sera annoncé automatiquement.