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

# Criação de QR codes em massa

> Crie até 100 QR codes de uma vez e baixe-os em um arquivo ZIP.

> [!NOTE]
>
> A API do GetQR está em beta e disponível para workspaces selecionados. Os detalhes podem mudar antes do lançamento oficial.

Uma criação em massa transforma uma lista de nomes e URLs em QR codes de Website com um design em comum. Ela roda em segundo plano: inicie-a, acompanhe o progresso e depois baixe o arquivo ZIP.

| Método | Caminho | Descrição |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [Obter a criação em massa atual](#obter-a-criação-em-massa-atual) |
| `POST` | `/api/v1/bulk-qr-creations` | [Criar a partir de JSON](#criar-a-partir-de-json) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [Criar a partir de um arquivo CSV](#criar-a-partir-de-um-arquivo-csv) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [Obter uma criação em massa](#obter-uma-criação-em-massa) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Cancelar uma criação em massa](#cancelar-uma-criação-em-massa) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Baixar o ZIP](#baixar-o-zip) |

## Como funciona

**1. Inicie a criação em massa**

Envie suas linhas com [Criar a partir de JSON](#criar-a-partir-de-json) ou [Criar a partir de um arquivo CSV](#criar-a-partir-de-um-arquivo-csv). A API responde `202` com a criação em massa e o `id` dela.

**2. Acompanhe o progresso**

Chame [Obter uma criação em massa](#obter-uma-criação-em-massa) a cada poucos segundos até `status` ser `completed` ou `failed`.

**3. Baixe o ZIP**

Quando `status` for `completed`, chame [Baixar o ZIP](#baixar-o-zip) para obter um ZIP com as imagens dos QR codes.

* **Limite.** Até 100 linhas por criação em massa.
* **Uma por vez.** Só uma criação em massa roda por workspace. Iniciar outra enquanto uma está em andamento retorna a que está em andamento.
* **Idempotência.** Toda requisição precisa de uma `idempotencyKey`. Repetir uma requisição com a mesma chave e o mesmo corpo retorna a criação em massa já iniciada. A mesma chave com um corpo diferente retorna `422`.
* **Linhas.** Cada linha precisa de um `name` e de uma `url`. Veja [Linhas](#linhas).
* **Plano.** A criação em massa não está disponível no plano Single QR: a requisição retorna `403 exceeded_limit`.

## Linhas

* **Nome.** Vira o título do QR code. Os espaços nas pontas são removidos e o texto é cortado em 40 caracteres. Nomes repetidos (sem diferenciar maiúsculas de minúsculas) recebem um número: `Menu`, `Menu 2`, `Menu 3`.
* **URL.** Vira o destino. Precisa ser um endereço `http` ou `https` com um domínio real, como `example.com/menu`, e não pode conter espaços. Uma URL sem esquema recebe `https://`.
* **Linhas vazias.** Linhas sem nome e sem URL são ignoradas. Uma linha com apenas um dos dois é rejeitada.

Todo QR code é um QR code `website` com link curto. Veja [Tipos de QR](https://docs.getqr.com/pt-br/api/guides/qr-types.md).

## Cabeçalhos

**Authorization** `string` *required*

`Bearer` seguido da sua chave de API. Veja [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md).

**Content-Type** `string`

`application/json` para [Criar a partir de JSON](#criar-a-partir-de-json), `multipart/form-data` para [Criar a partir de um arquivo CSV](#criar-a-partir-de-um-arquivo-csv).

## O objeto de criação em massa

**id** `string`

ID da criação em massa, por exemplo `cm2k7x9qb0003ax8eb4f6gh2t`.

**status** `string`

`queued`, `processing`, `packaging` ou `completed`. Uma criação em massa com falha ou cancelada passa por `rollingBack` até `failed`.

**sourceFilename** `string`

Nome do arquivo de origem.

**totalCount** `integer`

Número de linhas.

**createdCount** `integer`

QR codes criados até agora.

**renderedCount** `integer`

Imagens de QR codes geradas até agora.

**percent** `integer`

Progresso geral, de 0 a 100. A criação vai até 40, a geração das imagens até 90, o empacotamento é 95, e `completed` é 100.

**stalled** `boolean`

`true` quando uma criação em massa em andamento não avança há 2 minutos. Continue consultando: [Obter uma criação em massa](#obter-uma-criação-em-massa) reinicia uma criação em massa travada.

**error** `object | null`

Quando `status` é `failed`: `code` e `message`. Uma criação em massa cancelada tem o código `cancelled_by_user`. Uma criação em massa com falha é revertida, então nenhum dos QR codes dela é mantido.

**downloadUrl** `string | null`

Caminho de [Baixar o ZIP](#baixar-o-zip), quando `status` é `completed`.

**createdAt** `string`

Data de início, ISO 8601.

**updatedAt** `string`

Data da última atualização, ISO 8601.

**completedAt** `string | null`

Data de conclusão, ISO 8601.

**failedAt** `string | null`

Data da falha, ISO 8601.

## Obter a criação em massa atual

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

Retorna a criação em massa ainda em andamento no seu workspace. Se nenhuma estiver em andamento, retorna a última concluída (`completed` ou `failed`) até que ela seja dispensada: baixar o ZIP dela ou dispensá-la no painel faz isso. Caso contrário, retorna `null`. Use-o para voltar a acompanhar o processo depois de uma reinicialização.

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

## Criar a partir de JSON

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

Inicia uma criação em massa a partir de uma lista de linhas. Responde `202 Accepted`. A criação em massa roda em segundo plano.

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

QR codes a criar, até 100. Cada linha é `{ "name": "...", "url": "..." }` e não aceita outros campos. Veja [Linhas](#linhas).

**design** `object` *required*

Design aplicado a todos os QR codes: `styles`, `frameOptions` e `logoOptions`, todos opcionais. Envie `{}` para o design padrão. Outros campos são rejeitados. Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

**sourceFilename** `string` *required*

Nome exibido no painel e usado para o ZIP, de 1 a 255 caracteres.

**idempotencyKey** `string` *required*

Sua própria chave para esta criação em massa, de 8 a 100 caracteres.

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

## Criar a partir de um arquivo CSV

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

Igual a [Criar a partir de JSON](#criar-a-partir-de-json), mas recebe as linhas como um arquivo CSV enviado como `multipart/form-data`. Responde `202 Accepted`.

O arquivo precisa ser um `.csv` de no máximo 1.000.000 bytes. A linha de cabeçalho precisa ser exatamente `name,url`, seguida de até 100 linhas de dados. Veja [Formato do CSV](https://docs.getqr.com/pt-br/bulk/csv-format.md).

**file** `file` *required*

O arquivo CSV.

**design** `string` *required*

O objeto de design, serializado como JSON, por exemplo `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Envie `{}` para o design padrão.

**idempotencyKey** `string` *required*

Sua própria chave para esta criação em massa, de 8 a 100 caracteres.

**sourceFilename** `string`

Nome exibido no painel e usado para o ZIP, até 255 caracteres. Padrão: o nome do arquivo enviado.

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

## Obter uma criação em massa

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

Retorna o status e o progresso de uma criação em massa. Consulte-o enquanto `status` for `queued`, `processing` ou `packaging`. `downloadUrl` aparece quando o ZIP fica pronto.

**id** `string` *required*

ID da criação em massa. Pegue-o na resposta da criação ou da criação em massa atual.

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

## Cancelar uma criação em massa

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

Interrompe uma criação em massa em andamento e exclui os QR codes que ela já criou. A reversão acontece durante a requisição, então a resposta normalmente vem com `status` `failed` e `error.code` `cancelled_by_user`. Cancelar uma criação em massa que já falhou a retorna sem alterações.

> [!WARNING]
>
> Uma criação em massa concluída não pode ser cancelada: a requisição retorna `400`. Exclua os QR codes dela um a um com [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md).

**id** `string` *required*

ID da criação em massa.

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

## Baixar o ZIP

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

Retorna um arquivo ZIP com um JPEG de 1024 px por QR code, nomeado de acordo com a linha: `001-Menu.jpg`, `002-Wine list.jpg` e assim por diante. O ZIP recebe o nome de `sourceFilename`. Disponível quando `status` é `completed`. O download dispensa a criação em massa, então [Obter a criação em massa atual](#obter-a-criação-em-massa-atual) deixa de retorná-la.

**id** `string` *required*

ID da criação em massa.

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

## Problemas comuns

> [accordion] 422 com "contains an invalid HTTP(S) URL"
>
> A mensagem indica a linha. Cada URL precisa ser um endereço `http` ou `https` com um domínio real, como `example.com/menu`. Corrija a linha e envie a requisição de novo.

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> A primeira linha do CSV precisa ser `name,url`, nessa ordem e em minúsculas, sem outras colunas.

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> As chaves não podem ser reutilizadas para um lote diferente. Envie uma nova `idempotencyKey`.

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> A criação em massa ainda não foi concluída. Continue consultando até `status` ser `completed`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> A criação em massa já foi concluída, então não pode ser revertida.

> [accordion] 403 exceeded\_limit
>
> Seu workspace está no plano Single QR, que não inclui criação em massa. Faça upgrade do plano.

> [accordion] Recebi uma criação em massa antiga em vez de uma nova
>
> Outra criação em massa ainda está em andamento no seu workspace, ou você reutilizou uma `idempotencyKey`. Espere ela terminar ou use uma nova chave.

## Próximos passos

> [card] [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md)

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

> [card] [Criação em massa no app](https://docs.getqr.com/pt-br/bulk/overview.md)

> [card] [Formato do CSV](https://docs.getqr.com/pt-br/bulk/csv-format.md)


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