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égration Voir 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

Plugin vote FiveM + boutique FiveM (ox_lib) avec menu, commande, keymap et hooks serveur.

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.

Créer ou configurer ton serveur

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

Récupérer ton token

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

Installer le plugin

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

Tester le flux complet

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

Modules

Guides plugin

FiveM (vote)Boutique FiveM TrinityCore WOW

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',
  description = 'Ouvrir la boutique TopServeur'
}

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

Config.ShopCatalog = {
  {
    id = 'packs',
    label = { fr = 'Packs', en = 'Packs' },
    description = { fr = 'Packs de boosts et récompenses', en = 'Boost packs and rewards' },
    icon = 'package',
    items = {
      {
        id = 'pack_start',
        label = { fr = 'Pack de démarrage', en = 'Starter Pack' },
        description = { fr = 'Cash + véhicule', en = 'Cash + vehicle' },
        price = 9,
        icon = 'coins',
        rewards = {
          { type = 'command', command = 'give_money {player} 50000' },
        },
      },
    },
  },
}

Hook achat boutique

function Config.OnPurchase(source, item, category, quantity)
  -- Branche ici ESX, QBCore, ox_inventory, garage custom, etc.
  -- Exemple: print(('TopServeur Boutique: %s achète %sx%s'):format(source, quantity, item.id))
  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.

Validation via input dialog ox_lib.

Serveur

Hook Config.OnPurchase(source, item, category, quantity) pour récompenser.

Support commandes serveur avec {player}.

Notifications ox_lib, api de synchronisation et catalogue personnalisable.

Plugin TrinityCore WOW

Plugin dédié aux serveurs TrinityCore/WoW. Configure le token et la connexion API puis branche tes callbacks de récompense.

Configuration

-- Exemple de configuration TrinityCore
votePluginConfig = {
  serverToken = 'TOKEN',
  apiBaseUrl = 'https://topserveur.fr/api/public/v1',
  checkInterval = 60
}

Gestion du callback

-- Callback générique de vote (TrinityCore)
local vote = ...
if vote and vote.playerName then
  -- Ajoute ici ta logique de récompense (SQL, commandes, etc.)
end

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.