Top Serveur

Documentation développeur

API, votes, plugin FiveM et webhooks Discord

Tout ce qu’il faut pour connecter un serveur à TopServeur : vérifier les votes, distribuer les récompenses, suivre le statut serveur et automatiser les notifications Discord.

Commencer l’intégrationVoir les endpoints

Base API

Version stable v1

https://topserveur.fr/api/public/v1

Token requis
JSON stable
Rate limit
Webhooks

Votes & cooldown

Contrôle les votes par pseudo, Steam ID, Discord ID ou identifiant personnalisé avec cooldown serveur.

Plugin FiveM

Resource vote et boutique FiveM avec menu client, commande, keymap, config Lua et locales FR/EN.

Webhooks Discord

Notifications de vote, test webhook et aperçu Discord pour valider le rendu avant production.

Monitoring

Statut online/offline, joueurs, slots, latence et historiques exploitables côté dashboard.

Quick start

Brancher un serveur

Le flux recommandé est simple : token privé, plugin côté serveur, check de vote, puis claim de récompense.

1

Créer ou configurer ton serveur

Ajoute ton serveur depuis le dashboard, renseigne le jeu, les bannières, le Discord et les tags.

2

Récupérer ton token

Dans l’onglet API de ton serveur, copie le server_token. Il doit rester côté serveur/plugin.

3

Installer le plugin

Installe le resource FiveM, ajoute le token dans ton server.cfg et démarre le script.

4

Tester le flux complet

Vote depuis la page publique, vérifie l’API, puis consomme la récompense avec une route claim.

Plugin de vote FiveM

Le plugin interroge l’API TopServeur, détecte les nouveaux votes et déclenche un event Lua pour récompenser les joueurs.

server.cfg

ensure topserveur_vote
set topserveur_token "TOKEN"
set topserveur_api_url "https://topserveur.fr/api/public/v1"
set topserveur_check_interval 60

Event reward Lua

AddEventHandler('onPlayerVote', function(playername, date)
  print(('[TopServeur] %s a voté le %s'):format(playername, date))

  -- Exemple :
  -- giveMoney(playername, 5000)
  -- giveItem(playername, 'premium_case', 1)
end)

Documentation boutique

Repository officiel : https://github.com/DARKAOFF/topserveur-fivem-boutique

server.cfg boutique

ensure topserveur_boutique

# Configuration principale dans resources/topserveur_boutique/config.lua

config.lua boutique

Config.Locale = 'fr'
Config.Command = 'boutique'
Config.KeyMapping = {
  enabled = true,
  key = 'F7'
}

Config.Api = {
  enabled = true,
  baseUrl = 'https://topserveur.fr/api/public/v1',
  serverToken = 'TOKEN',
  checkVoteBeforePurchase = false
}

Config.Categories = {
  { id = 'packs', label = 'Packs' },
  { id = 'vehicles', label = 'Véhicules' }
}

Hook achat boutique

function Config.OnPurchase(source, item, category)
  -- Branche ici ESX, QBCore, ox_inventory, garage custom, etc.
  for _, reward in ipairs(item.rewards or {}) do
    if reward.type == 'command' and reward.command then
      ExecuteCommand(reward.command:gsub('{player}', tostring(source)))
    end
  end
end

Client

Commande /boutique configurable.
Keymap F7 activable ou désactivable.
Menu catégories/articles côté joueur.

Serveur

Hook Config.OnPurchase pour récompenser.
Support commandes serveur avec {player}.
Locales fr.lua et en.lua incluses.

Référence API

Endpoints publics v1

Tous les endpoints nécessitent un token serveur. Le token peut être passé en query `server_token=TOKEN` ou dans l’URL pour les routes serveur.

GET

Derniers votes

Retourne les derniers votes disponibles pour ton serveur.

https://topserveur.fr/api/public/v1/votes/last?server_token=TOKEN

Réponse exemple

{
  "code": 200,
  "success": true,
  "data": [
    {
      "playerIdentifier": "username:Anthony",
      "playerName": "Anthony",
      "datetime": "2026-04-29T12:00:00.000Z"
    }
  ]
}
GET

Vérifier un vote

Indique si un joueur a déjà voté et quand il pourra voter à nouveau.

https://topserveur.fr/api/public/v1/votes/check?server_token=TOKEN&playername=PSEUDO

Réponse exemple

{
  "code": 200,
  "success": true,
  "data": {
    "voted": true,
    "lastVoteAt": "2026-04-29T12:00:00.000Z",
    "nextVoteAt": "2026-04-30T12:00:00.000Z"
  }
}
GET

Réclamer une récompense

Consomme un vote validé pour éviter de donner deux fois la même récompense.

https://topserveur.fr/api/public/v1/votes/claim-username?server_token=TOKEN&playername=PSEUDO

Réponse exemple

{
  "code": 200,
  "success": true,
  "message": "Vote reward claimed.",
  "data": {
    "claimed": true,
    "playerName": "Anthony"
  }
}
GET

Statut serveur

Retourne l’état du serveur, les joueurs connectés et la latence.

https://topserveur.fr/api/public/v1/servers/TOKEN/status

Réponse exemple

{
  "code": 200,
  "success": true,
  "data": {
    "online": true,
    "playersOnline": 54,
    "maxPlayers": 300,
    "latency": 42
  }
}
GET

Classement joueurs

Liste les joueurs qui votent le plus pour ton serveur.

https://topserveur.fr/api/public/v1/servers/TOKEN/players-ranking

Réponse exemple

{
  "code": 200,
  "success": true,
  "data": {
    "players": [
      {
        "playerName": "Anthony",
        "votes": 42,
        "position": 1
      }
    ]
  }
}

Sécurité

Ne mets jamais ton token dans un script frontend.
Régénère le token si un plugin ou un dépôt public l’a exposé.
Les votes gardent une protection IP et cooldown côté serveur.

Discord

Crée un webhook dans le salon Discord ciblé.
Colle l’URL dans l’onglet Webhooks du serveur.
Utilise le test intégré avant d’ouvrir les votes.

Bonnes pratiques

Utilise les routes claim pour les récompenses.
Log les erreurs côté plugin pour diagnostiquer rapidement.
Conserve un fallback si Discord ou l’API est temporairement indisponible.