Синхронизация инвентаря (QXSync)

В разработке (coming soon)

Отдельный мод / плагин QXSync для сервера Minecraft находится в разработке и будет официальным клиентом для отправки снимков инвентаря в QMServer. Документ описывает целевой контракт: эндпоинт и настройки в экосистеме уже есть, ориентируйтесь на них при появлении релиза QXSync.

Условия работы QXSync на стороне QMServer — для одной сборки из репозитория QMServer: включены модуль «Игровой сервер Minecraft» и интеграция QMWeb. Иначе POST /api/v1/inventory отвечает 404 (detail про отключённый модуль или интеграцию).

Синхронизацию настраивают в QMAdmin (ключ API, вкл/выкл). QMLauncher и QMWeb сами POST /inventory не вызывают — только отображают сохранённые данные через API облака (лаунчер — при включённой интеграции QMLauncher).

Источник правды по контракту — эта страница. В репозитории QMServer файл INVENTORY_SYNC_API.md — короткая ссылка сюда.

Endpoint

POST {QMSERVER}/api/v1/inventory

Пример продакшена: https://api.qx-dev.ru/api/v1/inventory.

Авторизация

• Заголовок Authorization: Bearer <api_key> или
• X-API-Key: <api_key>

Ключ выдаёт администратор через QMAdmin (на бэкенде: POST /api/v1/settings/inventory-sync/generate-key). Публичные параметры sync (без секрета) читаются из GET /api/v1/settings/inventory-sync (используется QMWeb) — GET требует включённой интеграции QMWeb и модуля Minecraft.

Приём инвентаря с игрового сервера (POST /api/v1/inventory, QXSync) требует модуля Minecraft, интеграции QMWeb и валидного API-ключа (и включённой sync в настройках). При отключённой интеграции QMWeb — 404 с detail: QMWeb integration is disabled; при отключённом модуле Minecraft — 404 про модуль.

Идентификация сервера

В теле JSON поле serverId — UUID профиля сервера в QMServer (не ID в игре). UUID можно посмотреть:

• в интерактивном режиме QMServer (list);
• в QMLauncher при выборе сервера;
• в QMAdmin в списке серверов.

Если UUID не найден в базе QMServer, ответ 400.

Тело запроса (пример)

Формат ожидается от QXSync (итоговая схема может уточняться вместе с первым релизом мода):

{
  "serverId": "550e8400-e29b-41d4-a716-446655440000",
  "playerUuid": "игрок-uuid",
  "playerName": "Steve",
  "timestamp": 1739452800000,
  "main": [
    { "slot": 0, "item": "minecraft:diamond_sword", "count": 1, "nbt": "..." }
  ],
  "armor": [{ "slot": 0, "item": "minecraft:diamond_helmet", "count": 1 }],
  "offhand": { "slot": 0, "item": "minecraft:shield", "count": 1 }
}

Ответы

Код	Причина
200	Успех
400	Невалидный JSON, нет обязательных полей, неизвестный serverId
401	Нет ключа или неверный ключ
404	Выключены модуль Minecraft или интеграция QMWeb
503	Синхронизация инвентаря выключена в настройках (inventory_sync_enabled)

Конфигурация на стороне игрового сервера (план)

После выхода QXSync путь к файлу конфигурации и точные ключи будут задокументированы в репозитории мода. Ориентир для администраторов — те же параметры, что и раньше обсуждались для синхронизации: URL API, UUID профиля QMServer, ключ, интервал. Пример черновика (не финальное имя файла):

{
  "inventorySyncEnabled": true,
  "inventorySyncApiUrl": "https://api.qx-dev.ru/api/v1/inventory",
  "inventorySyncServerId": "uuid-профиля-из-QMServer",
  "inventorySyncApiKey": "секретный-ключ",
  "inventorySyncIntervalMinutes": 5
}

Связь с экосистемой

Компонент	Роль
QMServer	Приём POST, валидация ключа и UUID сервера, хранение
QMAdmin	Генерация ключа, вкл/выкл sync
QMWeb	Публичные настройки inventory-sync; без включённой интеграции QXSync на QMServer не принимает POST
QMLauncher	Показывает серверы и сохранённый инвентарь (при включённой интеграции); UUID профиля совпадает с тем, что передаёт QXSync
QXSync	Мод/плагин на игровом сервере — скоро; трафик только при Minecraft + QMWeb