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

# Masowe tworzenie kodów QR

> Twórz do 100 kodów QR naraz i pobieraj je jako archiwum ZIP.

> [!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ą.

Masowe tworzenie zamienia listę nazw i adresów URL w kody QR typu Website ze wspólnym projektem. Działa w tle: uruchom je, odpytuj o postęp, a potem pobierz archiwum ZIP.

| Metoda | Ścieżka | Opis |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [Bieżące masowe tworzenie](#bieżące-masowe-tworzenie) |
| `POST` | `/api/v1/bulk-qr-creations` | [Tworzenie z JSON](#tworzenie-z-json) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [Tworzenie z pliku CSV](#tworzenie-z-pliku-csv) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [Odczyt masowego tworzenia](#odczyt-masowego-tworzenia) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Przerywanie masowego tworzenia](#przerywanie-masowego-tworzenia) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Pobieranie archiwum](#pobieranie-archiwum) |

## Jak to działa

**1. Uruchom masowe tworzenie**

Wyślij wiersze przez [tworzenie z JSON](#tworzenie-z-json) lub [tworzenie z pliku CSV](#tworzenie-z-pliku-csv). API odpowiada `202` i zwraca masowe tworzenie z jego `id`.

**2. Odpytuj o postęp**

Co kilka sekund wywołuj [odczyt masowego tworzenia](#odczyt-masowego-tworzenia), aż `status` będzie miał wartość `completed` lub `failed`.

**3. Pobierz archiwum**

Gdy `status` ma wartość `completed`, wywołaj [pobieranie archiwum](#pobieranie-archiwum), aby otrzymać plik ZIP z obrazami kodów QR.

* **Limit.** Do 100 wierszy na jedno masowe tworzenie.
* **Jedno naraz.** W obszarze roboczym działa naraz tylko jedno masowe tworzenie. Próba uruchomienia kolejnego, gdy jedno trwa, zwraca to, które trwa.
* **Idempotentność.** Każde żądanie wymaga `idempotencyKey`. Powtórzenie żądania z tym samym kluczem i tą samą treścią zwraca już uruchomione masowe tworzenie. Ten sam klucz z inną treścią zwraca `422`.
* **Wiersze.** Każdy wiersz wymaga `name` i `url`. Zobacz [Wiersze](#wiersze).
* **Plan.** Masowe tworzenie nie jest dostępne w planie Single QR: żądanie zwraca `403 exceeded_limit`.

## Wiersze

* **Nazwa.** Staje się tytułem kodu QR. Spacje na początku i końcu są usuwane, a nazwa jest obcinana do 40 znaków. Powtarzające się nazwy (bez względu na wielkość liter) dostają numer: `Menu`, `Menu 2`, `Menu 3`.
* **URL.** Staje się celem. Musi to być adres `http` lub `https` z prawdziwą domeną, np. `example.com/menu`, bez spacji. Adres URL bez schematu dostaje `https://`.
* **Puste wiersze.** Wiersze bez nazwy i bez adresu URL są pomijane. Wiersz z tylko jedną z tych wartości jest odrzucany.

Każdy kod QR jest kodem QR typu `website` z krótkim linkiem. Zobacz [Typy kodów QR](https://docs.getqr.com/pl/api/guides/qr-types.md).

## Nagłówki

**Authorization** `string` *required*

`Bearer`, a po nim Twój klucz API. Zobacz [Uwierzytelnianie](https://docs.getqr.com/pl/api/authentication.md).

**Content-Type** `string`

`application/json` dla [tworzenia z JSON](#tworzenie-z-json), `multipart/form-data` dla [tworzenia z pliku CSV](#tworzenie-z-pliku-csv).

## Obiekt masowego tworzenia

**id** `string`

ID masowego tworzenia, np. `cm2k7x9qb0003ax8eb4f6gh2t`.

**status** `string`

`queued`, `processing`, `packaging` lub `completed`. Nieudane lub przerwane masowe tworzenie przechodzi przez `rollingBack` do `failed`.

**sourceFilename** `string`

Nazwa pliku źródłowego.

**totalCount** `integer`

Liczba wierszy.

**createdCount** `integer`

Liczba kodów QR utworzonych do tej pory.

**renderedCount** `integer`

Liczba obrazów kodów QR wyrenderowanych do tej pory.

**percent** `integer`

Ogólny postęp, od 0 do 100. Tworzenie zajmuje do 40, renderowanie do 90, pakowanie to 95, a `completed` to 100.

**stalled** `boolean`

`true`, gdy trwające masowe tworzenie nie zrobiło postępu przez 2 minuty. Odpytuj dalej: [odczyt masowego tworzenia](#odczyt-masowego-tworzenia) wznawia zablokowane masowe tworzenie.

**error** `object | null`

Gdy `status` ma wartość `failed`: `code` i `message`. Przerwane masowe tworzenie ma kod `cancelled_by_user`. Nieudane masowe tworzenie jest wycofywane, więc żaden z jego kodów QR nie zostaje zachowany.

**downloadUrl** `string | null`

Ścieżka do [pobierania archiwum](#pobieranie-archiwum), gdy `status` ma wartość `completed`.

**createdAt** `string`

Data rozpoczęcia, ISO 8601.

**updatedAt** `string`

Data ostatniej aktualizacji, ISO 8601.

**completedAt** `string | null`

Data zakończenia, ISO 8601.

**failedAt** `string | null`

Data niepowodzenia, ISO 8601.

## Bieżące masowe tworzenie

`GET /api/v1/bulk-qr-creations`

Zwraca masowe tworzenie, które wciąż trwa w Twoim obszarze roboczym. Gdy żadne nie trwa, zwraca ostatnie zakończone (`completed` lub `failed`), dopóki nie zostanie zamknięte: robi to pobranie jego archiwum lub zamknięcie go w panelu. W przeciwnym razie zwraca `null`. Użyj go, aby wznowić śledzenie po ponownym uruchomieniu.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}
```

```json 200 (nothing to resume) theme={null}
null
```

## Tworzenie z JSON

`POST /api/v1/bulk-qr-creations`

Uruchamia masowe tworzenie z listy wierszy. Odpowiada `202 Accepted`. Masowe tworzenie działa w tle.

**rows** `object[]` *required*

Kody QR do utworzenia, do 100. Każdy wiersz to `{ "name": "...", "url": "..." }` i nie przyjmuje innych pól. Zobacz [Wiersze](#wiersze).

**design** `object` *required*

Projekt stosowany do każdego kodu QR: `styles`, `frameOptions` i `logoOptions`, wszystkie opcjonalne. Wyślij `{}` dla projektu domyślnego. Inne pola są odrzucane. Zobacz [Personalizacja](https://docs.getqr.com/pl/api/guides/customization.md).

**sourceFilename** `string` *required*

Nazwa wyświetlana w panelu i używana dla archiwum, od 1 do 255 znaków.

**idempotencyKey** `string` *required*

Twój własny klucz dla tego masowego tworzenia, od 8 do 100 znaków.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## Tworzenie z pliku CSV

`POST /api/v1/bulk-qr-creations/csv`

Działa tak samo jak [tworzenie z JSON](#tworzenie-z-json), ale przyjmuje wiersze jako plik CSV wysłany jako `multipart/form-data`. Odpowiada `202 Accepted`.

Plik musi mieć format `.csv` i rozmiar najwyżej 1 000 000 bajtów. Jego wiersz nagłówka musi mieć dokładnie postać `name,url`, a po nim może być do 100 wierszy danych. Zobacz [Format CSV](https://docs.getqr.com/pl/bulk/csv-format.md).

**file** `file` *required*

Plik CSV.

**design** `string` *required*

Obiekt projektu zserializowany do JSON, np. `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Wyślij `{}` dla projektu domyślnego.

**idempotencyKey** `string` *required*

Twój własny klucz dla tego masowego tworzenia, od 8 do 100 znaków.

**sourceFilename** `string`

Nazwa wyświetlana w panelu i używana dla archiwum, do 255 znaków. Domyślnie nazwa przesłanego pliku.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "file=@campaign-links.csv" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"
```

```csv campaign-links.csv theme={null}
name,url
Menu,https://example.com/menu
Wine list,example.com/wine
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## Odczyt masowego tworzenia

`GET /api/v1/bulk-qr-creations/{id}`

Zwraca status i postęp masowego tworzenia. Odpytuj ten endpoint, dopóki `status` ma wartość `queued`, `processing` lub `packaging`. `downloadUrl` pojawia się, gdy archiwum jest gotowe.

**id** `string` *required*

ID masowego tworzenia. Weź je z odpowiedzi tworzenia lub odczytu bieżącego masowego tworzenia.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}
```

## Przerywanie masowego tworzenia

`DELETE /api/v1/bulk-qr-creations/{id}`

Zatrzymuje trwające masowe tworzenie i usuwa kody QR, które już utworzyło. Wycofanie odbywa się w trakcie żądania, więc odpowiedź zwykle ma `status` równy `failed` i `error.code` równy `cancelled_by_user`. Przerwanie masowego tworzenia, które już się nie powiodło, zwraca je bez zmian.

> [!WARNING]
>
> Zakończonego masowego tworzenia nie można przerwać: żądanie zwraca `400`. Zamiast tego usuń jego kody QR pojedynczo przez [Kody QR](https://docs.getqr.com/pl/api/endpoints/qr-codes.md).

**id** `string` *required*

ID masowego tworzenia.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}
```

## Pobieranie archiwum

`GET /api/v1/bulk-qr-creations/{id}/download`

Zwraca archiwum ZIP z jednym plikiem JPEG 1024 px na każdy kod QR, nazwanym według wiersza: `001-Menu.jpg`, `002-Wine list.jpg` i tak dalej. Nazwa archiwum pochodzi od `sourceFilename`. Dostępne, gdy `status` ma wartość `completed`. Pobranie zamyka masowe tworzenie, więc [bieżące masowe tworzenie](#bieżące-masowe-tworzenie) przestaje je zwracać.

**id** `string` *required*

ID masowego tworzenia.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>
```

## Typowe problemy

> [accordion] 422 z komunikatem "contains an invalid HTTP(S) URL"
>
> Komunikat wskazuje wiersz. Każdy adres URL musi być adresem `http` lub `https` z prawdziwą domeną, np. `example.com/menu`. Popraw wiersz i wyślij żądanie ponownie.

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> Pierwszy wiersz pliku CSV musi mieć postać `name,url`, w tej kolejności i małymi literami, bez innych kolumn.

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> Kluczy nie można ponownie używać dla innej partii. Wyślij nowy `idempotencyKey`.

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> Masowe tworzenie jeszcze się nie zakończyło. Odpytuj dalej, aż `status` będzie miał wartość `completed`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> Masowe tworzenie już się zakończyło, więc nie można go wycofać.

> [accordion] 403 exceeded\_limit
>
> Twój obszar roboczy jest w planie Single QR, który nie obejmuje masowego tworzenia. Zmień plan na wyższy.

> [accordion] Otrzymałem starsze masowe tworzenie zamiast nowego
>
> W Twoim obszarze roboczym wciąż trwa inne masowe tworzenie albo ponownie użyłeś `idempotencyKey`. Poczekaj, aż się zakończy, lub użyj nowego klucza.

## Co dalej

> [card] [Personalizacja](https://docs.getqr.com/pl/api/guides/customization.md)

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

> [card] [Masowe tworzenie w aplikacji](https://docs.getqr.com/pl/bulk/overview.md)

> [card] [Format CSV](https://docs.getqr.com/pl/bulk/csv-format.md)


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