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
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,luckpermsCapability 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.
429 s Retry-After. Neúspěšné pokusy o autentizaci jsou limitované podle IP.Vyzvednutí doručení
/api/plugin/v1/deliveries/claimscope: vip:claimZarezervuje (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.
// 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)
// 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.
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í
/api/plugin/v1/deliveries/ackscope: vip:ack{
"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ýznam | Co udělat |
|---|---|---|
| 200 DELIVERED | Zapsáno | Hotovo |
| 200 ALREADY_ACKED | Duplicitní ACK | Hotovo |
| 200 RETRY_SCHEDULED | Selhání zapsáno, zkusí se znovu | Nic |
| 200 GAVE_UP | 5. selhání — GRANT se automaticky refunduje | Oprav 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_CLAIM | Lease vypršel, doručení má jiná instance | Zahoď, neopakuj |
| 409 CANCELLED | Objednávka se refunduje | Zahoď (případné odebrání přijde jako REVOKE) |
| 404 NOT_FOUND | Doručení nepatří tomuto serveru | Zahoď |
| 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
/api/plugin/v1/redeemscope: vip:claim// 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“.
/api/plugin/v1/products?includeInactive=truescope: products:read | products:write/api/plugin/v1/productsscope: products:write{
"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é)
}/api/plugin/v1/products/{productId}scope: products:read | products:write/api/plugin/v1/products/{productId}scope: products:write/api/plugin/v1/products/{productId}scope: products:writeOdpově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í.
/api/plugin/v1/categoriesscope: products:read | products:write/api/plugin/v1/categoriesscope: products:write// 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
/api/plugin/v1/codesscope: codes:write// 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
/api/plugin/v1/heartbeatscope: heartbeat// 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
/api/plugin/v1/vips?cursor=&limit=500scope: vip:read{ "vips": [{ "player": "Notch", "uuid": "…", "packageId": "…", "packageName": "VIP", "expiresAt": "…" }],
"nextCursor": "cm1…" }/api/plugin/v1/vips/{jmeno-nebo-uuid}scope: vip:read{ "vip": true, "expiresAt": "…", "packages": [{ "packageId": "…", "packageName": "VIP", "expiresAt": "…" }] }Hráč bez VIP vrací 200 { "vip": false }, ne 404. Aktivní = expiresAt > now.