API для авторів збірок модів: коди активації та оновлення

Вам не обов'язково писати код. Усе описане нижче тепер доступне й кнопками: якщо ваша збірка модів прив'язана до акаунта Millida, у профілі з'являється вкладка «Мої збірки модів» — там ви завантажуєте версії, редагуєте картку та збираєте лендінги. Не прив'язана — напишіть нам, і ми прив'яжемо. API — для тих, хто розгортає зі свого CI.

Ця стаття для авторів платних збірок модів, які продають їх самостійно й передають встановлення сервера нам. Покупцеві не потрібно нічого завантажувати: він вводить код і отримує розгорнуту збірку модів. Щоб побачити, як це виглядає з його боку, прочитайте Платна збірка модів за кодом активації.

Що потрібно для початку

1. Надішліть нам серверний архів вашої збірки модів — .zip з mods/ у корені (без обгортки на кшталт Server Files/) або .mrpack. Архів зберігається в нашому приватному сховищі, і посилання ніколи не передається назовні.
2. Скажіть нам ядро, версію гри та мінімальний обсяг пам'яті — майстер використовує їх, щоб відфільтрувати тарифи, на яких збірка модів не запуститься.
3. Отримайте від нас ключ збірки модів (key, наприклад arcania) та токен видачі — ваш сайт використовує його для генерації кодів.

Токен показується лише один раз: ми зберігаємо тільки його відбиток. Якщо ви його втратите, попросіть нас перевидати — старий перестане працювати.

Як працює схема

• Ви приймаєте оплату самостійно, на своєму боці.
• Після оплати ваш сайт звертається до нашого API й отримує код активації.
• Ви передаєте код покупцеві — електронною поштою, ботом або на сторінці «дякуємо».
• Покупець вводить код на нашому боці й отримує сервер зі збіркою модів на оплаченому тарифі.
• Файли збірки модів на сервері захищені: mods не можна завантажити з панелі чи через SFTP.

Фізично покупець ніколи не отримує серверну збірку модів до рук — лише робочий сервер.

Ендпоінт і авторизація

Базова URL-адреса — https://millida.net/v2/hosting.

Токен передається в заголовку X-Pack-Token. Це не JWT і не Bearer-токен — це окремий секрет для вашої збірки модів.

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

Токен живе на вашому сервері — тримайте його у змінних середовища, а не в коді фронтенду.

Видача кодів

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"]
}

Поле code — це перший код у партії, збережене для сумісності; коли count > 1, використовуйте codes.

Коди повертаються лише тут і більше ніде. Ми зберігаємо їхній хеш — як пароль. Якщо ви втратите код, ми не зможемо його відновити: видайте новий і відкличте старий.

Ліміт — 30 запитів за хвилину на одну збірку модів. Партії до 200 кодів за виклик існують саме для продажів: генеруйте їх гуртом, а не по одному коду на запит.

Що сталося з кодами

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"
  }
]

Самих кодів у відповіді немає й бути не може. codeHint — це початок коду; використовуйте його, щоб зіставити рядок зі своїм замовленням.

Стани: free — невикористаний, spent — використаний, expired — прострочений, revoked — відкликаний вами.

Перевірка одного коду

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

Відповідь — той самий рядок, що й у списку. Код передається в тілі, а не в URL: URL-адреси потрапляють у логи проксі та історію браузера, а до активації код є робочим ключем.

Дефіси та регістр не мають значення: a7k29mhd4rtpqw38 знайдеться так само, як A7K2-9MHD-4RTP-QW38.

Відкликання коду

POST /v2/hosting/packs/{key}/keys/revoke, тіло {"code": "..."}.

Використовуйте для повернень коштів, помилкових видач або спорів. Відкликання блокує майбутні активації, але не видаляє вже розгорнуту збірку модів — покупець, який її активував, зберігає робочий сервер.

Вебхук активації

Якщо ви надасте нам URL-адресу вебхука, ми викличемо його в момент погашення коду:

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"
}

Виклик не підписується: ви можете перевірити його тим самим токеном через keys/status — за codeHint знайдете свій рядок і побачите state: "spent". Так вам не доведеться зберігати другий секрет.

Вебхук надсилається без очікування відповіді й не повторюється: якщо ваш сервер був недоступний, активація все одно відбулася, і ви побачите її у списку кодів. URL-адреса має бути публічною — ми не викликаємо внутрішні чи локальні адреси. Переадресації не обробляються.

Картка збірки модів

GET /v2/hosting/packs/{key} — публічний, токен не потрібен. Він повертає те, що бачить покупець: назву, ядро, версію, мінімальний обсяг пам'яті, список тарифів і прапорці захисту. Посилання на архів у відповіді немає.

Зручно для сторінки «Купити» на вашому сайті: вимоги до тарифів беруться з єдиного джерела й не розійдуться з тим, що каже наш майстер.

Поля вітрини своєї картки ви редагуєте самостійно: PATCH /v2/hosting/packs/{key} з токеном приймає name, authorName, authorUrl, iconUrl, webhookUrl. Умови продажу (paidOnly, requireKey, lockFiles, planCodes), увімкнення збірки модів на вітрині та прапорці запуску JVM не можна змінити токеном — це наша домовленість з вами та наші вузли, тож пишіть нам про них.

Оновлення збірки модів

Раніше оновлення означало лист нам і очікування. Тепер ви публікуєте версію самостійно, а власники серверів обирають її у своїй панелі.

Ключовий момент: ми ніколи не оновлюємо нікого мовчки. Перехід між версіями збірки модів може бути несумісним зі світом, і рішення ухвалює власник сервера. Опубліковану версію отримують нові сервери, і саме її ми пропонуємо вже розгорнутим; попередні версії залишаються у списку, і ви можете залишитися на них або відкотитися.

Як виглядає цикл

# 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"

Версія

Завантаження

POST /v2/hosting/packs/{key}/versions/{label}/archive?offset=N, тіло — фрагмент .zip, Content-Type: application/octet-stream. Фрагмент до 32 МБ, весь архів до 4 ГБ.

Фрагмент адресується за offset, а не «дописати в кінець»: фрагмент, перерваний на середині, уже частково ліг у файл, і повторна спроба допише ті самі байти вдруге — архів прийде непомітно пошкодженим. У відповіді повертається uploadedBytes, за яким завантаження продовжують після переривання.

Розпакування

POST .../finish відповідає одразу (status: "processing"), а розпакування виконується у фоні: розпакування конфігурації сервера розміром у гігабайт займає хвилини. Стан читайте з GET .../versions/{label}: processing → ready або failed з текстом причини в error.

Що архів має пройти:

• це серверний набір: після видалення єдиної обгортки (Server Files/ та подібних) mods/ або plugins/ лежить у корені. Клієнтський набір на сервері дає порожній світ, тому ми його відхиляємо, а не встановлюємо;
• жодних .., абсолютних шляхів чи Windows-роздільників у назвах усередині архіву;
• без пароля, без екзотичних методів стиснення (лише store та deflate);
• обмеження: 60 000 файлів, 12 ГБ у розпакованому вигляді, коефіцієнт стиснення до 200×.

Невдача не впливає на опубліковану версію: ваші клієнти далі працюють на попередній, а ви завантажуєте знову. Незавершені чернетки: не більше трьох на конфігурацію сервера, занедбані прибираються автоматично за добу.

Публікація, відкат і видалення

Публікація переносить ядро, версію гри, фіксацію завантажувача, Java та мінімум пам'яті версії в картку конфігурації сервера: нові сервери отримують це без жодних додаткових дій з вашого боку.

Що бачить власник сервера

У панелі, в блоці преміум-конфігурації сервера: яка версія встановлена, яка випущена, ваш changelog і список версій з кнопкою «Перемкнути». Оновлення не впливає на світ — замінюються лише файли конфігурації сервера, і перед заміною ми робимо копію. Власні моди, якщо ви їх дозволили, доведеться додати знову після перемикання: конфігурація сервера переміщується як єдине ціле, а половина старої версії в mods/ означає краш під час запуску.

Якщо тариф власника не витримує версію, ми показуємо її з причиною, а не ховаємо: людина має бачити, що їй потрібно, а не здогадуватися, чому конфігурація сервера не оновлюється.

Ваша власна сторінка конфігурації сервера

Ви будуєте лендінг для своєї конфігурації сервера самі у своєму акаунті (профіль → «Мої конфігурації серверів» → «Сторінки конфігурацій серверів»): перший екран, можливості, скриншоти, питання й відповіді, ваші кольори. Тарифи та список версій наповнюються нашими даними, щоб не застарівати.

Готова сторінка живе за адресою millida.net/sborka/<your-address> — звичайна сторінка сайту, яку індексують пошукові системи й включено до нашої карти сайту. Чернетку не бачить ніхто, крім вас.

Зображення завантажуються там само, у вашому акаунті: сторінка віддається з нашого домену, а її файли зберігаються в нас — якщо ваш хостинг впаде, сторінка залишиться цілою.

Сторінки не можна редагувати через API: це екран, а не розгортання.

Коди відповідей

Як усе перевірити перед продажем

Попросіть у нас кілька тестових кодів: видайте код через API, активуйте його на своєму сервері на нашому хостингу, подивіться, що прийшло у вебхук і що показує keys/status. Так ви побачите весь шлях покупця, перш ніж його пройде перший платний клієнт.