BR Tools — API dla developerów

Podstawy

Adres bazowy: https://brtools.erwinowak.dev

Format: wszystko to zwykły JSON, bez opakowania — odpowiedź to bezpośrednio tablica lub obiekt.

Autoryzacja: odczyty (wszystko poniżej oznaczone GET) są całkowicie publiczne, bez klucza API. Zapis (import bestiariusza) wymaga tokenu i nie jest przeznaczony dla zewnętrznych integracji — opisany niżej, zarezerwowany dla oficjalnych narzędzi tego projektu.

Limity i etykieta

To mały, prywatny serwer, nie infrastruktura klasy chmurowej — limity są tu po to, żeby jedna niewłaściwie napisana pętla nie potrafiła go położyć dla wszystkich innych.

Odczyty (wszystkie GET): ok. 180 zapytań / minutę / adres IP. Po przekroczeniu dostaniesz 429 Too Many Requests.
Odpowiedzi z agregacją (ceny, statystyki, bestiariusz) są cache'owane po stronie serwera na ok. 20 sekund — odpytywanie częściej niż raz na kilkanaście sekund i tak zwróci te same dane.

Jeśli budujesz coś, co odświeża dane cyklicznie, wystarczy raz na 30–60 sekund — dokładnie tyle, ile wynosi cykl wysyłki z samych trackerów. Częstsze odpytywanie nie da świeższych danych, tylko niepotrzebnie obciąży serwer.

Rynek

GET /v1/market/servers

Lista serwerów gry, dla których jest jakakolwiek aktywność w oknie ostatnich 7 dni.

curl https://brtools.erwinowak.dev/v1/market/servers

[
  { "server": "Veskara", "contributors": 3, "updatedAt": 1786737092790 }
]

GET /v1/market/prices

Zagregowane ceny dla danego serwera i kategorii, z ostatnich 7 dni.

Parametr	Wymagany	Opis
`server`	tak	nazwa serwera, np. `Veskara`
`category`	tak	`item` \| `orb` \| `drif`

curl "https://brtools.erwinowak.dev/v1/market/prices?server=Veskara&category=item"

[
  {
    "key": "1234",
    "name": "Kryształ Pamięci",
    "latest": 900000,
    "median": 900000,
    "min": 850000,
    "max": 950000,
    "quantity": 3,
    "samples": 5,
    "contributors": 2,
    "updatedAt": 1786737092790,
    "trendPct": 5.9,
    "history": [
      { "price": 850000, "at": 1786600000000 },
      { "price": 870000, "at": 1786650000000 },
      { "price": 900000, "at": 1786737092790 }
    ]
  }
]

trendPct to zmiana procentowa od najstarszego do najnowszego odczytu w oknie (0, jeśli nie da się ich porównać — np. tylko jeden odczyt). history to do 20 ostatnich odczytów wraz z ich znacznikiem czasu (at, unix ms), od najstarszego, do narysowania własnego wykresu.

GET /v1/market/stats

Zbiorcze statystyki dla całego serwera (wszystkie kategorie naraz) — liczba śledzonych pozycji, liczba zgłaszających, liczba zgłoszeń, per kategoria.

curl "https://brtools.erwinowak.dev/v1/market/stats?server=Veskara"

{
  "server": "Veskara",
  "categories": [
    { "category": "drif", "items": 12, "contributors": 2, "submissions": 40 },
    { "category": "item", "items": 231, "contributors": 3, "submissions": 900 },
    { "category": "orb", "items": 8, "contributors": 1, "submissions": 15 }
  ],
  "contributors": 3,
  "updatedAt": 1786737092790
}

Bestiariusz

GET /v1/bestiary/monsters

Lista potworów, opcjonalnie filtrowana kategorią.

Parametr	Wymagany	Opis
`category`	nie	`BOSS` \| `CHAMPION` \| `ELITE`

curl "https://brtools.erwinowak.dev/v1/bestiary/monsters?category=BOSS"

GET /v1/bestiary/monsters/{name}

Pełne dane jednego potwora po dokładnej nazwie.

curl https://brtools.erwinowak.dev/v1/bestiary/monsters/Hvar

POST /v1/bestiary/import

Administracyjny import całego bestiariusza — wymaga nagłówka Authorization: Bearer <token>. Używany wyłącznie przez własne, jednorazowe/cykliczne narzędzie importujące, nie przez klientów końcowych.

Przedmioty

Obejmuje zwykłe przedmioty ze swoją stroną na wiki oraz ekwipunek z zestawów (Sety) i rzadkich dropów (Rary), które własnej strony nie mają — te są zeskrapowane ze zbiorczych stron kategorii i mają dodatkowo stats (surowe statystyki) oraz, dla całego zestawu, setPieces (z jakich części się składa).

GET /v1/items

Pełna lista przedmiotów. Brak wyszukiwania po stronie serwera — filtruj po stronie klienta.

curl https://brtools.erwinowak.dev/v1/items

GET /v1/items/{name}

Jeden przedmiot po dokładnej nazwie.

curl https://brtools.erwinowak.dev/v1/items/Okowy%20Snu

{
  "name": "Okowy Snu",
  "description": "Szansa na trafienie krytyczne: 8%\nPŻ: +50",
  "droppedBy": ["Kruczy", "Treven", "Acerodon"],
  "setPieces": ["Buty Wymiarów", "Rękawice Oddalenia", "Szarfa Nieistnienia"],
  "usage": [], "acquisition": [], "stats": [],
  "fetchedAt": 1786737092790
}

Jedna część tego zestawu, dla porównania — ma własne value/weight/stats, ale setPieces puste (to nie jest zestaw, to jego część):

curl https://brtools.erwinowak.dev/v1/items/Buty%20Wymiar%C3%B3w

{
  "name": "Buty Wymiarów",
  "value": 56000,
  "weight": 15,
  "stats": ["Kategoria: Buty", "Ranga: II", "Wymagany poziom: 22", "Moc: +7", "..."],
  "droppedBy": ["Kruczy", "Treven", "Acerodon"],
  "usage": [], "acquisition": [], "setPieces": [],
  "fetchedAt": 1786737092790
}

POST /v1/items/import

Administracyjny import — ten sam token co /v1/bestiary/import. Używany wyłącznie przez import-items/import-consumables, nie przez klientów końcowych.

Surowce i konsumpcyjne

Flasze ulepszeń, Inhibitory, Surowce i składniki oraz Eliksiry — zeskrapowane przez import-consumables z ich indywidualnych stron wiki. To wciąż zwykłe rekordy z /v1/items, oznaczone dodatkowo category. Jeśli strona danego przedmiotu ma sekcję "Wytwarzanie", dochodzi craftedBy (kto/gdzie/za ile) i recipe — lista składników z ilościami, gdzie każda name to nazwa innego przedmiotu z tego samego /v1/items (np. surowca).

GET /v1/items?category={kategoria}

kategoria to flaszka, inhibitor, surowiec lub eliksir.

curl https://brtools.erwinowak.dev/v1/items?category=surowiec

curl https://brtools.erwinowak.dev/v1/items/Ma%C5%82a%20Flasza%20Kondycji

{
  "name": "Mała Flasza Kondycji",
  "description": "Butelka zawiera specjalną substancję, zdolną ulepszyć sprzęt rangi I-III...",
  "value": 500,
  "weight": 1,
  "category": "flaszka",
  "craftedBy": "Wykonuje ją Somnus w Wymarłej Osadzie za 500 sztuk złota, po dostarczeniu składników:",
  "recipe": [
    { "name": "Miętek", "quantity": 4 },
    { "name": "Krew wandala", "quantity": 2 }
  ],
  "usage": [], "acquisition": [], "droppedBy": [], "stats": [], "setPieces": [],
  "fetchedAt": 1786737092790
}

Każdy recipe[].name jest jednocześnie kluczem do GET /v1/items/{name} — np. Miętek to własny rekord (surowiec) z tego samego zbioru danych.

Obrazki

Wszystkie imageUrl zwracane przez /v1/bestiary/* i /v1/items/* wskazują na ten serwer, nie na wikibr.pl — obrazki są pobrane raz podczas importu i hostowane tutaj, więc działają niezależnie od tego, czy wiki jest akurat dostępne.

GET /images/{category}/{plik}

category to monsters lub items. Publiczne, cache'owane 30 dni.

curl https://brtools.erwinowak.dev/images/monsters/Hvar.png -o hvar.png

POST /v1/images/{category}/{name}

Administracyjny upload — ten sam token co pozostałe endpointy importu. Treść żądania to surowe bajty obrazka (nie JSON). Zwraca gotowy do zapisania w bazie adres:

{ "url": "https://brtools.erwinowak.dev/images/monsters/Hvar.png" }

Status

GET /v1/health

curl https://brtools.erwinowak.dev/v1/health
# {"status":"ok"}