Přeskočit na obsah

API reference pro plugin (v2.1)

Kompletní kontrakt pluginového API. Všechny endpointy jsou pod /api/plugin/v1, autentizují se serverovým tokenem a odpovídají JSON s Cache-Control: no-store. Referenční implementace je oficiální plugin BlazeVip 2.x (složka plugin/ v repozitáři).

Autentizace, oprávnění a verze

http
Authorization: Bearer blz_TVUJ_TOKEN
User-Agent: BlazeVip/2.1.0
X-BlazeVip-Version: 2.1.0
X-BlazeVip-Capabilities: delivery-v2,revoke,test,heartbeat,local-dedupe,luckperms

Capability luckperms posílej jen tehdy, když je na serveru LuckPerms nainstalovaný. Doručení s nativními akcemi LuckPerms (viz payload.actions níže) dostane pouze plugin, který ji inzeruje — starší plugin by akce potichu přeskočil.

Neplatný, zneplatněný token nebo token smazaného serveru vrací 401 INVALID_TOKEN — všechny případy vypadají zvenčí stejně. Token pluginu má oprávnění (scopes) vip:claim, vip:ack, vip:read, heartbeat; chybějící oprávnění vrací 403 INSUFFICIENT_SCOPE. Tokeny „jen pro čtení“ (výpis VIP + heartbeat) jsou určené pro integrace třetích stran. Správa produktů a kódů (products:read, products:write, codes:write) se tokenu přidává jen na vyžádání při jeho vytvoření (typ „Správa produktů a kódů“ nebo „Plugin + správa“) — viz #products.

Plugin starší než minimální podporovaná verze dostane u claim odpověď 426 PLUGIN_UNSUPPORTED sminimumSupportedVersion; heartbeat se ale přijímá dál, aby majitel v panelu viděl, proč doručování stojí. Zastaralá (ale podporovaná) verze dostává hlavičku X-BlazeVip-Latest-Version.

Rate limity (na server, ne na IP): claim 60 v nárazu / 1 za s, ack a VIP dotazy 120 / 2 za s, heartbeat 10 / 1 za 20 s. Při překročení 429 s Retry-After. Neúspěšné pokusy o autentizaci jsou limitované podle IP.

Vyzvednutí doručení

POST/api/plugin/v1/deliveries/claimscope: vip:claim

Zarezervuje (lease 120 s) dávku doručení. Dvě instance pluginu dostanou vždy různá doručení. Každé doručení má neměnné deliveryId — podle něj plugin pozná, co už provedl.

json
// požadavek
{ "limit": 25 }

// odpověď (plugin s capability delivery-v2)
{
  "deliveries": [
    {
      "deliveryId": "cm1abc…",
      "type": "GRANT_VIP",            // GRANT_VIP | REVOKE_VIP | TEST
      "claimToken": "q7Gv…",
      "orderId": "cm1ord…",           // null u TEST
      "orderNumber": "VIP-20260925-7K2QX9",
      "createdAt": "2026-09-25T10:00:00.000Z",
      "attempt": 1,
      "payload": {
        "playerName": "Notch",
        "playerUuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
        "packageName": "VIP+",
        "quantity": 1,                     // počet kusů (VIP = 1)
        "commands": ["lp user {player} parent add vipplus"],
        "actions": [                       // jen pro plugin s capability luckperms
          { "type": "LUCKPERMS_GROUP_ADD", "group": "vipplus", "expiresAt": "2026-10-25T10:00:00.000Z" }
        ],
        "expiresAt": "2026-10-25T10:00:00.000Z",
        "test": false
      }
    }
  ],
  "count": 1,
  "plugin": { "latestVersion": "2.0.0", "minimumSupportedVersion": "1.0.0", "outdated": false }
}

Příkazy v payload jsou snapshot z okamžiku nákupu (u REVOKE snapshot příkazů pro odebrání) — pozdější úprava balíčku je nezmění. {player} a {uuid} dosazuje plugin; jméno hráče vždy znovu ověř proti ^[A-Za-z0-9_]{3,16}$.

Množství (quantity)

payload.quantity je počet zakoupených kusů (celé číslo ≥ 1; u VIP vždy 1). Server ho už dosadil do příkazů za {quantity} — pole je navíc pro pluginy, které předměty nebo peníze přidělují nativně (např. vlastní FiveM resource). packageName u množství větších než 1 obsahuje i „×N“ (pro zobrazení). Pole je ve všech doručeních (u starších záznamů ho server doplní z objednávky).

Nativní akce LuckPerms (actions)

json
// GRANT: přidá skupinu; expiresAt = konec VIP (null = trvale).
// Existující delší členství se nikdy nezkrátí, trvalé se nikdy nezmění na dočasné.
{ "type": "LUCKPERMS_GROUP_ADD", "group": "vip", "expiresAt": "2026-10-25T10:00:00.000Z" | null }
// REVOKE: odebere dočasné i trvalé členství skupiny.
{ "type": "LUCKPERMS_GROUP_REMOVE", "group": "vip" }

Akce se provedou PŘED příkazy. Neznámý typ akce = doručení selže (nikdy se tiše nepřeskočí). Název skupiny musí odpovídat ^[a-z0-9_-]{1,36}$. Akce jsou idempotentní, proto jsou bezpečnější než konzolové příkazy.

Zpětná kompatibilita: plugin bez capability delivery-v2 (1.x) dostává pouze GRANT doručení ve starém tvaru { "orders": [{ orderId, claimToken, playerName, commands, … }] } a potvrzuje je přes orderId. REVOKE a TEST doručení čekají, dokud se nepřipojí plugin 2.x.

Potvrzení

POST/api/plugin/v1/deliveries/ackscope: vip:ack
json
{
  "deliveryId": "cm1abc…",
  "claimToken": "q7Gv…",            // z claimu, který doručení vydal
  "success": true,
  "executedAt": "2026-09-25T10:00:03.120Z",
  "alreadyProcessed": false          // true = provedeno dříve, jen potvrzuji
}
OdpověďVýznamCo udělat
200 DELIVEREDZapsánoHotovo
200 ALREADY_ACKEDDuplicitní ACKHotovo
200 RETRY_SCHEDULEDSelhání zapsáno, zkusí se znovuNic
200 GAVE_UP5. selhání — GRANT se automaticky refundujeOprav příkazy
selhání „possible partial execution after crash“Plugin 2.1 zjistil pád uprostřed prováděníServer doručení NEOPAKUJE a NEREFUNDUJE — majitel ověří stav ve hře, spustí /blazevip resolve, admin doručení znovu zařadí
409 STALE_CLAIMLease vypršel, doručení má jiná instanceZahoď, neopakuj
409 CANCELLEDObjednávka se refundujeZahoď (případné odebrání přijde jako REVOKE)
404 NOT_FOUNDDoručení nepatří tomuto serveruZahoď
5xx / síťNejistéLease vyprší, server doručení vydá znovu

Doručení „právě jednou“

Síťový protokol je at-least-once: pokud plugin příkazy provede a spadne před ACK, server doručení po vypršení lease vydá znovu (se stejným deliveryId a novým claimToken). Plugin 2.1 si proto před spuštěním příkazů zapíše značku IN_PROGRESS a hned po posledním příkazu DONE (SQLite, synchronní zápis). Opakovaně vydané DONE doručení jen potvrdí s alreadyProcessed: true. Pokud najde IN_PROGRESS (pád uprostřed), příkazy znovu NESPUSTÍ a nahlásí „possible partial execution after crash“ — server doručení odloží k ruční kontrole místo automatické refundace. Absolutní „právě jednou“ pro libovolné konzolové příkazy zaručit nelze (tvrdý pád mezi posledním příkazem a zápisem). Příkazy proto piš idempotentně (lp user {player} parent add vip, ne give … 64) — nebo použij nativní akce LuckPerms.

Uplatnění kódu ve hře

POST/api/plugin/v1/redeemscope: vip:claim
json
// požadavek — hráč napsal /redeem <kód>
{
  "code": "ABCD-EFGH-JKMN",            // velikost písmen, mezery a pomlčky nevadí
  "playerName": "license:0123…",       // MC jméno, nebo FiveM identifikátor
  "identifierType": "LICENSE"          // FiveM: LICENSE | STEAM | DISCORD | FIVEM; MC: vynech (MC_NAME)
}

// úspěch — 200
{
  "ok": true,
  "message": "Kód uplatněn: VIP klíč ×3. Doručení proběhne za pár vteřin.",
  "packageName": "VIP klíč",
  "kind": "ONE_TIME",                  // VIP | ONE_TIME
  "quantity": 3,
  "orderNumber": "VIP-20261006-7K2QX9",
  "expiresAt": null,                   // u VIP nový konec VIP (ISO), u ONE_TIME null
  "deliveryQueued": true
}

// očekávané selhání — také 200, ok: false (zprávu ukaž hráči tak, jak je)
{ "ok": false, "code": "USED", "message": "Kód už byl uplatněn." }

Doručení nevzniká v odpovědi. Úspěšné uplatnění ve stejné transakci zařadí běžné GRANT doručení do fronty (deliveryQueued: true); plugin ho vyzvedne při dalším /deliveries/claim (obvykle do pár sekund) a potvrdí přes /deliveries/ack jako každý nákup. Příkazy tedy nespouštěj podle odpovědi /redeem — spouštěj je až z claimu, jinak se provedou dvakrát.

Kódy code: NOT_FOUND, USED, VOID, EXPIRED, WRONG_SERVER (kód je jiného serveru), INVALID_PLAYER, UNAVAILABLE, IN_REVIEW (platba čeká na kontrolu), NEEDS_ACCOUNT (giveaway kód na VIP — uplatňuje se na webu), RATE_LIMITED (HTTP 429). Kódy z nákupu (dárek nebo produkt „Vždy jako kód“) jdou ve hře uplatnit i u VIP; VIP se pak eviduje na účtu kupujícího.

Správa produktů z kódu

Pro vlastní integrace (např. synchronizace produktů z konfigurace FiveM resource). Token musí mít scope products:write (čtení stačí products:read). Pozor: kdo má products:write, mění i konzolové příkazy — tedy spouští příkazy na tvém serveru. Token drž jen v backendu. Každá změna příkazů pošle majiteli e-mail a zapíše se do auditu. Tyto volání nemění stav „plugin online“.

GET/api/plugin/v1/products?includeInactive=truescope: products:read | products:write
POST/api/plugin/v1/productsscope: products:write
json
{
  "name": "VIP klíč",
  "kind": "ONE_TIME",                  // VIP | ONE_TIME
  "priceCzk": 29,                      // CELÉ koruny (max. 2 desetinná místa)
  "priceEur": 1.19,                    // nepovinné; celé eura, null = neprodává se v EUR
  "durationDays": 0,                   // VIP: 1+ dní, ONE_TIME: 0
  "maxQuantity": 20,                   // ONE_TIME: max. kusů v objednávce
  "alwaysAsCode": true,                // vždy jako kód (bez identifikátoru při nákupu)
  "categoryId": "cm1cat…",             // z GET /categories (nebo null)
  "commands": ["givekey {player} vip {quantity}"],   // alias: grantCommands
  "revokeCommands": [],                // při vypršení / refundaci
  "giftable": true, "isActive": true, "sortOrder": 0,
  "description": "…", "perks": ["…"],
  "salePriceCzk": 24, "salePriceEur": 0.99, "saleEndsAt": "2026-10-31T22:00:00Z"   // akce (nepovinné)
}
GET/api/plugin/v1/products/{productId}scope: products:read | products:write
PATCH/api/plugin/v1/products/{productId}scope: products:write
DELETE/api/plugin/v1/products/{productId}scope: products:write

Odpovědi vrací { "product": { … } } s penězi v haléřích / centech: price (CZK), priceEur (EUR, nebo null), salePrice, salePriceEur. PATCH přijímá libovolnou podmnožinu polí z POST. DELETE produkt jen skryje (už zaplacené VIP doběhnou) a vrací { "ok": true, "activeVips": 3 }. Validace je stejná jako v panelu (blokované příkazy, typ hry, akce musí být levnější než běžná cena) — chyba je 400 s issues. Už zaplacené objednávky změna produktu nikdy neovlivní.

GET/api/plugin/v1/categoriesscope: products:read | products:write
POST/api/plugin/v1/categoriesscope: products:write
json
// POST { "name": "Klíče" } → 201 { "category": { "id": "…", "name": "Klíče" }, "created": true }
// stejný název znovu → 200 { "category": { … }, "created": false }   (idempotentní)

Giveaway kódy přes API

POST/api/plugin/v1/codesscope: codes:write
json
// požadavek
{ "productId": "cm1prod…", "count": 10, "quantity": 1, "note": "Discord soutěž", "validDays": 30 }

// odpověď 201 — kódy se vrací jen jednou
{ "codes": ["ABCD-EFGH-JKMN", "…"], "productId": "cm1prod…", "quantity": 1,
  "expiresAt": "2026-11-05T10:00:00.000Z", "kind": "ONE_TIME" }

count 1–500, quantity jen u jednorázových produktů (≤ maxQuantity), validDays nepovinné. Kódy jsou zdarma (giveaway) a v panelu je majitel vidí v „Slevy a kódy“. Jednorázové produkty jdou uplatnit ve hře přes /redeem, giveaway VIP jen na webu.

Heartbeat

POST/api/plugin/v1/heartbeatscope: heartbeat
json
// požadavek (každých nextHeartbeatSeconds, výchozí 60 s)
{
  "pluginVersion": "2.1.0",
  "minecraftVersion": "1.21.1-R0.1-SNAPSHOT",
  "serverSoftware": "Paper 1.21.1-119",
  "onlineMode": true,
  "lastDeliveryAt": "2026-09-25T09:58:00Z",
  "processedStoreSize": 1284,
  "capabilities": ["delivery-v2", "revoke", "test", "heartbeat", "local-dedupe", "luckperms"]
}

// odpověď
{ "ok": true, "serverTime": "…", "latestVersion": "2.0.0", "minimumSupportedVersion": "1.0.0",
  "outdated": false, "unsupported": false, "nextHeartbeatSeconds": 60 }

Neposílej žádná soukromá data (seznam hráčů, IP adresy, MOTD). Plugin je v panelu „online“, pokud se ozval během posledních 3 minut; po 30 minutách ticha dostane majitel e-mail.

Aktivní VIP

GET/api/plugin/v1/vips?cursor=&limit=500scope: vip:read
json
{ "vips": [{ "player": "Notch", "uuid": "…", "packageId": "…", "packageName": "VIP", "expiresAt": "…" }],
  "nextCursor": "cm1…" }
GET/api/plugin/v1/vips/{jmeno-nebo-uuid}scope: vip:read
json
{ "vip": true, "expiresAt": "…", "packages": [{ "packageId": "…", "packageName": "VIP", "expiresAt": "…" }] }

Hráč bez VIP vrací 200 { "vip": false }, ne 404. Aktivní = expiresAt > now.