API Hytale-Servs

Intégrez les votes Hytale-Servs directement dans votre serveur de jeu : vérification des votes, claims de récompenses et gestion des tokens API.

Stablev1

1. Vue d’ensemble

L’API Hytale-Servs permet à votre serveur de jeu de :

vérifier qu’un joueur a voté récemment,
savoir s’il peut recevoir une récompense,
marquer le vote comme claimé pour éviter les doublons.

Le pseudo du joueur est optionnel : l’API repose principalement sur un identifiant technique (par exemple un UUID Hytale) transmis par votre plugin.

Le joueur tape /vote en jeu.

Votre plugin lui donne un lien Hytale-Servs avec un identifiant (externalId).

Le joueur vote sur Hytale-Servs. Le vote est enregistré.

Le joueur revient en jeu et tape /vote claim.

Votre plugin appelle l’API (vote-check puis vote-claim) et donne la récompense une seule fois.

2. Tokens API serveurs

Chaque serveur inscrit sur Hytale-Servs possède un token API utilisé pour authentifier les appels de votre plugin.

Vous pouvez le gérer depuis l’interface web, dans Mon compte > Mes serveurs :

Générer un token API (si aucun n’existe).
Régénérer un token en cas de fuite ou de rotation de clé.

Dans les URLs, le token est directement utilisé :

GET /api/v1/servers/vote-check?api_key=<clé>
POST /api/v1/servers/vote-claim?api_key=<clé>

3. Identification des joueurs

Deux modes sont disponibles, avec une priorité claire :

3.1. externalId (recommandé)

Identifiant technique stable (UUID Hytale, ID interne...).
Transmis au site via le paramètre de vote (ex. ?pid=XYZ).
Utilisé dans l’API via externalId.
Idéal pour éviter les homonymes et l’usurpation de pseudo.

3.2. player (fallback)

Pseudo saisi sur la page de vote ou connu du serveur.
Transmis dans l’API via player.
Moins fiable (homonymes), à réserver aux serveurs sans identifiant technique.

Lors du vote, Hytale-Servs enregistre notamment :

externalPlayerId : identifiant technique transmis par votre plugin ;
playerName : pseudo optionnel ;
ipHash et autres métadonnées anti-abus.

4. Vérifier un vote – `GET /vote-check`

Permet de savoir si un joueur a voté récemment et s’il peut encore recevoir une récompense.

GET https://hytale-servs.com/api/v1/servers/vote-check?api_key=<clé>&externalId=<id>
# Fallback (moins recommandé) :
GET https://hytale-servs.com/api/v1/servers/vote-check?api_key=<clé>&player=<pseudo>

Paramètres

externalId (string, optionnel mais prioritaire) : identifiant technique du joueur.
player (string, optionnel) : pseudo du joueur, utilisé uniquement si externalId n’est pas fourni.

Réponse de base

{
  "ok": true,
  "voted": true,
  "canClaim": true,
  "vote": {
    "id": 12345,
    "playerName": "Romain",
    "externalPlayerId": "XYZ-123",
    "votedAt": "2025-12-23T13:10:00.000Z"
  },
  "nextVoteAt": "2025-12-23T15:10:00.000Z"
}

ok : appel réussi.
voted : un vote récent existe pour ce joueur.
canClaim : la récompense peut encore être récupérée (vote non expiré, non claimé).
nextVoteAt : date à laquelle le joueur pourra revoter.

5. Valider une récompense – `POST /vote-claim`

Permet de marquer un vote comme claimé après avoir donné la récompense en jeu. Un même vote ne peut être claimé qu’une seule fois.

POST https://hytale-servs.com/api/v1/servers/vote-claim?api_key=<clé>
Content-Type: application/json

{
  "externalId": "XYZ-123"
}

# Fallback possible :

{
  "player": "Romain"
}

Champs du body

externalId (string, recommandé) : identifiant technique du joueur.
player (string, optionnel) : pseudo (utilisé seulement si externalId est absent).

Réponse en cas de succès

{
  "ok": true,
  "claimed": true,
  "voteId": 12345,
  "playerName": "Romain",
  "externalPlayerId": "XYZ-123",
  "claimedAt": "2025-12-23T13:12:30.000Z"
}

Réponse en cas d’échec

{
  "ok": false,
  "claimed": false,
  "reason": "NO_VOTE" | "ALREADY_CLAIMED" | "EXPIRED" | "UNAUTHORIZED"
}

6. Exemple de flow plugin

// 1) En jeu : commande /vote
showMessage(player, "Vote ici : https://hytale-servs.com/servers/<slug>?pid=" + externalId);

// 2) Le joueur vote sur Hytale-Servs (vote enregistré avec externalPlayerId = externalId).

// 3) En jeu : commande /vote claim
const resp = GET("https://hytale-servs.com/api/v1/servers/<token>/vote-check?externalId=" + externalId);

if (resp.ok && resp.canClaim) {
  // Donner la récompense
  giveReward(player);

  // Marquer le vote comme claimé
  POST("https://hytale-servs.com/api/v1/servers/<token>/vote-claim", {
    externalId: externalId
  });
} else {
  showMessage(player, "Aucun vote à récupérer pour le moment.");
}

7. Sécurité & bonnes pratiques

Ne partagez jamais votre token API publiquement.
Un token = un serveur. Régénérez-le en cas de fuite.
N’utilisez l’API qu’en HTTPS.
Implémentez un minimum de rate limiting / backoff dans votre plugin pour éviter le spam.
Utilisez externalId dès que possible pour éviter l’usurpation de pseudo.