API Rankora — Intégration dans votre site

Guide express (3 étapes)

Récupérez votre server_token dans votre dashboard Rankora.
Depuis votre backend (PHP, Node, Python…), appelez GET https://rankium.net/api/v1/servers/{server_token}/votes/{user_ip}.
Interprétez la réponse :
- si next_vote_seconds > 0 ⇒ le joueur a voté récemment (cooldown encore actif),
- si next_vote_seconds = 0 ⇒ il peut voter maintenant.

Important : faites l’appel côté serveur (ne pas exposer votre token au navigateur).

1) Vérifier un vote (90 min)

GET /servers/{server_token}/votes/{user_ip}

user_ip : IP publique du joueur. Si vous utilisez Cloudflare, prenez HTTP_CF_CONNECTING_IP, sinon REMOTE_ADDR.
La fenêtre de vérification est de 90 minutes.

Réponse (succès)

{
  "success": true,
  "data": {
    "username": "Trevor",
    "voted_at": 1730282400,
    "next_vote_seconds": 3120,
    "is_connected": true,
    "is_subscriber": false
  }
}

Déjà voté next_vote_seconds > 0 → cooldown encore actif.

Libre next_vote_seconds = 0 → il peut voter maintenant.

2) Statistiques

GET /servers/{server_token}/statistics

Exemple de réponse

{
  "success": true,
  "data": {
    "position": 7,
    "votes_count": 1520,
    "clicks_count": 842,
    "comments_count": 12,
    "rating": 4.6
  }
}

3) Donateurs

GET /servers/{server_token}/donors

Exemple de réponse

{
  "success": true,
  "data": [
    {
      "username": "Alice",
      "avatar": "https://.../alice.png",
      "amount": 5.00,
      "currency": "EUR",
      "message": "Thanks!",
      "created_at": 1730282400
    }
  ]
}

4) Abonnés

GET /servers/{server_token}/subscribers

Exemple de réponse

{
  "success": true,
  "data": [
    {
      "username": "Bob",
      "avatar": "https://.../bob.png",
      "started_at": 1728000000,
      "ended_at": null
    }
  ]
}

5) Top voteurs (mois courant)

GET /servers/{server_token}/voters

Exemple de réponse

{
  "success": true,
  "data": [
    {
      "username": "Trevor",
      "position": 1,
      "votes": 18,
      "avatar": null,
      "subscribed": false,
      "public_profile": null
    }
  ]
}

Exemples d’intégration (copiez/collez)

PHP (vanilla)

PHP

<?php
$token = 'VOTRE_TOKEN_RANKORA';
$ip = $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $_SERVER['REMOTE_ADDR']; // IP réelle
$url = "https://rankium.net/api/v1/servers/$token/votes/$ip";

$resp = @file_get_contents($url);
if ($resp === false) {
  http_response_code(502);
  exit('Erreur de connexion à l’API.');
}
$js = json_decode($resp);
if (!$js || empty($js->success)) {
  http_response_code(502);
  exit('Réponse API invalide.');
}

// Exemple d’usage :
if ($js->data->next_vote_seconds > 0) {
  // ✅ Le joueur a voté récemment → accordez la récompense
  // $js->data->username, $js->data->voted_at…
  echo "Merci, vote confirmé !";
} else {
  // ❌ Pas de vote récent → invitez à voter
  echo "Tu peux voter maintenant.";
}

WordPress (functions.php / plugin)

WordPress

add_action('rest_api_init', function(){
  register_rest_route('rankora/v1', '/check-vote', [
    'methods' => 'GET',
    'callback' => function(WP_REST_Request $req){
      $token = 'VOTRE_TOKEN_RANKORA';
      $ip = $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $_SERVER['REMOTE_ADDR'];
      $url = 'https://rankium.net/api/v1' . "/servers/$token/votes/$ip";
      $r = wp_remote_get($url, ['timeout' => 5]);
      if (is_wp_error($r)) return new WP_Error('api_error','API injoignable', ['status' => 502]);
      $body = wp_remote_retrieve_body($r);
      $js = json_decode($body, true);
      return rest_ensure_response($js ?: ['success' => false]);
    }
  ]);
});

Node / Express

Node

app.get('/api/check-vote', async (req, res) => {
  const ip = req.headers['cf-connecting-ip'] || req.ip;
  const token = process.env.RANKORA_TOKEN; // stockez le token en variable d’environnement
  const url = 'https://rankium.net/api/v1' + '/servers/' + token + '/votes/' + ip;
  const r = await fetch(url, { timeout: 5000 });
  const js = await r.json();
  res.json(js);
});

Python / Flask

Flask

import requests
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.get('/check-vote')
def check_vote():
  ip = request.headers.get('CF-Connecting-IP') or request.remote_addr
  token = 'VOTRE_TOKEN_RANKORA'
  url = 'https://rankium.net/api/v1' + f'/servers/{token}/votes/{ip}'
  r = requests.get(url, timeout=5)
  return jsonify(r.json())

Astuce : testez en live avec l’outil Vérifier un vote (UI) ou ajoutez ?format=json pour la réponse brute.

Bonnes pratiques

N’exposez jamais votre token côté navigateur. Faites un endpoint proxy côté serveur.
IP réelle : Cloudflare ⇒ CF-Connecting-IP, sinon REMOTE_ADDR.
Timeout & retry : 3–6 s de timeout, un retry max.
Caching léger : 20–60s suffisent pour soulager votre site.
UX : si next_vote_seconds > 0, affichez un compte à rebours.

Erreurs fréquentes

400 Paramètre invalide (IP vide/mal formée).
404 Mauvais server_token.
500 Erreur côté Rankora (rare). Réessayez après quelques secondes.
502 local Votre serveur n’a pas pu joindre l’API (firewall DNS/SSL, timeout).

cURL debug

curl -i "https://rankium.net/api/v1/servers/VOTRE_TOKEN/votes/1.2.3.4"

FAQ

Q: On est derrière Cloudflare/Reverse Proxy, l’IP n’est pas la bonne.
R: Utilisez CF-Connecting-IP (CF) ou configurez correctement les headers de votre proxy.

Q: Un joueur dit avoir voté mais on récupère next_vote_seconds = 0.
R: Son dernier vote a plus de 90 min, ou l’IP est différente (VPN, 4G, box partagée). Demandez-lui son IP publique puis testez dans l’outil Vérifier un vote.

Q: Pouvons-nous appeler l’API depuis le navigateur ?
R: Déconseillé (le token serait exposé). Passez toujours par votre backend.