Server-API | Noxyr-Dokumentation

Was die API bereitstellt

Die API ist nur lesend und auf einen Server beschränkt. Sie ist für Status-Seiten, Tabellen und interne Tools gedacht, die die Zahlen des Dashboards ohne Anmeldung brauchen. Sie kann keine Einstellungen ändern, keine Tickets schließen und keine Rechnungen erstellen.

Jeder Endpunkt liegt unter https://noxyrbot.com/api/v1 und liefert JSON. Der Schlüssel identifiziert den Server, daher nimmt kein Endpunkt eine Server-ID entgegen.

GET /api/v1/: Welche Bereiche für diesen Schlüssel aktiv sind und welche Endpunkte er erreichen kann.
GET /api/v1/server: Name, Icon, Mitgliederzahl, Online-Anzahl, Boosts und Erstellungsdatum.
GET /api/v1/tickets: Gesamtsummen, Anzahl offener und geschlossener Tickets, Volumen über 7 und 30 Tage, durchschnittliche Bewertung.
GET /api/v1/activity?days=30: Tägliche Nachrichten, Beitritte und Austritte, bis zu 90 Tage.
GET /api/v1/invoices: Rechnungsanzahl, Umsatz nach Währung und Zahlungsstatus. Mit dem Bereich Rechnungslinks fügt ?limit= aktuelle Rechnungen mit einer herunterladbaren Bild-URL hinzu.
GET /api/v1/reviews: Durchschnittliche Bewertung, Sternverteilung und die fünf neuesten öffentlichen Bewertungen.
GET /api/v1/giveaways: Anzahl aktiver und beendeter Gewinnspiele, Gesamtteilnahmen und die aktuellen Gewinnspiele.

Einen Schlüssel erstellen

Jeder Server hat genau einen Schlüssel. Er wird auf der API-Seite des Servers erzeugt und nur einmal angezeigt – gespeichert wird nur ein Hash. Ein verlorener Schlüssel muss daher neu erzeugt werden, wodurch der alte ungültig wird.

Öffne den Server im Dashboard und gehe zu API.
Drücke Erzeugen und kopiere den Schlüssel, der mit nxr_ beginnt. Er wird nicht noch einmal angezeigt.
Schalte jeden Bereich aus, den du nicht brauchst. Rechnungslinks ist standardmäßig aus, weil es Rechnungsbilder von Kunden offenlegt.
Optional: Drücke Kanal einrichten, damit der Bot auf dem Server eine API-Kategorie und einen Kanal mit der Endpunktliste anlegt.

Die Seite zeigt außerdem, wann der Schlüssel zuletzt verwendet wurde und wie viele Anfragen er gestellt hat – das ist der schnellste Weg, einen geleakten Schlüssel zu erkennen. Deaktiviere ihn mit dem Schalter oder widerrufe ihn, um ihn ganz zu löschen.

Bereiche

Bereiche sperren Endpunkte, nicht Felder. Eine Anfrage an einen Endpunkt, dessen Bereich aus ist, erhält einen 403 mit einer Meldung, die den Bereich nennt.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Fügt die aktuelle Rechnungsliste mit Bildlinks hinzu. Standardmäßig aus.
reviews: /reviews
giveaways: /giveaways

Authentifizierung und Beispielanfrage

Sende den Schlüssel als Bearer-Token im Authorization-Header. Aufrufe aus dem Browser sind erlaubt (CORS ist offen), aber ein Schlüssel im Frontend-Code ist ein öffentlicher Schlüssel – rufe die API deshalb von einem Server aus auf, den du kontrollierst.

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

Rate-Limits

Jeder Schlüssel darf 60 Anfragen pro Minute stellen. Das Limit wird in den Standard-RateLimit-Headern bei jeder Antwort zurückgegeben. Wird es überschritten, kommt HTTP 429 mit dem Fehler „rate_limited“. Frage nicht schneller ab, als sich die Daten ändern – Ticket- und Verkaufssummen kann man problemlos einmal pro Minute lesen.

Fehler

Jeder Fehler ist JSON mit einem maschinenlesbaren Fehlercode und einer menschenlesbaren Meldung.

401 unauthorized: Der Authorization-Header fehlt, ist kein Bearer-Token, oder der Schlüssel existiert nicht.
403 key_disabled: Der Schlüssel wurde im Dashboard ausgeschaltet.
403 scope_disabled: Dieser Bereich ist für diesen Schlüssel aus.
404 not_found: Unbekannter Endpunkt. Die Meldung listet die gültigen auf.
404 guild_unavailable: Der Bot ist nicht mehr auf dem Server.
429 rate_limited: Mehr als 60 Anfragen in einer Minute.
500 internal_error: Auf Noxyrs Seite ist etwas fehlgeschlagen. Versuche es später erneut.