API pre autorov modpackov: aktivačné kódy a aktualizácie

Nemusíš písať kód. Všetko, čo je popísané nižšie, je teraz dostupné aj cez tlačidlá: ak je tvoj modpack prepojený s tvojím účtom Millida, v profile sa ti zobrazí karta „Moje modpacky” — tam nahrávaš verzie, upravuješ kartu a vytváraš landing pages. Ak prepojený nie je, napíš nám a prepojíme ho. API je pre tých, ktorí nasadzujú z vlastného CI.

Tento článok je pre autorov platených modpackov, ktorí ich predávajú sami a inštaláciu na server nechávajú na nás. Kupujúci nemusí nič sťahovať: zadá kód a dostane nasadený modpack. Ako to vyzerá z jeho strany, si prečítaj v článku Platený modpack cez aktivačný kód.

Čo potrebuješ na začiatok

1. Pošli nám serverový archív svojho modpacku — .zip s priečinkom mods/ v koreni (bez obalového priečinka ako Server Files/) alebo .mrpack. Archív ukladáme do súkromného úložiska a odkaz nikdy nezverejňujeme navonok.
2. Povedz nám jadro, verziu hry a minimálnu pamäť — sprievodca podľa nich vyfiltruje plány, na ktorých modpack nepobeží.
3. Dostaneš od nás kľúč modpacku (key, napríklad arcania) a vydávací token — tvoja stránka ním generuje kódy.

Token sa zobrazí len raz: ukladáme iba jeho odtlačok. Ak ho stratíš, požiadaj nás o nový — starý prestane fungovať.

Ako to celé funguje

• Platbu prijímaš sám, na svojej strane.
• Po zaplatení tvoja stránka zavolá naše API a získa aktivačný kód.
• Kód dáš kupujúcemu — e-mailom, cez bota alebo na stránke s poďakovaním.
• Kupujúci zadá kód u nás a dostane server s modpackom na zaplatenom pláne.
• Súbory modpacku na serveri sú uzamknuté: mods sa nedá stiahnuť z ovládacieho panela ani cez SFTP.

Fyzicky sa kupujúcemu serverový modpack nikdy nedostane do rúk — len fungujúci server.

Endpoint a autorizácia

Základná URL — https://millida.net/v2/hosting.

Token sa posiela v hlavičke X-Pack-Token. Nie je to JWT ani Bearer token — je to samostatný tajný kľúč pre tvoj modpack.

X-Pack-Token: mpk_pack_XXXXXXXXXXXXXXXX
Content-Type: application/json

Token patrí na tvoj server — drž ho v premenných prostredia, nie v kóde frontendu.

Vydávanie kódov

POST /v2/hosting/packs/{key}/keys

curl -X POST https://millida.net/v2/hosting/packs/arcania/keys \
  -H "X-Pack-Token: $PACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "note": "order 4821"}'

{
  "code": "A7K2-9MHD-4RTP-QW38",
  "codes": ["A7K2-9MHD-4RTP-QW38"]
}

Pole code je prvý kód z dávky, zachované kvôli kompatibilite; pri count > 1 použi codes.

Kódy sa vracajú len tu a nikde inde. Ukladáme ich hash — ako heslo. Ak kód stratíš, nedokážeme ho obnoviť: vygeneruj nový a starý zruš.

Limit je 30 požiadaviek za minútu na modpack. Dávky až do 200 kódov na volanie existujú práve kvôli predaju: generuj ich hromadne, nie jeden kód na požiadavku.

Čo sa stalo s kódmi

GET /v2/hosting/packs/{key}/keys?limit=100

[
  {
    "codeHint": "A7K29MHD",
    "note": "order 4821",
    "maxServers": 1,
    "usedCount": 1,
    "state": "spent",
    "expiresAt": null,
    "revokedAt": null,
    "createdAt": "2026-08-03T12:20:11.000Z"
  }
]

Samotné kódy v odpovedi nie sú a ani nemôžu byť. codeHint je začiatok kódu — podľa neho priradíš riadok k svojej objednávke.

Stavy: free — nepoužitý, spent — použitý, expired — expirovaný, revoked — zrušený tebou.

Overenie jedného kódu

POST /v2/hosting/packs/{key}/keys/status, telo {"code": "A7K2-9MHD-4RTP-QW38"}.

Odpoveď je rovnaký riadok ako v zozname. Kód patrí do tela, nie do URL: URL končia v logoch proxy a histórii prehliadača a pred aktiváciou je kód funkčný kľúč.

Spojovníky a veľkosť písmen nehrajú rolu: a7k29mhd4rtpqw38 sa nájde rovnako ako A7K2-9MHD-4RTP-QW38.

Zrušenie kódu

POST /v2/hosting/packs/{key}/keys/revoke, telo {"code": "..."}.

Použi to pri vrátení peňazí, omylom vydaných kódoch alebo sporoch. Zrušenie zablokuje budúce aktivácie, ale neodstráni už nasadený modpack — kupujúci, ktorý ho aktivoval, má ďalej fungujúci server.

Webhook na aktiváciu

Ak nám dáš URL webhooku, zavoláme ho v momente, keď sa kód uplatní:

POST <your-address>
X-Millida-Pack: arcania
Content-Type: application/json

{
  "event": "pack.activated",
  "packKey": "arcania",
  "codeHint": "A7K29MHD",
  "serverId": "cm4x...",
  "activatedAt": "2026-08-04T09:14:02.000Z"
}

Volanie nie je podpísané: overíš ho tým istým tokenom cez keys/status — podľa codeHint nájdeš svoj riadok a uvidíš state: "spent". Nemusíš tak držať druhé tajomstvo.

Webhook sa posiela bez čakania na odpoveď a neopakuje sa: ak bol tvoj server dole, aktivácia aj tak prebehla a uvidíš ju v zozname kódov. URL musí byť verejná — na interné ani lokálne adresy nevoláme. Presmerovania sa nenasledujú.

Karta modpacku

GET /v2/hosting/packs/{key} je verejný, token netreba. Vráti to, čo vidí kupujúci: názov, jadro, verziu, minimálnu pamäť, zoznam plánov a príznaky ochrany. Odkaz na archív v odpovedi nie je.

Hodí sa na stránku „Kúpiť” na tvojom webe: požiadavky na plán pochádzajú z jedného zdroja a nebudú sa rozchádzať s tým, čo hovorí náš sprievodca.

Polia výkladnej skrine svojej karty si upravuješ sám: PATCH /v2/hosting/packs/{key} s tokenom prijme name, authorName, authorUrl, iconUrl, webhookUrl. Podmienky predaja (paidOnly, requireKey, lockFiles, planCodes), zapnutie modpacku vo výkladnej skrini a JVM launch flagy sa tokenom meniť nedajú — to je naša dohoda s tebou a naše nody, tak nám o nich napíš.

Aktualizácie modpacku

Predtým znamenala aktualizácia napísať nám a čakať. Teraz verziu publikuješ sám a majitelia serverov si ju vyberajú vo svojom ovládacom paneli.

Kľúčové je: nikomu neaktualizujeme potichu. Prechod medzi verziami modpacku môže byť nekompatibilný so svetom a rozhodnutie je na majiteľovi servera. Publikovanú verziu dostanú nové servery a ponúkame ju aj tým už nasadeným; predchádzajúce verzie zostávajú v zozname a môžeš na nich zostať alebo sa vrátiť späť.

Ako vyzerá cyklus

# 1. Create a version
curl -X POST https://millida.net/v2/hosting/packs/arcania/versions \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/json" \
  -d '{"label":"1.5.0","changelog":"Updated Create to 0.5.1, fixes crash on portals","minRamMb":10240}'

# 2. Upload the archive in chunks (32 MB each), addressing by offset
curl -X POST "https://millida.net/v2/hosting/packs/arcania/versions/1.5.0/archive?offset=0" \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/octet-stream" \
  --data-binary @part0.bin

# 3. Say the archive is finished, and publish after parsing
curl -X POST https://millida.net/v2/hosting/packs/arcania/versions/1.5.0/finish \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/json" \
  -d '{"archiveSha256":"<sha256 of archive>","publish":true}'

# 4. Wait for parsing
curl https://millida.net/v2/hosting/packs/arcania/versions/1.5.0 -H "X-Pack-Token: $PACK_TOKEN"

Verzia

Nahrávanie

POST /v2/hosting/packs/{key}/versions/{label}/archive?offset=N, telo — časť .zip, Content-Type: application/octet-stream. Časť do 32 MB, celý archív do 4 GB.

Časť sa adresuje cez offset, nie „pripoj na koniec“: časť prerušená v polovici už čiastočne pristála v súbore a opakovaný pokus by pridal tie isté bajty druhýkrát — archív by dorazil potichu poškodený. Odpoveď vracia uploadedBytes, podľa ktorého sa nahrávanie obnoví po prerušení.

Spracovanie

POST .../finish odpovie hneď (status: "processing"), zatiaľ čo spracovanie beží na pozadí: rozbalenie gigabajtovej konfigurácie servera trvá minúty. Stav čítaj z GET .../versions/{label}: processing → ready alebo failed s textom dôvodu v error.

Čo musí archív spĺňať:

• je to serverový pack: po odstránení jedného obalu (Server Files/ a podobne) je mods/ alebo plugins/ v koreni. Klientský pack na serveri vytvorí prázdny svet, preto ho radšej odmietneme, než by sme ho nainštalovali;
• žiadne .., absolútne cesty ani Windows oddeľovače v názvoch vnútri archívu;
• žiadne heslo, žiadne exotické metódy kompresie (len store a deflate);
• limity: 60 000 súborov, 12 GB rozbalených, kompresný pomer do 200×.

Zlyhanie neovplyvní publikovanú verziu: tvoji klienti ďalej bežia na predchádzajúcej a ty nahráš znova. Nedokončené koncepty: najviac tri na jednu konfiguráciu servera, opustené sa automaticky čistia po dni.

Publikovanie, rollback a odstránenie

Publikovanie prenesie core, hernú verziu, pripnutie loadera, Java a minimálnu pamäť verzie do karty konfigurácie servera: nové servery ju dostanou bez toho, aby si čokoľvek robil.

Čo vidí majiteľ servera

V ovládacom paneli v bloku prémiovej konfigurácie servera: ktorá verzia je nainštalovaná, ktorá vyšla, tvoj changelog a zoznam verzií s tlačidlom „Prepnúť“. Aktualizácia neovplyvní svet — nahradia sa len súbory konfigurácie servera a pred nahradením si spravíme kópiu. Vlastné mody, ak si ich povolil, budeš musieť po prepnutí pridať znova: konfigurácia servera sa presúva ako jeden celok a polovica starej verzie v mods/ znamená pád pri štarte.

Ak to plán majiteľa neunesie, ukážeme to aj s dôvodom, namiesto toho, aby sme to skryli: človek má vidieť, čo potrebuje, a nie hádať, prečo sa konfigurácia servera neaktualizuje.

Vlastná stránka konfigurácie servera

Landing page pre svoju konfiguráciu servera si postavíš sám vo svojom účte (profil → „Moje konfigurácie serverov“ → „Stránky konfigurácií serverov“): prvá obrazovka, funkcie, screenshoty, otázky a odpovede, tvoje farby. Plány a zoznam verzií sa napĺňajú našimi dátami, aby nezostarli.

Hotová stránka žije na millida.net/sborka/<tvoja-adresa> — bežná stránka webu, indexovaná vyhľadávačmi a zahrnutá v našej sitemape. Koncept nevidí nikto okrem teba.

Obrázky sa nahrávajú na tom istom mieste, vo tvojom účte: stránka sa servíruje z našej domény a jej súbory sú uložené u nás — ak tvoj hosting padne, stránka zostane nedotknutá.

Stránky sa nedajú upravovať cez API: je to obrazovka, nie rollout.

Kódy odpovedí

Ako si všetko otestovať pred predajom

Vyžiadaj si od nás pár testovacích kódov: cez API vydaj kód, aktivuj ho na svojom serveri u nás na hostingu, pozri, čo dorazilo do webhooku a čo ukazuje keys/status. Takto uvidíš celú cestu kupujúceho skôr, než ňou prejde prvý platiaci zákazník.