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

# Масове створення QR-кодів

> Створюйте до 100 QR-кодів за раз і завантажуйте їх ZIP-архівом.

> [!NOTE]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

Масове створення перетворює список назв і URL на QR-коди Website зі спільним дизайном. Воно виконується у фоновому режимі: запустіть його, періодично перевіряйте прогрес, а потім завантажте ZIP-архів.

| Метод | Шлях | Опис |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [Отримання поточного масового створення](#отримання-поточного-масового-створення) |
| `POST` | `/api/v1/bulk-qr-creations` | [Створення з JSON](#створення-з-json) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [Створення з CSV-файлу](#створення-з-csv-файлу) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [Отримання масового створення](#отримання-масового-створення) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Скасування масового створення](#скасування-масового-створення) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Завантаження архіву](#завантаження-архіву) |

## Як це працює

**1. Запустіть масове створення**

Надішліть рядки через [Створення з JSON](#створення-з-json) або [Створення з CSV-файлу](#створення-з-csv-файлу). API відповідає `202` з масовим створенням і його `id`.

**2. Стежте за прогресом**

Викликайте [Отримання масового створення](#отримання-масового-створення) кожні кілька секунд, доки `status` не стане `completed` або `failed`.

**3. Завантажте архів**

Коли `status` дорівнює `completed`, викличте [Завантаження архіву](#завантаження-архіву), щоб отримати ZIP зі зображеннями QR-кодів.

* **Ліміт.** До 100 рядків на одне масове створення.
* **Одне за раз.** У робочому просторі одночасно виконується лише одне масове створення. Спроба запустити інше, поки одне виконується, повертає те, що вже виконується.
* **Ідемпотентність.** Кожен запит потребує `idempotencyKey`. Повторний запит із тим самим ключем і тим самим тілом повертає вже запущене масове створення. Той самий ключ з іншим тілом повертає `422`.
* **Рядки.** Кожен рядок потребує `name` і `url`. Див. [Рядки](#рядки).
* **Тарифний план.** Масове створення недоступне на плані Single QR: запит повертає `403 exceeded_limit`.

## Рядки

* **Назва.** Стає назвою QR-коду. Пробіли на краях обрізаються, довжина обмежується 40 символами. Повторювані назви (без урахування регістру) отримують номер: `Menu`, `Menu 2`, `Menu 3`.
* **URL.** Стає адресою призначення. Це має бути адреса `http` або `https` зі справжнім доменом, наприклад `example.com/menu`, без пробілів. До URL без схеми додається `https://`.
* **Порожні рядки.** Рядки без назви й без URL пропускаються. Рядок лише з одним із цих значень відхиляється.

Кожен QR-код — це QR-код `website` з коротким посиланням. Див. [Дані QR-коду за типами](https://docs.getqr.com/ua/api/guides/qr-types.md).

## Заголовки

**Authorization** `string` *required*

`Bearer`, а за ним ваш API-ключ. Див. [Автентифікація](https://docs.getqr.com/ua/api/authentication.md).

**Content-Type** `string`

`application/json` для [Створення з JSON](#створення-з-json), `multipart/form-data` для [Створення з CSV-файлу](#створення-з-csv-файлу).

## Об'єкт масового створення

**id** `string`

ID масового створення, наприклад `cm2k7x9qb0003ax8eb4f6gh2t`.

**status** `string`

`queued`, `processing`, `packaging` або `completed`. Невдале чи скасоване масове створення проходить через `rollingBack` до `failed`.

**sourceFilename** `string`

Назва вихідного файлу.

**totalCount** `integer`

Кількість рядків.

**createdCount** `integer`

Скільки QR-кодів уже створено.

**renderedCount** `integer`

Скільки зображень QR-кодів уже відрендерено.

**percent** `integer`

Загальний прогрес, від 0 до 100. Створення займає до 40, рендеринг — до 90, пакування — 95, а `completed` — 100.

**stalled** `boolean`

`true`, якщо масове створення, що виконується, не просувається вже 2 хвилини. Продовжуйте опитування: [Отримання масового створення](#отримання-масового-створення) перезапускає завислий процес.

**error** `object | null`

Коли `status` дорівнює `failed`: `code` і `message`. Скасоване масове створення має код `cancelled_by_user`. Невдале масове створення відкочується, тож жоден із його QR-кодів не зберігається.

**downloadUrl** `string | null`

Шлях до [Завантаження архіву](#завантаження-архіву), щойно `status` стане `completed`.

**createdAt** `string`

Дата запуску, ISO 8601.

**updatedAt** `string`

Дата останнього оновлення, ISO 8601.

**completedAt** `string | null`

Дата завершення, ISO 8601.

**failedAt** `string | null`

Дата збою, ISO 8601.

## Отримання поточного масового створення

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

Повертає масове створення, яке ще виконується у вашому робочому просторі. Якщо нічого не виконується, повертає останнє завершене (`completed` або `failed`), доки його не буде закрито: це відбувається, коли ви завантажуєте його архів або закриваєте його в панелі керування. Інакше повертає `null`. Використовуйте цей ендпоінт, щоб відновити відстеження після перезапуску.

```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 (немає чого відновлювати) theme={null}
null
```

## Створення з JSON

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

Запускає масове створення зі списку рядків. Відповідає `202 Accepted`. Масове створення виконується у фоновому режимі.

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

QR-коди, які потрібно створити, до 100. Кожен рядок має вигляд `{ "name": "...", "url": "..." }` і не приймає інших полів. Див. [Рядки](#рядки).

**design** `object` *required*

Дизайн, що застосовується до кожного QR-коду: `styles`, `frameOptions` і `logoOptions`, усі необов'язкові. Для дизайну за замовчуванням надішліть `{}`. Інші поля відхиляються. Див. [Оформлення](https://docs.getqr.com/ua/api/guides/customization.md).

**sourceFilename** `string` *required*

Назва, що відображається в панелі керування й використовується для архіву, від 1 до 255 символів.

**idempotencyKey** `string` *required*

Ваш власний ключ для цього масового створення, від 8 до 100 символів.

```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
}
```

## Створення з CSV-файлу

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

Те саме, що й [Створення з JSON](#створення-з-json), але рядки передаються як CSV-файл у `multipart/form-data`. Відповідає `202 Accepted`.

Файл має бути `.csv` розміром не більше 1 000 000 байтів. Рядок заголовків має бути саме `name,url`, а за ним — до 100 рядків даних. Див. [Формат CSV](https://docs.getqr.com/ua/bulk/csv-format.md).

**file** `file` *required*

CSV-файл.

**design** `string` *required*

Об'єкт дизайну, серіалізований у JSON, наприклад `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Для дизайну за замовчуванням надішліть `{}`.

**idempotencyKey** `string` *required*

Ваш власний ключ для цього масового створення, від 8 до 100 символів.

**sourceFilename** `string`

Назва, що відображається в панелі керування й використовується для архіву, до 255 символів. За замовчуванням — назва завантаженого файлу.

```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
}
```

## Отримання масового створення

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

Повертає статус і прогрес масового створення. Опитуйте його, поки `status` дорівнює `queued`, `processing` або `packaging`. `downloadUrl` з'являється, щойно архів готовий.

**id** `string` *required*

ID масового створення. Візьміть його з відповіді на створення або на запит поточного масового створення.

```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
}
```

## Скасування масового створення

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

Зупиняє масове створення, що виконується, і видаляє вже створені ним QR-коди. Відкат виконується під час запиту, тож відповідь зазвичай містить `status` `failed` і `error.code` `cancelled_by_user`. Скасування масового створення, яке вже завершилося збоєм, повертає його без змін.

> [!WARNING]
>
> Завершене масове створення скасувати не можна: запит повертає `400`. Натомість видаліть його QR-коди по одному через [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md).

**id** `string` *required*

ID масового створення.

```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"
}
```

## Завантаження архіву

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

Повертає ZIP-архів з одним JPEG розміром 1024 px на кожен QR-код, названим за його рядком: `001-Menu.jpg`, `002-Wine list.jpg` і так далі. Архів названо за `sourceFilename`. Доступно, щойно `status` стане `completed`. Завантаження закриває масове створення, тож [Отримання поточного масового створення](#отримання-поточного-масового-створення) більше його не повертає.

**id** `string` *required*

ID масового створення.

```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>
```

## Поширені проблеми

> [accordion] 422 з "contains an invalid HTTP(S) URL"
>
> Повідомлення називає рядок. Кожен URL має бути адресою `http` або `https` зі справжнім доменом, наприклад `example.com/menu`. Виправте рядок і надішліть запит знову.

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> Перший рядок CSV має бути `name,url` — саме в такому порядку, у нижньому регістрі й без інших стовпців.

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> Ключі не можна повторно використовувати для іншого пакета. Надішліть новий `idempotencyKey`.

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> Масове створення ще не завершилося. Продовжуйте опитування, доки `status` не стане `completed`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> Масове створення вже завершилося, тож його не можна відкотити.

> [accordion] 403 exceeded\_limit
>
> Ваш робочий простір на плані Single QR, який не включає масового створення. Змініть тарифний план.

> [accordion] Я отримав старіше масове створення замість нового
>
> У вашому робочому просторі ще виконується інше масове створення, або ви повторно використали `idempotencyKey`. Дочекайтеся його завершення або використайте новий ключ.

## Що далі

> [card] [Оформлення](https://docs.getqr.com/ua/api/guides/customization.md)

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)

> [card] [Масове створення в застосунку](https://docs.getqr.com/ua/bulk/overview.md)

> [card] [Формат CSV](https://docs.getqr.com/ua/bulk/csv-format.md)


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