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:

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": "[e-mail]",
    "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:

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:

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:

1. Żą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.

2. Potwierdzenie

   POST /orders/public/{orderId}/nickname/change z kodem i nowym nickiem. Po weryfikacji nick zostaje zmieniony, a poprzedni zapisany w historii.