API REST v1

Documentation API Développeurs

Intégrez vos serveurs de jeux (Minecraft, Rust, FiveM, ARK, Garry's Mod, 7 Days to Die, etc.) ou votre boutique en ligne à Serveurly pour vérifier les votes de vos joueurs et distribuer automatiquement leurs récompenses.

Authentification

Chaque serveur possède une clé API unique srv_live_... accessible dans l'espace de gestion.

Anti-double réclamation

Les réclamations sont verrouillées en base de données pour empêcher tout doublon de récompense.

Limite de requêtes

60 requêtes par minute par serveur pour assurer une haute disponibilité.

1. Authentification et base URL

URL de base de l'API

https://serveurly.com/api/v1

Où trouver votre clé API (Token serveur) ?

Rendez-vous dans votre espace Gestion des serveurs , sélectionnez votre serveur puis copiez votre token au format srv_live_....

Méthodes d'authentification supportées :

Recommandé
1. Header HTTP standard (Bearer Token)
Authorization: Bearer srv_live_votre_token_secret
2. Header HTTP personnalisé (X-Server-Token)
X-Server-Token: srv_live_votre_token_secret
Pratique pour tester
3. Paramètre d'URL (Query String)
https://serveurly.com/api/v1/server?token=srv_live_votre_token_secret

Sécurité : Ne divulguez jamais votre token d'API côté client (navigateur, JavaScript public ou HTML). Effectuez toujours vos requêtes depuis votre backend, vos plugins de jeux ou vos scripts serveurs privés.

2. Endpoints

GET
/api/v1/votes/check
POST
/api/v1/votes/claim
GET
/api/v1/server
GET
/api/v1/votes/top
GET
/api/v1/votes/recent

3. Webhook personnalisé de vote

Dans le formulaire de création ou de modification du serveur, renseignez l'URL de réception dans Webhook personnalisé. Serveurly envoie une requête POST JSON à chaque vote accepté. Un champ vide désactive cette notification.

json
{
  "id": "serveurly.vote.1234",
  "event": "vote.created",
  "created_at": "2026-11-05T12:30:00.000Z",
  "data": {
    "server": {
      "id": 42,
      "name": "Mon serveur",
      "slug": "mon-serveur",
      "game": { "id": 1, "name": "Minecraft", "slug": "minecraft" }
    },
    "vote": {
      "id": 1234,
      "username": "Joueur123",
      "voted_at": "2026-11-05T12:30:00.000Z"
    }
  }
}

En-têtes : Content-Type: application/json, X-Serveurly-Event: vote.created, X-Serveurly-Event-Id et X-Serveurly-Attempt. L'identifiant d'événement reste stable entre les tentatives : utilisez-le pour ignorer un éventuel doublon après un délai réseau.

Une réponse 2xx confirme la livraison. En cas de délai réseau, de réponse 408, 425, 429 ou 5xx, Serveurly effectue jusqu'à cinq tentatives au total (envoi initial compris), avec un délai croissant de 1, 5, 15 puis 60 minutes. Les réponses 3xx et les erreurs 4xx permanentes ne sont pas rejouées.

L'URL doit être une adresse publique HTTP ou HTTPS. Les adresses locales ou privées et les redirections sont refusées. Aucune adresse IP du votant n'est incluse dans le contenu.

4. Codes d'erreur et réponses HTTP

200 OK

Requête réussie

L'opération a été effectuée. Le champ success: true confirme le succès métier. En cas d'échec métier (ex: déjà réclamé), le code HTTP reste 200 avec success: false et un objet error.

400 Bad Request

Paramètres manquants

Code MISSING_IDENTIFIER : ni le pseudo (username) ni l'adresse IP n'ont été fournis.

401 Unauthorized

Authentification invalide

Code UNAUTHORIZED ou INVALID_TOKEN : clé API absente, non reconnue ou désactivée.

429 Rate Limit

Quota de requêtes dépassé

Limite de 60 requêtes par minute par serveur dépassée. Les en-têtes Retry-After indiquent le délai d'attente requis.

Prêt à intégrer l'API sur votre serveur ?

Récupérez votre clé API dans votre espace de gestion pour commencer à automatiser la distribution des récompenses de vote.

Accéder à mes serveurs