Connecter tes outils aux membres de ton serveur (API Membres)

« Tu boostes le Discord ? Alors tu as le grade VIP en jeu… mais qui le donne, à la main, à chaque fois ? » Avec l'API Membres, ton plugin Minecraft ou FiveM, ton script ou le site de ta communauté lisent eux-mêmes les informations de tes membres : rôles, boost, tag de serveur, niveau, invitations… Et avec les webhooks, c'est Hurix qui prévient ton outil dès qu'un membre arrive, booste ou change de rôle.

1. Comprendre le principe

• Tu crées une clé d'accès depuis le dashboard. Ton outil l'envoie à chaque appel : sans clé, l'API ne répond rien.
• Une clé est liée à ton serveur : elle ne donne accès qu'à ses membres, jamais à ceux d'un autre serveur.
• L'API est en lecture seule : elle ne peut rien modifier, ni sur Discord ni dans Hurix. Elle ne sert qu'à lire.
• Elle lit les membres un par un (ou par petits groupes de 100 au plus) : il n'existe pas de liste complète des membres. Seuls les classements (niveaux, invitations, économie) se lisent en entier, comme sur Discord.
• Pour chaque clé, tu choisis ce qu'elle peut lire (rôles, boost, niveaux…).
• Les webhooks font le chemin inverse : Hurix envoie un message à ton outil quand il se passe quelque chose. Ils préviennent seulement, ils ne modifient rien.

Tout se règle sur le dashboard, dans Pilotage → Paramètres, carte API développeurs. Cette page est réservée aux gestionnaires du serveur : les sous-utilisateurs ne la voient pas.

2. Repérer l'adresse de l'API

La carte API développeurs affiche :

• l'adresse de l'API, https://hurix.xyz/api/v1/guild, avec un bouton Copier ;
• les règles à retenir : un seul serveur par clé, lecture seule, la limite de requêtes par minute de ton serveur, et l'interdiction de mettre une clé dans une page web ;
• un exemple d'appel prêt à copier.

L'adresse ne contient jamais l'identifiant de ton serveur : c'est la clé qui dit à Hurix de quel serveur il s'agit.

3. Créer une clé et choisir ses permissions

Dans la carte Clés d'accès, clique sur Nouvelle clé.

1. Donne-lui un nom (60 caractères au plus) : le plugin ou l'outil qui l'utilisera, par exemple « Plugin Minecraft » ou « Site de la communauté ».
2. Coche ce que la clé peut lire. Ne coche que ce dont l'outil a besoin.

Informations Discord

• Fiche du membre : pseudo, avatar, date d'arrivée sur le serveur, date de création du compte.
• Rôles : rôles du membre et liste des rôles du serveur.
• Boost : si le membre booste le serveur, et depuis quand.
• Tag de serveur : tag affiché sur le profil, et s'il s'agit de celui de ton serveur.
• Statut contient… : répond seulement oui ou non à « le statut contient-il ce texte ? », sans renvoyer le texte.
• Statut complet (sensible) : en ligne, absent, ne pas déranger ou hors ligne, et le texte du statut personnalisé.

Données Hurix

• Niveaux : XP, niveau, rang et temps passé en vocal.
• Invitations : invitations du membre et qui l'a invité.
• Économie : solde, total gagné et dépensé, séries, inventaire.
• Activité : messages et minutes de vocal sur 7 et 30 jours.
• Vérification : si le membre a passé le captcha, et quand.
• Sanctions (sensible) : nombre de sanctions par type et sanction en cours, sans les raisons ni le membre du staff.
• Anniversaire (sensible) : jour et mois de l'anniversaire, jamais l'année.

Les trois permissions marquées Sensible sont décochées par défaut. Si tu en coches une, Hurix te le rappelle : ne donne cette clé qu'à un outil de confiance.

Les données Hurix ne se lisent que si le module correspondant est activé sur ton serveur (Niveaux, Invitations, Économie, Captcha, Modération, Anniversaires). L'activité, elle, vient des statistiques du dashboard et se lit toujours.

Clique sur Créer la clé.

4. Copier la clé (une seule fois)

Hurix affiche la clé complète, qui commence par hxm_. Clique sur Copier et colle-la tout de suite dans la configuration de ton outil, puis clique sur J'ai copié.

Dans la liste, chaque clé affiche son nom, son début, ses permissions (les sensibles en orange), qui l'a créée et quand, et la date de sa dernière utilisation (ou « jamais utilisée »).

Tester la clé

La personne qui gère ton outil peut vérifier que tout marche avec cet appel, tiré de la documentation (remplace l'identifiant Discord et la clé) :

curl https://hurix.xyz/api/v1/guild/members/123456789012345678 \
  -H "Authorization: Bearer hxm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Hurix répond la fiche du membre. Les champs rôles, boost, tag et statut n'apparaissent que si la clé a la permission correspondante. Pour une whitelist, le plus simple est :

curl https://hurix.xyz/api/v1/guild/members/123456789012345678/has-role/222222222222222222 \
  -H "Authorization: Bearer hxm_…"

qui répond simplement { "hasRole": true } ou false. Toutes les autres adresses (niveaux, invitations, classements…) sont décrites sur hurix.xyz/developers/members, avec des exemples pour Spigot/Paper et FiveM.

5. Révoquer une clé

Une clé a fuité, ou l'outil ne sert plus ? Clique sur Révoquer à côté de la clé, puis confirme.

• Les outils qui l'utilisent cessent de fonctionner immédiatement.
• C'est définitif : une clé révoquée ne se réactive pas. Crée une nouvelle clé si besoin.
• La révocation libère une place dans ta limite de clés.

6. Ajouter un webhook

Plutôt que d'interroger l'API sans arrêt (« il booste ? et maintenant ? »), laisse Hurix prévenir ton outil. Dans la carte Webhooks, clique sur Nouveau webhook.

1. Adresse (https) : l'adresse de ton serveur qui recevra les messages. Elle doit commencer par https:// et être publique : les adresses IP et les réseaux locaux sont refusés.
2. Événements : coche ceux que tu veux recevoir (ou Tout cocher) :
   • Arrivée d'un membre, Départ d'un membre ;
   • Rôles modifiés, Pseudo modifié ;
   • Début d'un boost, Fin d'un boost ;
   • Tag de serveur modifié ;
   • Statut : texte ajouté, Statut : texte retiré (sensibles) ;
   • Passage de niveau, Arrivée par invitation, Vérification réussie ;
   • Nouvelle sanction (sensible) : le type (avertissement, mute, expulsion, bannissement) et la fin éventuelle, sans raison ni membre du staff.
3. Si tu coches un événement de statut, indique les textes de statut à surveiller : un par ligne, 10 au plus, majuscules ignorées (par exemple discord.gg/hurixcafe). Hurix ne prévient que quand un de ces textes apparaît ou disparaît du statut d'un membre, jamais à chaque passage en ligne.

Les événements sensibles sont décochés par défaut.

Clique sur Créer le webhook. Hurix affiche le secret de signature, qui commence par whsec_. Copie-le dans la configuration de ton serveur : il permet de vérifier que chaque message vient bien de Hurix.

Vérifier la signature (pour le développeur)

Chaque envoi est un POST en JSON avec les en-têtes X-Hurix-Event, X-Hurix-Delivery (identifiant unique, utile pour ignorer un doublon), X-Hurix-Timestamp et X-Hurix-Signature. La signature vaut sha256= suivi du HMAC-SHA256 du texte horodatage.corps avec le secret. Exemple Node.js tiré de la documentation :

import { createHmac, timingSafeEqual } from "node:crypto";

// express.raw({ type: "application/json" }) : il faut le corps brut.
app.post("/hurix", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Hurix-Timestamp");
  const signature = req.get("X-Hurix-Signature") ?? "";
  const expected = "sha256=" + createHmac("sha256", process.env.HURIX_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  if (!fresh || signature.length !== expected.length ||
      !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  if (event.event === "member.boost.start") giveVip(event.data.userId);
  res.sendStatus(200); // réponds vite (moins de 8 s), traite ensuite
});

Refuse toujours un message dont la signature ne correspond pas, ou dont l'horodatage a plus de 5 minutes.

7. Tester et suivre un webhook

Chaque webhook de la liste affiche son état (Actif, Désactivé, Échecs récents ou Coupé après trop d'échecs), son adresse, le nombre d'événements et le résultat du dernier envoi. Sur la ligne :

• l'interrupteur active ou désactive le webhook ;
• Tester envoie un message de test (événement ping) dans les secondes qui suivent ;
• la corbeille supprime le webhook, après confirmation : plus rien n'est envoyé à cette adresse et les envois en attente sont abandonnés ;
• la flèche déplie les détails.

Une fois déplié, tu vois les événements choisis (avec Modifier pour en changer, ainsi que les textes de statut surveillés) et les derniers envois : Envoyé, En attente ou Échec, avec l'heure, le nombre d'essais et l'erreur éventuelle. Le bouton Renvoyer remet un envoi en file, par exemple après avoir réparé ton serveur.

Bon à savoir :

• ton serveur doit répondre par un code 2xx en moins de 8 secondes. Sinon, Hurix réessaie après 1 min, 5 min, 30 min, 2 h, 6 h puis 24 h, et abandonne ;
• après 20 échecs d'affilée, le webhook est coupé. Répare ton serveur, puis réactive-le avec l'interrupteur ;
• les changements de rôles d'un même membre en moins de 2 secondes sont regroupés en un seul envoi ;
• l'événement « Départ d'un membre » ne fait pas la différence entre un départ, une expulsion et un bannissement.

8. Voir les derniers appels

La carte Derniers appels garde les 100 derniers appels faits avec les clés du serveur. Clique sur Afficher pour les voir : code de réponse, adresse appelée, nom de la clé utilisée et heure.

Les codes à connaître :

• 200 : tout va bien ;
• 401 : clé absente, invalide ou révoquée ;
• 403 : la clé n'a pas la permission demandée (par exemple lire le statut sans « Statut complet ») ;
• 404 : le compte n'est pas sur le serveur, ou le module concerné est désactivé ;
• 429 : la limite de requêtes par minute est atteinte. L'outil doit attendre le délai indiqué avant de réessayer.

C'est le meilleur endroit pour repérer un outil qui appelle trop souvent ou une clé qu'on utilise sans ton accord.

9. Les limites

Sans Premium, chaque serveur a droit à :

• 30 requêtes par minute, toutes clés confondues ;
• 2 clés d'accès ;
• 2 webhooks.

Avec Premium, ces limites sont plus élevées selon l'offre (voir la page Premium). Les chiffres de ton serveur sont affichés sur le dashboard : la limite de requêtes dans la carte API développeurs, le compteur à côté de Clés d'accès et de Webhooks (par exemple 2 / 2). Quand une limite est atteinte, le bouton de création est grisé ; révoque une clé ou supprime un webhook pour libérer une place.

10. Les bons réflexes de sécurité

• Ne mets jamais une clé dans une page web (code JavaScript d'un site, application mobile…) : n'importe qui pourrait la lire. Une clé s'utilise depuis un serveur : plugin de jeu, script, back-end de ton site.
• Une clé par outil, avec seulement les permissions dont il a besoin. Si l'un d'eux fuite, tu ne révoques que celle-là.
• Garde les données sensibles (statut complet, sanctions, anniversaire) pour les outils de confiance.
• Une clé qui a fuité, ou un appel inconnu dans Derniers appels ? Révoque la clé tout de suite.
• Même avec la bonne clé, l'API ne peut rien modifier : pas de rôle donné, pas de sanction, pas de message envoyé.

Questions fréquentes

Je ne vois pas la carte API développeurs. Elle est réservée aux gestionnaires du serveur (propriétaire et membres qui peuvent gérer le serveur). Les sous-utilisateurs n'y ont pas accès.

L'API peut-elle donner un rôle ou sanctionner un membre ? Non. Elle est en lecture seule : seules les lectures existent, toute autre demande est refusée. Les webhooks, eux, préviennent seulement.

Peut-on voir pourquoi un membre a été sanctionné, ou par qui ? Non. La permission « Sanctions » et l'événement « Nouvelle sanction » donnent seulement le type de sanction, le nombre et la fin éventuelle, jamais la raison ni le membre du staff.

J'ai perdu ma clé. Hurix peut-il me la redonner ? Non, elle n'est affichée qu'une fois. Révoque-la et crée-en une nouvelle, puis mets à jour ton outil. C'est pareil pour le secret d'un webhook : supprime le webhook et recrée-le.

Mon webhook est « Coupé après trop d'échecs ». Ton serveur n'a pas répondu correctement 20 fois d'affilée. Vérifie qu'il est en ligne et qu'il répond par un code 2xx en moins de 8 secondes, puis réactive le webhook avec l'interrupteur et clique sur Tester.

Existe-t-il une API pour les tournois ? Oui, elle a sa propre documentation : hurix.xyz/developers/tournaments.