> ## 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]
>
> GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.

Массовое создание превращает список названий и 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/ru/api/guides/qr-types.md).

## Заголовки

**Authorization** `string` *required*

`Bearer` и ваш API-ключ. См. [Аутентификация](https://docs.getqr.com/ru/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/ru/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/ru/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/ru/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/ru/api/guides/customization.md)

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

> [card] [Массовое создание в приложении](https://docs.getqr.com/ru/bulk/overview.md)

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


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