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

# Wprowadzenie

> ItemShop v2 — API platformy sprzedaży przedmiotów dla serwerów Minecraft.

ItemShop v2 to API platformy, na której właściciele serwerów Minecraft prowadzą sklepy z przedmiotami. Jeden użytkownik może mieć wiele sklepów, każdy sklep wiele serwerów, a klienci kupują produkty i otrzymują je w grze przez wtyczkę.

API jest zbudowane na **NestJS 11** z adapterem **Fastify 5**. Wszystkie ścieżki mają prefiks `/api/v2`.

## Główne pojęcia

<Columns cols={2}>
  <Card title="Sklep (shop)" icon="store">
    Jednostka organizacyjna. Ma właściciela, przypisanych użytkowników z rolami (`view`/`edit`/`full`), własną konfigurację płatności, VAT, e-maili i Discorda.
  </Card>

  <Card title="Serwer (server)" icon="server">
    Serwer Minecraft powiązany ze sklepem. Produkty przypisuje się do serwera; plugin odbiera dla niego dostawy w czasie rzeczywistym.
  </Card>

  <Card title="Produkt (product)" icon="box">
    Pozycja w katalogu z ceną i listą komend do wykonania (z placeholderami `{PLAYER}`, `{QUANTITY}`, `{PRODUCT}`).
  </Card>

  <Card title="Zamówienie (order)" icon="receipt">
    Tworzone publicznie przez klienta. Generuje sesję płatności; po opłaceniu trafia do realizacji przez wtyczkę.
  </Card>
</Columns>

## Cykl życia zamówienia

<Steps>
  <Step title="Utworzenie">
    Klient wysyła `POST /orders` z produktem, nickiem i metodą płatności. API tworzy zamówienie i sesję płatności, zwraca link do płatności.
  </Step>

  <Step title="Płatność">
    Klient płaci u dostawcy. Dostawca wysyła webhook na `POST /payments/webhooks/...`. Po weryfikacji podpisu zamówienie przechodzi w status `paid`.
  </Step>

  <Step title="Realizacja">
    Plugin Minecraft odbiera push Socket.IO, wygrywa atomowy claim, zapisuje journal, wykonuje sformatowane komendy i potwierdza realizację (`status` → `completed`).
  </Step>
</Steps>

## Co dalej

<Columns cols={2}>
  <Card title="Szybki start" icon="rocket" href="/pl/quickstart">
    Pierwsze żądania: rejestracja, sklep, produkt, zamówienie.
  </Card>

  <Card title="Architektura" icon="sitemap" href="/pl/guides/architecture">
    Struktura modułów, warstwy, integracje (Redis, kolejki, WebSocket).
  </Card>

  <Card title="Uwierzytelnianie" icon="key" href="/pl/guides/authentication">
    Klucze API, uprawnienia i role.
  </Card>

  <Card title="API Reference" icon="code" href="/pl/api-reference/overview">
    Pełna lista endpointów wygenerowana z OpenAPI.
  </Card>
</Columns>