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 un vote pour ton serveur qui n'a pas encore été récompensé (pas encore réclamé via /vote/claim), quelle que soit sa date.

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

Plugins & Intégrations

ESX, QBCore, QBox

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

1.Télécharge le dossier topspawn-votes et place-le dans resources/
2.Ajoute ensure topspawn-votes dans server.cfg
3.Ouvre config.lua et colle ta clé API
4.Configure le type de récompense (money, bank, item, custom)
5.Redémarre ton serveur

Télécharger le plugin

Badge de vote

Une image à intégrer sur ton site, ton forum ou ton Discord : rang, votes et joueurs de ton serveur, mis à jour toutes les 5 minutes, avec un lien vers ta page de vote. Aucune clé API nécessaire.

https://www.topspawn.com/badge/<server-id>.png?style=button|stats|mini&theme=light|dark&lang=fr|en

Choisis le format et copie le code HTML, Markdown, BBCode ou Discord depuis Dashboard › Intégrations

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