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

# Zamówienia

> Bezpieczne tworzenie zamówień, statusy i zmiana nicku.

Zamówienie może utworzyć klient bez konta. Najbezpieczniejszą integracją jest gotowy checkout sklepu: pokazuje aktualne dokumenty prawne, zbiera wymagane zgody, generuje klucz idempotencji i token Turnstile.

## Tworzenie

Jeśli budujesz własny checkout, najpierw pobierz aktualny storefront i wyświetl klientowi dokumenty wskazane przez sklep. Następnie wyślij dokładnie ich `legalDocumentVersion` wraz z trzema świadomymi zgodami:

```bash theme={null}
curl -X POST https://api.itemshop.dev/api/v2/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <losowy-ciag-32-128-znakow>" \
  -H "cf-turnstile-response: <token-z-widgetu>" \
  -d '{
    "productId": "<productId>",
    "nickname": "Steve",
    "paymentMethodName": "imojeTransfer:blik",
    "email": "klient@example.com",
    "quantity": 1,
    "termsAccepted": true,
    "immediatePerformanceConsent": true,
    "withdrawalAcknowledged": true,
    "legalDocumentVersion": "<64-znakowy-skrot-SHA-256-pokazanych-dokumentow>"
  }'
```

Ten sam `Idempotency-Key` wolno ponowić tylko z identycznym żądaniem. Nowa próba zakupu musi dostać nowy losowy klucz. W produkcji brak tokenu Turnstile albo niezgodna/nieaktualna wersja dokumentów blokuje checkout.

Odpowiedź gościa zawiera ograniczone dane, `redirectUrl`, `orderId` oraz niejawny `statusToken`. Zapisz token wyłącznie po stronie klienta potrzebującego śledzić to zamówienie; nie umieszczaj go w logach ani publicznym URL-u.

## Statusy

| Status       | Znaczenie                                   |
| ------------ | ------------------------------------------- |
| `pending`    | Utworzone, oczekuje na płatność             |
| `paid`       | Opłacone, gotowe do realizacji przez plugin |
| `processing` | Plugin rozpoczął realizację                 |
| `completed`  | Plugin potwierdził realizację               |
| `cancelled`  | Anulowane                                   |
| `failed`     | Płatność nieudana                           |
| `dispute`    | Spór                                        |

Klient odczytuje ograniczony status przez `GET /orders/public/{orderId}/status`, przekazując capability zwrócone przez checkout:

```bash theme={null}
curl https://api.itemshop.dev/api/v2/orders/public/<orderId>/status \
  -H "x-order-status-token: <statusToken>"
```

`GET /orders/payment-status/{orderId}` zwraca więcej danych operatora i dlatego wymaga sesji Bearer użytkownika mającego dostęp do sklepu.

## Zmiana statusu (panel lub integracja)

Użytkownik z dostępem albo klucz sklepu z `orders:write` może zmienić status ręcznie:

```bash theme={null}
curl -X PUT https://api.itemshop.dev/api/v2/orders/<shopId>/orders/<orderId>/status \
  -H "X-API-Key: <klucz-sklepu>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "reason": "Zrealizowano ręcznie" }'
```

## Zmiana nicku

Klient może zmienić nick przed zakończeniem realizacji, potwierdzając kod wysłany na e-mail przypisany do zamówienia:

<Steps>
  <Step title="Żądanie kodu">
    `POST /orders/public/{orderId}/nickname/request-change` z e-mailem zgodnym z zamówieniem. API wysyła 6-cyfrowy kod ważny 10 minut.
  </Step>

  <Step title="Potwierdzenie">
    `POST /orders/public/{orderId}/nickname/change` z kodem i nowym nickiem. Po weryfikacji nick zostaje zmieniony, a poprzedni zapisany w historii.
  </Step>
</Steps>