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 -H "Authorization: Bearer ta_clé" https://topspawn.com/api/v1/server/info
3Intègre dans ton plugin Minecraft, FiveM, ou tout autre serveur de jeu

Authentification

Toutes les requêtes doivent inclure ta clé API via le header Authorization :

Header Authorization

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

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 ton serveur dans les 2 dernières 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://www.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://www.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 ton serveur.

Exemple curl

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  "https://www.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 ton serveur.

Exemple curl

curl -H "Authorization: Bearer ts_live_VOTRE_CLE" \
  "https://www.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émarre ton 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