Przegląd API

Bazowy URL, uwierzytelnianie, stronicowanie i konwencje referencji API generowanej z OpenAPI.

Strony w tej zakładce są generowane ze specyfikacji OpenAPI: osobnej dla Storefront API v1 (publiczne, bez klucza) i dla API sklepu (klucz lub sesja). Każdy endpoint ma interaktywny formularz „Wypróbuj”. Referencja obejmuje publiczne API — trasy wewnętrzne panelu (logowanie, asystent AI, rozliczenia) nie są w niej publikowane.

​

Bazowy URL

https://itemshop.dev/api/v2

Lokalnie: http://localhost:3000/api/v2. Wszystkie ścieżki mają prefiks /api/v2.

​

Które API do czego

API	Uwierzytelnianie	Do czego
Storefront API v1 (/storefront/v1/..., od 3.0)	brak — publiczne, CORS, cache	dane strony sklepu w przeglądarce: sklep, produkty, metody płatności, kasa, status zamówienia, widżety. Zobacz Storefront API.
API sklepu (ta referencja)	X-API-Key (apiKeyAuth)	integracje serwerowe: produkty, zamówienia, rabaty, vouchery, statystyki, zespół, od 3.0 także pliki i publikacje strony
trasy panelu	sesja Authorization: Bearer (bearerAuth)	konto, tworzenie sklepu, zarządzanie kluczami, akcje tylko dla właściciela

​

Uwierzytelnianie

Endpoint może wymagać bearerAuth, apiKeyAuth, akceptować oba albo być publiczny — każda strona referencji to pokazuje. Dla integracji używaj klucza sklepu:

X-API-Key: isk_<64 znaki hex>

Jeśli endpoint dopuszcza klucz, a żądanie zawiera oba mechanizmy, sprawdzany jest klucz. Zwykła trasa Bearer ignoruje klucz i używa sesji. Tworzenie kluczy i zakresy: API z kluczem.

Publiczne (bez uwierzytelnienia) są m.in.: tworzenie zamówienia, publiczne katalogi sklepu, realizacja vouchera, walidacja kodu rabatowego, status zamówienia i webhooki operatorów płatności. Publiczne nie znaczy bez ograniczeń — obowiązują walidacja, limity żądań, a w kasie także zgody, wersja dokumentów, Idempotency-Key i Turnstile.

​

Konwencje odpowiedzi

Sukces: { success: true, data, message? }. Błąd: { success: false, statusCode, error, code?, details?, timestamp, path }. Zawsze sprawdzaj pole success. Kody i ponawianie: Błędy i limity.

​

Identyfikatory

Identyfikatory zasobów (shopId, serverId, orderId, …) to MongoDB ObjectId — 24 znaki hex (^[0-9a-fA-F]{24}$). Nieprawidłowy format zwraca 400.

​

Stronicowanie i limity

Listy przyjmują page (od 1) i limit. Odpowiedź stronicowana zawiera data, total, page, pages, hasNext i hasPrev. limit jest przycinany do bezpiecznego maksimum (zwykle 100; listy statystyk mają własne, niższe progi). Przykład:

curl "https://itemshop.dev/api/v2/orders/<shopId>?status=paid&page=2&limit=50" \
  -H "X-API-Key: $ITEMSHOP_API_KEY"

Globalny limit to 200 żądań na minutę per IP, a wrażliwe trasy mają ostrzejsze okna — szczegóły w Błędy i limity.

​

Dalej

API z kluczem

Utwórz klucz i wyślij pierwsze żądanie.

Storefront API

Publiczne dane sklepu dla Twojej strony.