> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wprowadzenie do API

> Zarządzaj kodami QR, szablonami, analityką i raportami z poziomu własnego kodu.

> [!NOTE]
>
> API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.

API GetQR to REST API do tego, co robisz w panelu: tworzenia i aktualizowania kodów QR, pobierania ich obrazów, odczytu analityki skanowań i eksportu raportów. Uwierzytelniaj się kluczem API swojego konta i wywołuj wersjonowane endpointy pod `/api/v1`.

## Co możesz zrobić

> [card] [Kody QR](https://docs.getqr.com/pl/api/endpoints/qr-codes.md)
>
> Twórz, wyświetlaj, aktualizuj, wstrzymuj, duplikuj, usuwaj i pobieraj kody QR.

> [card] [Analityka](https://docs.getqr.com/pl/api/endpoints/analytics.md)
>
> Łączna liczba skanowań i podziały dla jednego kodu QR lub całego obszaru roboczego.

> [card] [Raporty](https://docs.getqr.com/pl/api/endpoints/reports.md)
>
> Eksportuj jednorazowy raport lub zaplanuj cykliczne raporty e-mailem.

> [card] [Szablony](https://docs.getqr.com/pl/api/endpoints/templates.md)
>
> Zapisuj projekty i stosuj je do nowych kodów QR.

> [card] [Masowe tworzenie kodów QR](https://docs.getqr.com/pl/api/endpoints/bulk-qr-creations.md)
>
> Twórz do 100 kodów QR naraz z JSON lub pliku CSV.

> [card] [Pliki](https://docs.getqr.com/pl/api/endpoints/files.md)
>
> Przesyłaj pliki PDF, obrazy, filmy i logo do swoich kodów QR.

> [card] [Stan API](https://docs.getqr.com/pl/api/endpoints/health.md)
>
> Sprawdź, czy API działa. Klucz API nie jest potrzebny.

## Przewodniki

> [card] [Typy kodów QR](https://docs.getqr.com/pl/api/guides/qr-types.md)
>
> Format danych dla każdego z 16 typów kodów QR.

> [card] [Personalizacja](https://docs.getqr.com/pl/api/guides/customization.md)
>
> Style kropek, narożniki, kolory, ramki i logo.

> [card] [Reguły dostępu](https://docs.getqr.com/pl/api/guides/access-rules.md)
>
> Harmonogramy, limity skanowań, hasła, wstrzymywanie i usuwanie.

## Bazowy URL

Wszystkie endpointy znajdują się pod jednym bazowym adresem URL:

```text theme={null}
https://getqr.com/api/v1
```

## Wersjonowanie

Wersja API jest częścią ścieżki: każdy endpoint znajduje się pod `/api/v1/`.

* Zmiany niezgodne wstecz trafiają pod nowy prefiks wersji, np. `/api/v2/`, a `/api/v1/` działa dalej.
* Zmiany zgodne wstecz, takie jak nowe pola opcjonalne czy nowe endpointy, mogą pojawiać się w v1. Ignoruj pola odpowiedzi, których Twój kod nie rozpoznaje.

## Szybki start

**1. Zdobądź klucz API**

Wygeneruj lub wyświetl swój klucz w ustawieniach konta. Zobacz [Uwierzytelnianie](https://docs.getqr.com/pl/api/authentication.md).

**2. Sprawdź, czy API jest osiągalne**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

Odpowiedź to `{ "status": "ok", "version": "v1" }`.

**3. Utwórz pierwszy kod QR**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API odpowiada kodem `201` i zwraca nowy kod QR, w tym jego `id` i `shortLink`.

**4. Pobierz obraz**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Żądania i odpowiedzi

* **Format.** Wysyłaj treść żądania jako JSON z nagłówkiem `Content-Type: application/json`. Wyjątkiem jest przesyłanie pliku CSV przy [masowym tworzeniu](https://docs.getqr.com/pl/api/endpoints/bulk-qr-creations.md), które używa `multipart/form-data`.
* **Odpowiedzi.** Odpowiedzi są w formacie JSON. Pobierane pliki, takie jak obrazy kodów QR i archiwa ZIP z masowego tworzenia, są zwracane bezpośrednio jako plik.
* **Daty.** Daty to ciągi ISO 8601 w UTC, np. `2026-08-01T10:00:00.000Z`.
* **Parametry zapytania.** Parametry logiczne przyjmują ciągi `true` lub `false`.
* **Częściowe aktualizacje.** Endpointy `PATCH` zmieniają tylko wysłane pola.
* **Dane poufne.** Odpowiedzi nigdy nie zawierają haseł ani wewnętrznych identyfikatorów. Kod QR chroniony hasłem zwraca tylko `passwordProtected: true`.
* **Obszar roboczy.** Każde żądanie jest wykonywane w obszarze roboczym, do którego należy Twój klucz API. Nie podajesz ID obszaru roboczego. Zobacz [Dostęp i role](https://docs.getqr.com/pl/api/authentication.md#dostęp-i-role).
* **Błędy.** Nieudane żądania zwracają obiekt `error` ze stałym `code`. Zobacz [Błędy](https://docs.getqr.com/pl/api/errors.md).

## Paginacja

Endpointy list (kody QR, szablony i zaplanowane raporty) przyjmują dwa parametry zapytania:

| Parametr | Opis |
| - | - |
| `page` | Strona do zwrócenia. Domyślnie `1`. |
| `pageSize` | Liczba wyników na stronę, maksymalnie `100`. Domyślnie `100`. |

Odpowiadają tablicą `data` i obiektem `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Pole | Opis |
| - | - |
| `page` | Strona, którą otrzymałeś. |
| `pageSize` | Rozmiar strony, który otrzymałeś. |
| `total` | Liczba wyników na wszystkich stronach. |
| `hasMore` | `true`, dopóki czeka kolejna strona. |

Pobieraj kolejną stronę, dopóki `hasMore` ma wartość `true`. Wartość `pageSize` większa niż `100` zwraca [`422`](https://docs.getqr.com/pl/api/errors#błędy-walidacji).

## Idempotentność

Błąd sieci może sprawić, że nie wiesz, czy żądanie dotarło. Aby bezpiecznie ponowić [tworzenie kodu QR](https://docs.getqr.com/pl/api/endpoints/qr-codes.md#tworzenie-kodu-qr), wyślij nagłówek `Idempotency-Key` z wybraną przez siebie unikalną wartością:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Powtórzenie żądania z tym samym kluczem w ciągu 24 godzin zwraca pierwotną odpowiedź zamiast tworzyć drugi kod QR.
* Nagłówek odpowiedzi `x-idempotent-replay` ma wartość `true` dla odtworzonej odpowiedzi i `false` dla nowej.
* Jeśli pierwsze żądanie z tym kluczem wciąż trwa, API odpowiada `409 conflict`. Ponów żądanie, gdy się zakończy.
* Ponowne użycie klucza z inną treścią żądania zwraca `422 unprocessable_entity`.
* Bez tego nagłówka identyczna treść żądania wysłana w ciągu 30 sekund jest traktowana jako duplikat.

Masowe tworzenie przyjmuje zamiast tego pole `idempotencyKey` w treści żądania. Zobacz [Masowe tworzenie kodów QR](https://docs.getqr.com/pl/api/endpoints/bulk-qr-creations.md).

## Limity żądań

Każdy klucz API może wysłać do 600 żądań na minutę. Zobacz [Limity żądań](https://docs.getqr.com/pl/api/rate-limits.md).

## W przygotowaniu

Pakiety gotowe do druku są planowane w jednym z kolejnych wydań.

## Co dalej

> [card] [Uwierzytelnianie](https://docs.getqr.com/pl/api/authentication.md)

> [card] [Kody QR](https://docs.getqr.com/pl/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.