API du serveur | Documentation Noxyr

Ce que l'API expose

L'API est en lecture seule et limitée à un seul serveur. Elle est destinée aux pages de statut, aux tableurs et aux outils internes qui veulent les chiffres affichés par le tableau de bord sans connexion. Elle ne peut pas modifier les réglages, fermer des tickets ou créer des factures.

Chaque point d'accès se trouve sous https://noxyrbot.com/api/v1 et renvoie du JSON. La clé identifie le serveur, donc aucun point d'accès ne prend d'identifiant de serveur.

GET /api/v1/: Les portées activées pour cette clé et les points d'accès qu'elle peut atteindre.
GET /api/v1/server: Nom, icône, nombre de membres, nombre de membres en ligne, boosts et date de création.
GET /api/v1/tickets: Totaux, nombre de tickets ouverts et fermés, volume sur 7 et 30 jours, note moyenne.
GET /api/v1/activity?days=30: Messages, arrivées et départs par jour, jusqu'à 90 jours.
GET /api/v1/invoices: Nombre de factures, chiffre d'affaires par devise et statut de paiement. Avec la portée invoice links, ?limit= ajoute les factures récentes avec une URL d'image téléchargeable.
GET /api/v1/reviews: Note moyenne, répartition par étoiles et les cinq derniers avis publics.
GET /api/v1/giveaways: Nombre de giveaways actifs et terminés, nombre total de participations et giveaways en cours.

Créer une clé

Chaque serveur a une seule clé. Elle se génère sur la page API du serveur et n'est affichée qu'une fois : seul un hachage est stocké, donc une clé perdue doit être régénérée, ce qui invalide l'ancienne.

Ouvrez le serveur sur le tableau de bord et allez dans API.
Cliquez sur Générer et copiez la clé qui commence par nxr_. Elle ne sera plus affichée.
Désactivez les portées dont vous n'avez pas besoin. Invoice links est désactivé par défaut, car il expose les images de factures des clients.
Facultatif : cliquez sur Configurer un salon pour que le bot crée dans le serveur une catégorie et un salon API contenant la liste des points d'accès.

La page indique aussi la dernière utilisation de la clé et le nombre de requêtes effectuées, ce qui est le moyen le plus rapide de repérer une clé divulguée. Désactivez-la avec l'interrupteur, ou révoquez-la pour la supprimer complètement.

Portées

Les portées contrôlent les points d'accès, pas les champs. Une requête vers un point d'accès dont la portée est désactivée reçoit un 403 avec un message nommant la portée.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Ajoute la liste des factures récentes avec les liens d'images. Désactivé par défaut.
reviews: /reviews
giveaways: /giveaways

Authentification et exemple de requête

Envoyez la clé comme token Bearer dans l'en-tête Authorization. Les appels depuis le navigateur sont autorisés (CORS est ouvert), mais une clé placée dans le code front-end est une clé publique : appelez donc l'API depuis un serveur que vous contrôlez.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
Réponse : {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

Limites de débit

Chaque clé peut effectuer 60 requêtes par minute. La limite est renvoyée dans les en-têtes RateLimit standard de chaque réponse, et son dépassement renvoie HTTP 429 avec l'erreur « rate_limited ». N'interrogez pas plus souvent que les données ne changent : les totaux de tickets et de ventes peuvent être lus une fois par minute.

Erreurs

Chaque erreur est du JSON avec un code d'erreur lisible par une machine et un message lisible par un humain.

401 unauthorized: L'en-tête Authorization est absent, n'est pas un token Bearer, ou la clé n'existe pas.
403 key_disabled: La clé a été désactivée sur le tableau de bord.
403 scope_disabled: Cette portée est désactivée pour cette clé.
404 not_found: Point d'accès inconnu. Le message liste les points d'accès valides.
404 guild_unavailable: Le bot n'est plus sur le serveur.
429 rate_limited: Plus de 60 requêtes en une minute.
500 internal_error: Une erreur s'est produite côté Noxyr. Réessayez plus tard.