API serveru
Čti statistiky tiketů, prodejů, recenzí a giveaway svého serveru z vlastních nástrojů.
Co API zpřístupňuje
API je jen pro čtení a je omezené na jeden server. Je určeno pro stavové stránky, tabulky a interní nástroje, které chtějí čísla z dashboardu bez přihlášení. Nemůže měnit nastavení, zavírat tikety ani vytvářet faktury.
Každý endpoint je pod https://noxyrbot.com/api/v1 a vrací JSON. Klíč určuje server, takže žádný endpoint nebere ID serveru.
- GET /api/v1/
- Které rozsahy jsou pro tento klíč zapnuté a které endpointy může dosáhnout.
- GET /api/v1/server
- Název, ikona, počet členů, počet online, boosty a datum vytvoření.
- GET /api/v1/tickets
- Součty, počty otevřených a zavřených, objem za 7 a 30 dní, průměrné hodnocení.
- GET /api/v1/activity?days=30
- Denní zprávy, připojení a odchody, až za 90 dní.
- GET /api/v1/invoices
- Počty faktur, tržby podle měny a stavu platby. S rozsahem invoice links přidá ?limit= nedávné faktury s URL obrázku ke stažení.
- GET /api/v1/reviews
- Průměrné hodnocení, rozpis hvězdiček a pět nejnovějších veřejných recenzí.
- GET /api/v1/giveaways
- Počty aktivních a skončených, celkový počet účastí a aktuální giveaway.
Vytvoření klíče
Každý server má jeden klíč. Vygeneruje se na stránce API serveru a zobrazí se jen jednou. Ukládá se jen hash, takže ztracený klíč je třeba vygenerovat znovu, čímž se starý zneplatní.
- Otevři server na dashboardu a přejdi na API.
- Stiskni Generate a zkopíruj klíč, který začíná nxr_. Znovu se nezobrazí.
- Vypni rozsahy, které nepotřebuješ. Invoice links je ve výchozím stavu vypnuto, protože odhaluje obrázky zákaznických faktur.
- Volitelně: stiskni Set up channel, bot na serveru vytvoří kategorii a kanál API se seznamem endpointů.
Stránka také ukazuje, kdy byl klíč naposledy použit a kolik požadavků udělal. Je to nejrychlejší způsob, jak poznat uniklý klíč. Vypni ho přepínačem, nebo ho zrušením úplně smaž.
Rozsahy
Rozsahy hlídají endpointy, ne pole. Požadavek na endpoint, jehož rozsah je vypnutý, dostane 403 se zprávou, která rozsah pojmenuje.
- overview
- /server
- tickets
- /tickets
- activity
- /activity
- invoices
- /invoices
- invoiceLinks
- Přidá seznam nedávných faktur s odkazy na obrázky. Ve výchozím stavu vypnuto.
- reviews
- /reviews
- giveaways
- /giveaways
Autentizace a ukázkový požadavek
Klíč pošli jako Bearer token v hlavičce Authorization. Volání jsou povolena z prohlížeče (CORS je otevřené), ale klíč ve frontendovém kódu je veřejný, takže API volej ze serveru, který ovládáš.
- curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
- Odpověď: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}
Limity požadavků
Každý klíč může udělat 60 požadavků za minutu. Limit se vrací ve standardních hlavičkách RateLimit u každé odpovědi a při překročení vrátí HTTP 429 s chybou „rate_limited“. Nedotazuj se častěji, než se data mění. Součty tiketů a prodejů stačí číst jednou za minutu.
Chyby
Každá chyba je JSON se strojově čitelným kódem chyby a lidskou zprávou.
- 401 neautorizováno
- Hlavička Authorization chybí, není to Bearer token, nebo klíč neexistuje.
- 403 key_disabled
- Klíč byl na dashboardu vypnut.
- 403 scope_disabled
- Tento rozsah je pro tento klíč vypnutý.
- 404 not_found
- Neznámý endpoint. Zpráva vypíše platné endpointy.
- 404 guild_unavailable
- Bot už na serveru není.
- 429 rate_limited
- Více než 60 požadavků za minutu.
- 500 internal_error
- Něco selhalo na straně Noxyru. Zkus to později znovu.