> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Minecraft

> Zainstaluj i skonfiguruj plugin, który automatycznie wydaje zakupy na Twoim serwerze.

Plugin łączy serwer gry ze sklepem i wykonuje komendy opłaconych zamówień — bez Twojego udziału. Łączy się sam, szyfrowanym połączeniem wychodzącym, więc nie otwierasz żadnego portu. Gdy serwer był offline, zaległe dostawy są nadrabiane po ponownym połączeniu.

## Wymagania

* Java 17 lub nowsza,
* Paper/Spigot 1.19+, Folia, BungeeCord albo Velocity 3.x,
* serwer dodany w panelu (zobacz [Serwery](https://andcze.mintlify.site/pl/shop/servers.md)),
* prawo zapisu w folderze `plugins/ItemShop/` (konfiguracja i dziennik realizacji).

## Zainstaluj plugin

**1. Pobierz plugin**

W sekcji **Plugin** w panelu pobierz uniwersalny plik JAR i umieść go w folderze `plugins/`. Nie instaluj jednocześnie kilku wariantów pluginu.

**2. Wygeneruj klucz i konfigurację**

Wybierz serwer i kliknij **Wygeneruj klucz pluginu**, a potem skopiuj lub pobierz gotowy `config.yml`. Klucz jest widoczny tylko raz — jeśli go zgubisz, wygeneruj nowy.

**3. Wgraj konfigurację**

Zapisz plik jako `plugins/ItemShop/config.yml` i uruchom serwer.

**4. Sprawdź połączenie**

Komenda `/itemshop` pokazuje stan połączenia. W panelu serwer powinien zmienić się na **online**.

> [!WARNING]
>
> Wygeneruj klucz **przed** skopiowaniem pliku. Plik bez klucza zawiera `WKLEJ_TUTAJ_KLUCZ` w miejscu klucza i nie zadziała.

Jedna konfiguracja dotyczy **jednego serwera**. Masz kilka serwerów — wygeneruj osobny `config.yml` dla każdego. Po zmianach serwerów w panelu wygeneruj plik ponownie.

## Konfiguracja

Generator wypełnia wszystko za Ciebie. Przykładowy plik:

```yaml config.yml theme={null}
apiUrl: "https://itemshop.dev"
apiKey: "isk_..."
serverId: "..."
joinDeliveryDelaySeconds: 2
blockedCommands:
  - op
  - deop
  - stop
  - restart
  - reload
  - whitelist
blockedServers:
  - auth
  - login
playersUpdateIntervalSeconds: 30
sendPlayerNames: true
debug: false
```

| Pole | Znaczenie |
| - | - |
| `apiUrl` | adres ItemShop — bez `/api/v2` i bez ścieżki; w produkcji zawsze `https://` |
| `apiKey` | klucz pluginu (zaczyna się od `isk_`) |
| `serverId` | identyfikator jednego serwera z panelu |
| `joinDeliveryDelaySeconds` | opóźnienie dostawy po wejściu gracza na serwer |
| `blockedCommands` | komendy, których plugin nigdy nie wykona, nawet jeśli są w produkcie |
| `blockedServers` | tryby za proxy, na których dostawa czeka (np. lobby logowania) |
| `playersUpdateIntervalSeconds` | jak często plugin wysyła liczbę graczy online |
| `sendPlayerNames` | czy wysyłać też listę nicków (liczba graczy jest wysyłana zawsze) |
| `debug` | szczegółowe logi — włączaj tylko na czas diagnozy |

Zmiany w pliku wczytasz komendą `/itemshop reload`. Nie używaj globalnego `/reload` serwera — może zostawić plugin w niespójnym stanie.

## Bezpieczeństwo

* Klucz pluginu działa tylko w zakresie realizacji zamówień Twojego sklepu, ale traktuj go jak hasło: nie publikuj `config.yml`, nie wrzucaj go do repozytorium ani zgłoszeń pomocy.
* Jeśli klucz mógł wyciec, wygeneruj nowy, a stary usuń w kluczach API (zobacz [Klucze API](https://andcze.mintlify.site/pl/developers/api-keys.md)).
* Nie usuwaj pliku `fulfillment-journal.json` w folderze pluginu — bez niego nie da się bezpiecznie rozstrzygnąć dostawy przerwanej awarią.

## Jak przebiega dostawa

Opłacone zamówienie trafia do pluginu od razu. Jeśli kilka instancji jest połączonych, komendy wykona tylko jedna. Przed pierwszą komendą plugin zapisuje stan na dysku, więc po awarii wie, na czym skończył:

* jeśli wszystkie komendy się wykonały, plugin po restarcie tylko potwierdza realizację — nie powtarza komend,
* jeśli serwer padł **w trakcie** wykonywania komend, wynik jest niepewny. Zamówienie trafia wtedy do ręcznej weryfikacji, a Ty decydujesz: **zrealizowane** albo **ponów** (zobacz [Zamówienia](https://andcze.mintlify.site/pl/shop/orders.md)).

To celowy wybór: lepiej poprosić Cię o decyzję niż ryzykować podwójne wydanie produktu. Szczegóły techniczne opisuje [protokół pluginu](https://andcze.mintlify.site/pl/developers/plugin-protocol.md).

## Przetestuj przed sprzedażą

1. Utwórz produkt z niegroźną komendą testową, np. `say Test {PLAYER}`.
2. Kup go z kodem rabatowym 100% — nie angażujesz wtedy operatora płatności.
3. Sprawdź `/itemshop`, log serwera i zmianę statusu: **opłacone** → **przetwarzanie** → **zrealizowane**.
4. Powtórz z graczem offline, po wejściu gracza i po restarcie serwera przed dostawą.
5. Osobno przetestuj prawdziwego operatora w trybie testowym (zobacz [Płatności](https://andcze.mintlify.site/pl/shop/payments.md)).

## Diagnostyka

> **Plugin zgłasza brak konfiguracji**
>
> Sprawdź dokładne nazwy pól: `apiUrl`, `apiKey`, `serverId`. Klucz musi zaczynać się od `isk_`, a `apiUrl` nie może kończyć się na `/api/v2`.

> **Połączenie jest odrzucane (unauthorized)**
>
> Wygeneruj nowy klucz w sekcji **Plugin**. Klucz musi być aktywny i należeć do tego samego sklepu co `serverId`.

> **Zamówienie czeka na gracza**
>
> Sprawdź pisownię nicku, przełącznik **Wymagaj gracza online** i listę `blockedServers`. Wejście gracza lub zmiana trybu uruchamia dostawę zaległości po `joinDeliveryDelaySeconds`.

> **Zamówienie wymaga ręcznej weryfikacji**
>
> Plugin wykrył przerwaną dostawę — część komend mogła się wykonać. Najpierw sprawdź stan gracza i logi serwera, potem wybierz w panelu **zrealizowane** albo **ponów**.

> **Serwer jest offline w panelu**
>
> Plugin nie wysłał sygnału od ponad 5 minut. Sprawdź `/itemshop`, log serwera i czy serwer ma dostęp do internetu. Zamówienia poczekają do ponownego połączenia.

## Dalej

> **[Serwery](https://andcze.mintlify.site/pl/shop/servers.md)**
>
> Funkcje serwera i status online.

> **[Protokół pluginu](https://andcze.mintlify.site/pl/developers/plugin-protocol.md)**
>
> Techniczny opis komunikacji pluginu ze sklepem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.