Dokumentacja API bota

Uwierzytelnianie

Utwórz token na stronie API bota w panelu i wyślij go w nagłówku Authorization: Authorization: Bearer <token>. Token należy do jednego serwera i czyta tylko ten serwer. Jest pokazywany raz; DayZ Hub przechowuje tylko jego odcisk.

curl -H "Authorization: Bearer dhba_..." \
  https://dayzhub.net/api/v1/bot/guilds/<guildId>

Bazowy URL: https://dayzhub.net/api/v1/bot

Punkty końcowe

Każda odpowiedź to JSON w tej samej kopercie. Listy są stronicowane przez limit (od 1 do 100) i kursor z page.nextCursor.

{ "ok": true, "data": [ ... ], "page": { "limit": 25, "hasMore": true, "nextCursor": "eyJpZCI6Ij..." } }

Zakresy

Każdy token ma tylko te zakresy, które mu nadasz. Wszystkie są tylko do odczytu; przez to API nic nie da się zmienić.

Prywatność członków

Członkowie pojawiają się tylko tam, gdzie funkcja już pokazuje ich publicznie, jako identyfikator Discord. Członek, który sprzeciwił się przetwarzaniu danych, jest zawsze pokazywany jako anonimowy, jak poniżej. Nazwy, wiadomości, tickety i odpowiedzi z formularzy nigdy nie są częścią API.

{ "id": null, "anonymous": true }

Limity

Limity zależą od planu serwera. Premium 1: aktywnych tokenów 2, żądań na minutę na token 60. Premium 2: tokenów 5, 120 na minutę. Premium 3: tokenów 10, 300 na minutę. Darmowy okres próbny lub serwer sponsorowany liczy się jako Premium 1. Każdy adres IP może wykonać 300 żądań na minutę. Po przekroczeniu dostaniesz 429 z nagłówkiem Retry-After. Obniżenie planu nie unieważnia żadnego tokenu: te, które masz, nadal działają, tylko nowe są zablokowane, dopóki nie będziesz poniżej limitu. Serwer potrzebuje płatnego planu lub aktywnego okresu próbnego.

Pamięć podręczna

Odpowiedzi mają ETag i krótką prywatną pamięć podręczną. Wyślij If-None-Match, aby dostać 304, gdy nic się nie zmieniło. Odpytywanie co 30–60 sekund w zupełności wystarcza.

Przeglądarki i CORS

Wywołuj API z własnego serwera. CORS jest domyślnie wyłączony. Jeśli strona musi wywołać API z przeglądarki odwiedzającego, ustaw jedną dozwoloną stronę w tokenie; żądania z każdego innego źródła są odrzucane. Wszystko na stronie internetowej jest widoczne dla odwiedzających.

Twój token, plan i limity

GET /me nie sprawdza planu. Oprócz samego tokenu zwraca plan (premium1, premium2, premium3 lub none), limits (tokens i perMinute tego planu) oraz tokensUsed (aktywne tokeny serwera). rateLimitPerMin to tempo, jakie ten token ma w tej chwili.

{ "ok": true, "data": { "guildId": "123456789012345678", "name": "Website", "prefix": "dhba_aB3dE", "scopes": ["guild:read"],
  "allowedOrigin": null, "rateLimitPerMin": 120, "createdAt": "2026-10-01T12:00:00.000Z",
  "plan": "premium2", "limits": { "tokens": 5, "perMinute": 120 }, "tokensUsed": 2 } }

Identyfikatory żądań

Każda odpowiedź niesie nagłówek X-Request-Id. Jeśli wyślesz własny X-Request-Id (do 64 liter, cyfr i znaków . _ : -), zostanie zachowany, w przeciwnym razie zostanie wygenerowany. Błędy powtarzają go jako requestId. Podaj go, kontaktując się z pomocą.

X-Request-Id: 3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c

{ "ok": false, "error": "rate_limited", "code": "rate_limited", "message": "Too many requests", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

Błędy

Błędy to JSON z ok: false, stabilnym kodem w code (error zawiera tę samą wartość), krótkim komunikatem i requestId. Decyduj według kodu, nigdy według tekstu komunikatu.