API Documentation

API publique TOPSPAWN v1

L'API TOPSPAWN permet aux propriétaires de serveurs de vérifier les votes et récompenser les joueurs automatiquement via des plugins sur leurs serveurs de jeu.

Démarrage rapide

1Génère ta clé API dans le Dashboard → Intégrations
2Teste avec curl : curl "https://topspawn.com/api/v1/server/info?key=ta_clé"
3Intègre dans ton plugin Minecraft, FiveM, ou tout autre serveur de jeu

Authentification

Toutes les requêtes doivent inclure ta clé API. Deux méthodes sont supportées :

Header Authorization (recommandé)

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  https://topspawn.com/api/v1/server/info

Query parameter

curl "https://topspawn.com/api/v1/server/info?key=ts_live_VOTRE_CLE"

Rate limit : 60 requêtes par minute par clé API. En cas de dépassement, l'API retourne un code 429.

Endpoints

GET/api/v1/vote/check

Vérifie si un joueur a voté pour votre serveur dans les dernières 24 heures.

Paramètres

Nom	Type	Requis	Description
`username`	string	oui	Le pseudo en jeu du joueur
`ip`	string	non	L'adresse IP du joueur (alternative à username)

Exemple curl

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  "https://topspawn.com/api/v1/vote/check?username=Steve"

Réponse

{
  "voted": true,
  "voted_at": "2026-03-21T14:30:00.000Z",
  "username": "Steve"
}

POST/api/v1/vote/claim

Marque un vote comme réclamé (récompense distribuée). Permet d'éviter de récompenser deux fois le même vote.

Paramètres

Nom	Type	Requis	Description
`username`	string	oui	Le pseudo du joueur (dans le body JSON)

Exemple curl

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

Réponse

{
  "success": true,
  "vote_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

GET/api/v1/vote/count

Récupère les statistiques de votes de votre serveur.

Exemple curl

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  "https://topspawn.com/api/v1/vote/count"

Réponse

{
  "votes_total": 1234,
  "votes_24h": 42,
  "votes_7d": 287,
  "votes_monthly": 890,
  "server_name": "Mon Serveur",
  "server_game": "minecraft"
}

GET/api/v1/server/info

Récupère les informations publiques de votre serveur.

Exemple curl

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  "https://topspawn.com/api/v1/server/info"

Réponse

{
  "name": "Mon Serveur",
  "game": "minecraft",
  "ip": "play.monserveur.fr",
  "port": 25565,
  "description": "Un super serveur survie !",
  "is_premium": false,
  "is_verified": true,
  "votes_total": 1234,
  "followers_count": 56,
  "rank": 12
}

Codes d'erreur

Code	Description
`200`	Succès
`400`	Paramètre manquant ou invalide
`401`	Clé API manquante ou invalide
`404`	Ressource non trouvée (ex: aucun vote non-réclamé)
`429`	Rate limit dépassé (60 req/min)
`500`	Erreur interne du serveur

Plugin FiveM

Plugin Lua prêt à l'emploi pour récompenser automatiquement vos joueurs FiveM quand ils votent. Compatible ESX, QBCore, QBox et standalone.

Installation rapide

1.Téléchargez le dossier topspawn-votes et placez-le dans resources/
2.Ajoutez ensure topspawn-votes dans server.cfg
3.Ouvrez config.lua et collez votre clé API
4.Configurez le type de récompense (money, bank, item, custom)
5.Redémarrez votre serveur

Télécharger le plugin

Prêt à intégrer ?

Génère ta clé API et commence à récompenser tes joueurs en quelques minutes.

Générer ma clé API