API reference pro plugin

Kompletní kontrakt pluginového API. Všechny endpointy jsou pod /api/plugin/v1 a autentizují se serverovým tokenem.

Autentizace

Každý požadavek musí nést token v hlavičce Authorization:

http

Authorization: Bearer blz_TVUJ_TOKEN

Token je vázaný na jeden server. Neplatný, zneplatněný nebo token vypnutého serveru vrací 401 s tělem { "code": "INVALID_TOKEN" }. Všechny tři případy vypadají zvenčí stejně — API neprozradí, který z nich nastal.

Rate limity: polling (claim, vips) 60 požadavků v nárazu, 1/s trvale. Zápisy (ack) 120 / 2 za s. Při překročení přijde 429 s hlavičkou Retry-After. Limit je na server, ne na IP.

Vyzvednutí nákupů

POST/api/plugin/v1/deliveries/claim

Zarezervuje dávku nezpracovaných nákupů a vrátí je i s claimToken. Rezervace platí 120 vteřin (lease). Dvě instance pluginu dostanou různé nákupy — stejný nákup se nikdy nevydá dvakrát současně.

Je to POST, protože mutuje — inkrementuje počet pokusů a razí lease.

Požadavek

json

{ "limit": 25 }

Odpověď

json

{
  "count": 1,
  "orders": [
    {
      "orderId": "clx...",
      "orderNumber": "VIP-20260710-K3M9QX",
      "claimToken": "aB3k...",          // musíš vrátit při ACK
      "playerName": "Notch",
      "playerUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "packageName": "VIP+",
      "durationDays": 30,
      "commands": [                       // už s dosazenými zástupci? NE — viz níže
        "lp user {player} parent add vipplus",
        "broadcast &c{player} koupil VIP+!"
      ],
      "expiresAt": "2026-08-09T12:00:00.000Z",
      "attempt": 1
    }
  ]
}

Příkazy přicházejí se zástupnými symboly ({player}, {uuid}). Nahrazení proběhne až v pluginu. Nikdy nedosazuj hodnoty, které neprošly validací jména hráče — viz sekce o bezpečnosti v návodu na vlastní plugin.

Potvrzení zpracování

POST/api/plugin/v1/deliveries/ack

Potvrdí (nebo nahlásí selhání) jednoho nákupu. Musíš poslat claimToken z odpovědi claim. Pokud lease vypršel a nákup mezitím převzala jiná instance, přijde 409 STALE_CLAIM — pak nákup zahoď.

Požadavek (úspěch)

json

{
  "orderId": "clx...",
  "claimToken": "aB3k...",
  "success": true
}

Požadavek (selhání)

json

{
  "orderId": "clx...",
  "claimToken": "aB3k...",
  "success": false,
  "error": "Neznámý příkaz: lp"
}

Odpovědi

text

200 { "ok": true, "status": "DELIVERED" }          úspěšně potvrzeno
200 { "ok": true, "status": "ALREADY_ACKED" }      duplicitní ACK — taky OK
200 { "ok": true, "status": "RETRY_SCHEDULED" }    selhání, bude se opakovat
200 { "ok": true, "status": "GAVE_UP_REFUNDED" }   5 pokusů vyčerpáno, kredit vrácen
409 { "ok": false, "status": "STALE_CLAIM" }       lease vypršel — zahoď nákup
404 { "ok": false, "status": "NOT_FOUND" }          nákup nepatří tvému serveru

ACK je idempotentní. Když ti odpověď na ACK nedorazí a pošleš ho znovu, dostaneš ALREADY_ACKED, ne chybu. Opakuj klidně.

Seznam aktivních VIP

GET/api/plugin/v1/vips?cursor=&limit=500

Všechny aktivní VIP na serveru. „Aktivní“ = expiresAt > teď. Stránkuje se kurzorem — projdi ho, dokud nextCursor není null.

json

{
  "vips": [
    {
      "player": "Notch",
      "uuid": "069a79f4-...",
      "packageId": "clx...",
      "packageName": "VIP+",
      "expiresAt": "2026-08-09T12:00:00.000Z"
    }
  ],
  "nextCursor": "clx..."   // nebo null, když jsi na konci
}

Kontrola jednoho hráče

GET/api/plugin/v1/vips/{player}

{player} může být jméno nebo UUID. Preferuj UUID — jména se v Minecraftu mění. Vrací 200 i když hráč VIP nemá (vip: false), ne 404.

json

{
  "vip": true,
  "expiresAt": "2026-08-09T12:00:00.000Z",   // nejzazší napříč balíčky
  "packages": [
    { "packageId": "clx...", "packageName": "VIP+", "expiresAt": "..." }
  ]
}

Shrnutí záruk

text

• Doručení je "alespoň jednou" → příkazy musí být idempotentní
• claim je atomický → dvě instance nedostanou stejný nákup
• ACK vyžaduje claimToken → mrtvá instance nemůže potvrdit cizí práci
• po 5 pokusech → nákup FAILED a kredit se hráči automaticky vrátí
• všechny odpovědi mají Cache-Control: no-store