Documentation API - Serveur Hytale

1

Comprendre le principe (30 secondes)

Quand un joueur vote pour votre serveur sur Serveur Hytale, on enregistre son pseudo et la date du vote.

Votre plugin serveur peut ensuite nous demander :

💬

"Est-ce que le joueur Joueur123 a voté dans les dernières 24 heures ?"
Et on répond : OUI ou NON

Si la réponse est OUI → vous donnez une récompense au joueur ! 🎁

2

L'URL à appeler

Pour vérifier si un joueur a voté, votre plugin doit appeler cette URL :

https://serveur-hytale.gg/api/v1/votes/status?pseudo=NOM_DU_JOUEUR&server_id=VOTRE_ID

Remplacez :

NOM_DU_JOUEUR → le pseudo exact du joueur (ex: Joueur123)
VOTRE_ID → l'ID de votre serveur (visible dans votre dashboard)

💡

Où trouver votre ID de serveur ?
Allez dans votre Dashboard propriétaire, il est affiché dans la section "Clés API".

3

Tester maintenant ! 🧪

Essayez dans votre navigateur (remplacez les valeurs) :

https://serveur-hytale.gg/api/v1/votes/status?pseudo=MonPseudo&server_id=1

Vous allez recevoir une réponse comme celle-ci :

✅ Si le joueur a voté

{
  "success": true,
  "has_voted_24h": true
}

❌ Si le joueur n'a pas voté

{
  "success": true,
  "has_voted_24h": false
}

✨

C'est tout ! Votre plugin doit juste regarder si has_voted_24h est true ou false.

4

Exemples de code pour votre serveur

Voici comment intégrer la vérification dans différents langages :

📦 En Java (plugins Bukkit/Spigot/Paper)

// Quand un joueur tape /reward ou se connecte
String pseudo = player.getName();
int serverId = 1; // Votre ID de serveur

String url = "https://serveur-hytale.gg/api/v1/votes/status?pseudo=" + pseudo + "&server_id=" + serverId;

// Faire la requête HTTP (avec une librairie comme OkHttp)
String response = httpGet(url);
JSONObject json = new JSONObject(response);

if (json.getBoolean("has_voted_24h")) {
    // Donner la récompense !
    player.sendMessage("Merci d'avoir voté ! Voici 100 coins !");
    economy.depositPlayer(player, 100);
} else {
    player.sendMessage("Tu n'as pas encore voté aujourd'hui !");
    player.sendMessage("Vote ici : https://serveur-hytale.gg/voter/votre-serveur");
}

🐍 En Python

import requests

pseudo = "Joueur123"
server_id = 1  # Votre ID de serveur

response = requests.get(
    f"https://serveur-hytale.gg/api/v1/votes/status?pseudo={pseudo}&server_id={server_id}"
)
data = response.json()

if data["has_voted_24h"]:
    print("Le joueur a voté ! Donner récompense...")
else:
    print("Le joueur n'a pas voté")

🟢 En JavaScript/Node.js

const pseudo = "Joueur123";
const serverId = 1; // Votre ID de serveur

fetch(`https://serveur-hytale.gg/api/v1/votes/status?pseudo=${pseudo}&server_id=${serverId}`)
  .then(res => res.json())
  .then(data => {
    if (data.has_voted_24h) {
      console.log("Le joueur a voté !");
      // Donner récompense...
    } else {
      console.log("Pas de vote récent");
    }
  });

🐘 En PHP

$pseudo = "Joueur123";
$serverId = 1; // Votre ID de serveur

$url = "https://serveur-hytale.gg/api/v1/votes/status?pseudo=" . urlencode($pseudo) . "&server_id=" . $serverId;
$response = file_get_contents($url);
$data = json_decode($response, true);

if ($data['has_voted_24h']) {
    echo "Le joueur a voté !";
    // Donner récompense...
} else {
    echo "Pas de vote récent";
}

🏆

Afficher le classement des voteurs sur votre site

Vous voulez créer une page "Top Voteurs" sur votre site ? Utilisez cet endpoint :

https://serveur-hytale.gg/api/v1/votes/leaderboard?server_id=VOTRE_ID&period=month&limit=10

Paramètres

Paramètre	Obligatoire	Description
`server_id`	Oui	L'ID de votre serveur
`period`	Non	`day`, `week`, `month` (défaut), ou `all`
`limit`	Non	Nombre de résultats (1-100, défaut: 10)

Exemple de réponse

{
  "success": true,
  "server": {
    "id": 1,
    "name": "Mon Serveur",
    "slug": "mon-serveur"
  },
  "period": "month",
  "stats": {
    "total_votes": 150,
    "unique_voters": 42
  },
  "leaderboard": [
    { "rank": 1, "pseudo": "TopVoteur", "vote_count": 15, "last_vote": "2026-01-21 14:30:00" },
    { "rank": 2, "pseudo": "Joueur123", "vote_count": 12, "last_vote": "2026-01-20 18:45:00" },
    { "rank": 3, "pseudo": "VoteurFou", "vote_count": 10, "last_vote": "2026-01-21 09:15:00" }
  ]
}

💻 Exemple : Afficher le classement en HTML/JavaScript

<!-- HTML -->
<h2>🏆 Top Voteurs du Mois</h2>
<div id="leaderboard">Chargement...</div>

<!-- JavaScript -->
<script>
const serverId = 1; // Votre ID de serveur

fetch(`https://serveur-hytale.gg/api/v1/votes/leaderboard?server_id=${serverId}&limit=10`)
  .then(res => res.json())
  .then(data => {
    if (data.success) {
      let html = '<table><tr><th>#</th><th>Joueur</th><th>Votes</th></tr>';
      data.leaderboard.forEach(voter => {
        html += `<tr>
          <td>${voter.rank}</td>
          <td>${voter.pseudo}</td>
          <td>${voter.vote_count}</td>
        </tr>`;
      });
      html += '</table>';
      html += `<p>Total: ${data.stats.total_votes} votes de ${data.stats.unique_voters} joueurs</p>`;
      document.getElementById('leaderboard').innerHTML = html;
    }
  });
</script>

💡

Astuce : Mettez en cache le résultat pendant 5-10 minutes côté client pour éviter trop de requêtes.

🔧

Options avancées

📊 Méthode POST (plus de détails)

Si vous voulez plus d'infos (date exacte du vote, fenêtre personnalisée), utilisez POST :

POST https://serveur-hytale.gg/api/v1/votes/verify
Content-Type: application/json

{
  "pseudo": "Joueur123",
  "server_id": 1,
  "hours": 48  // Optionnel : vérifier les 48 dernières heures au lieu de 24
}

Réponse :

{
  "success": true,
  "has_voted": true,
  "vote_time": "2026-01-21 15:30:00"  // Date exacte du vote
}

🔑 Clés API (fonctions propriétaire)

Avec une clé API (générée dans votre dashboard), vous pouvez aussi :

Endpoint	Description
`GET /api/v1/me/server`	Voir toutes les infos de votre serveur
`GET /api/v1/me/stats`	Stats détaillées (votes jour/semaine/mois, classement)
`GET /api/v1/me/votes`	Historique des 100 derniers votes
`PATCH /api/v1/me/server`	Modifier description, liens, etc.

Comment utiliser la clé :

curl https://serveur-hytale.gg/api/v1/me/stats \
  -H "X-API-Key: sk_votre_cle_ici"

⚡ Limites

⏱️

100 requêtes par minute maximum par IP.
Si vous dépassez, attendez 60 secondes avant de réessayer.

❓

Questions fréquentes

Le pseudo doit-il être exactement le même ?

+

Oui et non. La comparaison ignore les majuscules/minuscules. "Joueur123" et "joueur123" sont considérés identiques.

Ai-je besoin d'une clé API pour vérifier les votes ?

+

Non ! La vérification de vote (/votes/status et /votes/verify) est publique et ne nécessite pas de clé.

Comment récupérer mon ID de serveur ?

+

Dans votre Dashboard propriétaire, section "Clés API". Vous pouvez aussi le voir dans l'URL de votre page serveur.

Le joueur peut-il tricher en votant plusieurs fois ?

+

Non, notre système anti-triche bloque les votes multiples (même IP, même pseudo, VPN/proxy détectés).

Comment tester sans avoir voté ?

+

Votez une fois pour votre propre serveur avec un pseudo test, puis utilisez ce pseudo pour tester l'API.

J'ai une erreur, que faire ?

+

Vérifiez que l'ID serveur est correct et que le pseudo ne contient pas de caractères spéciaux. Si le problème persiste, contactez-nous.

Quelle est la limite de requêtes API ?

+

100 requêtes par minute par IP. Si vous dépassez cette limite, attendez 60 secondes. Pour la plupart des usages (vérification de vote quand un joueur se connecte), c'est largement suffisant.

Les données sont-elles en temps réel ?

+

Oui ! Dès qu'un joueur vote, l'information est immédiatement disponible via l'API. Aucun délai de synchronisation.

🎮 Récompensez vos joueurs qui votent

📑 Dans ce guide