API serwera | Dokumentacja Noxyr

Co udostępnia API

API jest tylko do odczytu i ogranicza się do jednego serwera. Przeznaczone jest do stron statusu, arkuszy kalkulacyjnych i wewnętrznych narzędzi, które chcą liczb z dashboardu bez logowania. Nie może zmieniać ustawień, zamykać ticketów ani tworzyć faktur.

Każdy endpoint znajduje się pod https://noxyrbot.com/api/v1 i zwraca JSON. Klucz identyfikuje serwer, więc żaden endpoint nie przyjmuje ID serwera.

GET /api/v1/: Które zakresy są włączone dla tego klucza i do których endpointów ma dostęp.
GET /api/v1/server: Nazwa, ikona, liczba członków, liczba online, boosty i data utworzenia.
GET /api/v1/tickets: Sumy, liczba otwartych i zamkniętych, wolumen z 7 i 30 dni, średnia ocena.
GET /api/v1/activity?days=30: Dzienne wiadomości, dołączenia i wyjścia, do 90 dni.
GET /api/v1/invoices: Liczba faktur, przychód według waluty i status płatności. Przy zakresie invoice links parametr ?limit= dodaje ostatnie faktury z adresem URL obrazu do pobrania.
GET /api/v1/reviews: Średnia ocena, podział na gwiazdki i pięć najnowszych publicznych recenzji.
GET /api/v1/giveaways: Liczba aktywnych i zakończonych rozdań, łączna liczba wpisów i bieżące rozdania.

Tworzenie klucza

Każdy serwer ma jeden klucz. Jest generowany na stronie API serwera i pokazywany tylko raz – zapisywany jest tylko hash, więc utracony klucz trzeba wygenerować ponownie, co unieważnia stary.

Otwórz serwer w dashboardzie i przejdź do API.
Naciśnij Generuj i skopiuj klucz zaczynający się od nxr_. Nie zostanie pokazany ponownie.
Wyłącz każdy zakres, którego nie potrzebujesz. Linki do faktur są domyślnie wyłączone, ponieważ ujawniają obrazy faktur klientów.
Opcjonalnie: naciśnij Ustaw kanał, aby bot utworzył na serwerze kategorię i kanał API z listą endpointów.

Strona pokazuje też, kiedy klucz był ostatnio używany i ile zapytań wykonał – to najszybszy sposób na wykrycie wyciekłego klucza. Wyłącz go przełącznikiem albo unieważnij, aby usunąć go całkowicie.

Zakresy

Zakresy kontrolują endpointy, a nie pola. Zapytanie do endpointu, którego zakres jest wyłączony, dostaje 403 z komunikatem wskazującym ten zakres.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Dodaje ostatnią listę faktur z linkami do obrazów. Domyślnie wyłączone.
reviews: /reviews
giveaways: /giveaways

Uwierzytelnianie i przykładowe zapytanie

Wyślij klucz jako token Bearer w nagłówku Authorization. Wywołania z przeglądarki są dozwolone (CORS jest otwarte), ale klucz w kodzie front-endu jest kluczem publicznym, więc wywołuj API z serwera, który kontrolujesz.

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

Limity zapytań

Każdy klucz może wykonać 60 zapytań na minutę. Limit jest zwracany w standardowych nagłówkach RateLimit w każdej odpowiedzi, a przekroczenie zwraca HTTP 429 z błędem „rate_limited”. Nie odpytuj częściej, niż zmieniają się dane – sumy ticketów i sprzedaży wystarczy odczytywać raz na minutę.

Błędy

Każdy błąd to JSON z kodem błędu czytelnym dla maszyn i komunikatem dla człowieka.

401 unauthorized: Brakuje nagłówka Authorization, nie jest on tokenem Bearer albo klucz nie istnieje.
403 key_disabled: Klucz został wyłączony w dashboardzie.
403 scope_disabled: Ten zakres jest wyłączony dla tego klucza.
404 not_found: Nieznany endpoint. Komunikat wymienia prawidłowe.
404 guild_unavailable: Bot nie znajduje się już na serwerze.
429 rate_limited: Ponad 60 zapytań w ciągu minuty.
500 internal_error: Coś się nie powiodło po stronie Noxyr. Spróbuj ponownie później.