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

# Przegląd API

> Bazowy URL, uwierzytelnianie i konwencje API reference.

Strony w tej zakładce są generowane z [specyfikacji OpenAPI](https://github.com/andczey/itemshop-v2). Każdy endpoint ma interaktywny formularz „Wypróbuj".

## Bazowy URL

```text theme={null}
https://api.itemshop.dev/api/v2
```

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

## Uwierzytelnianie

Endpoint może wymagać sesji `bearerAuth`, klucza sklepu `apiKeyAuth`, akceptować oba mechanizmy albo być publiczny. Dla klucza:

```http theme={null}
X-API-Key: <klucz-sklepu>
```

Jeśli endpoint dopuszcza klucz i żądanie zawiera oba mechanizmy, sprawdzany jest klucz. Zwykła trasa Bearer ignoruje klucz i używa sesji. Szczegóły: [Uwierzytelnianie](/pl/guides/authentication).

## Konwencje odpowiedzi

Sukces ma kształt `{ success: true, data, message? }`, błąd `{ success: false, statusCode, error, timestamp, path }`. Zawsze sprawdzaj pole `success`. Zobacz [Obsługę błędów](/pl/guides/errors).

## Identyfikatory

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

## Endpointy publiczne

Część endpointów nie wymaga uwierzytelnienia: tworzenie zamówienia, publiczne katalogi, realizacja vouchera, walidacja kodu rabatowego oraz webhooki płatności. W API reference mają oznaczenie braku zabezpieczeń.