> ## 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 em massa > Crie até 100 códigos QR de uma só vez e transfira-os num arquivo ZIP. > [!NOTE] > > A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral. Uma criação em massa transforma uma lista de nomes e URL em códigos QR do tipo website com um design comum. É executada em segundo plano: inicie-a, acompanhe o progresso e depois transfira 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 ficheiro CSV](#criar-a-partir-de-um-ficheiro-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` | [Transferir o arquivo ZIP](#transferir-o-arquivo-zip) | ## Como funciona **1. Inicie a criação em massa** Envie as suas linhas com [Criar a partir de JSON](#criar-a-partir-de-json) ou [Criar a partir de um ficheiro CSV](#criar-a-partir-de-um-ficheiro-csv). A API responde `202` com a criação em massa e o respetivo `id`. **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. Transfira o arquivo ZIP** Quando `status` for `completed`, chame [Transferir o arquivo ZIP](#transferir-o-arquivo-zip) para obter um ZIP com as imagens dos códigos QR. * **Limite.** Até 100 linhas por criação em massa. * **Uma de cada vez.** Só é executada uma criação em massa por espaço de trabalho. Se iniciar outra enquanto uma está em curso, é devolvida a que está em curso. * **Idempotência.** Cada pedido precisa de um `idempotencyKey`. Repetir um pedido com a mesma chave e o mesmo corpo devolve a criação em massa já iniciada. A mesma chave com outro corpo devolve `422`. * **Linhas.** Cada linha precisa de um `name` e de um `url`. Consulte [Linhas](#linhas). * **Plano.** A criação em massa não está disponível no plano Single QR: o pedido devolve `403 exceeded_limit`. ## Linhas * **Nome.** Passa a ser o título do código QR. Os espaços no início e no fim são removidos e é cortado a 40 caracteres. Os nomes repetidos (sem distinguir maiúsculas de minúsculas) recebem um número: `Menu`, `Menu 2`, `Menu 3`. * **URL.** Passa a ser o destino. Tem de ser um endereço `http` ou `https` com um domínio real, como `example.com/menu`, e não pode conter espaços. A um URL sem esquema é acrescentado `https://`. * **Linhas vazias.** As linhas sem nome nem URL são ignoradas. Uma linha com apenas um dos dois é rejeitada. Todos os códigos QR são do tipo `website` com uma ligação curta. Consulte [Tipos de QR](https://docs.getqr.com/pt/api/guides/qr-types.md). ## Cabeçalhos **Authorization** `string` *required* `Bearer` seguido da sua chave de API. Consulte [Autenticação](https://docs.getqr.com/pt/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 ficheiro CSV](#criar-a-partir-de-um-ficheiro-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 falhada ou cancelada passa por `rollingBack` até `failed`. **sourceFilename** `string` Nome do ficheiro de origem. **totalCount** `integer` Número de linhas. **createdCount** `integer` Códigos QR criados até ao momento. **renderedCount** `integer` Imagens de códigos QR geradas até ao momento. **percent** `integer` Progresso global, de 0 a 100. A criação vai até 40, a geração das imagens até 90, o empacotamento corresponde a 95 e `completed` a 100. **stalled** `boolean` `true` quando uma criação em massa em curso não avança há 2 minutos. Continue a consultar: [Obter uma criação em massa](#obter-uma-criação-em-massa) reinicia uma criação em massa parada. **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 falhada é revertida, pelo que nenhum dos respetivos códigos QR é mantido. **downloadUrl** `string | null` Caminho de [Transferir o arquivo ZIP](#transferir-o-arquivo-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` Devolve a criação em massa que ainda está em curso no seu espaço de trabalho. Quando nenhuma está em curso, devolve a última concluída (`completed` ou `failed`) até ser dispensada: transferir o respetivo arquivo ou dispensá-la no painel tem esse efeito. Caso contrário, devolve `null`. Use-o para retomar o acompanhamento após um reinício. ```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 é executada em segundo plano. **rows** `object[]` *required* Códigos QR a criar, até 100. Cada linha é `{ "name": "...", "url": "..." }` e não aceita outros campos. Consulte [Linhas](#linhas). **design** `object` *required* Design aplicado a todos os códigos QR: `styles`, `frameOptions` e `logoOptions`, todos opcionais. Envie `{}` para o design predefinido. Os outros campos são rejeitados. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md). **sourceFilename** `string` *required* Nome apresentado no painel e usado para o arquivo, de 1 a 255 caracteres. **idempotencyKey** `string` *required* A 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 ficheiro CSV `POST /api/v1/bulk-qr-creations/csv` Igual a [Criar a partir de JSON](#criar-a-partir-de-json), mas recebe as linhas num ficheiro CSV enviado como `multipart/form-data`. Responde `202 Accepted`. O ficheiro tem de ser um `.csv` com, no máximo, 1 000 000 bytes. A linha de cabeçalho tem de ser exatamente `name,url`, seguida de até 100 linhas de dados. Consulte [Formato CSV](https://docs.getqr.com/pt/bulk/csv-format.md). **file** `file` *required* O ficheiro CSV. **design** `string` *required* O objeto de design, serializado em JSON, por exemplo `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Envie `{}` para o design predefinido. **idempotencyKey** `string` *required* A sua própria chave para esta criação em massa, de 8 a 100 caracteres. **sourceFilename** `string` Nome apresentado no painel e usado para o arquivo, até 255 caracteres. Por predefinição, o nome do ficheiro carregado. ```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}` Devolve o estado e o progresso de uma criação em massa. Consulte-o enquanto `status` for `queued`, `processing` ou `packaging`. `downloadUrl` aparece assim que o arquivo estiver pronto. **id** `string` *required* ID da criação em massa. Obtenha-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}` Para uma criação em massa em curso e elimina os códigos QR que já criou. A reversão é executada durante o pedido, pelo que a resposta tem normalmente `status` `failed` e `error.code` `cancelled_by_user`. Cancelar uma criação em massa que já falhou devolve-a sem alterações. > [!WARNING] > > Uma criação em massa concluída não pode ser cancelada: o pedido devolve `400`. Em vez disso, elimine os respetivos códigos QR um a um com [Códigos QR](https://docs.getqr.com/pt/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" } ``` ## Transferir o arquivo ZIP `GET /api/v1/bulk-qr-creations/{id}/download` Devolve um arquivo ZIP com um JPEG de 1024 px por código QR, com o nome da respetiva linha: `001-Menu.jpg`, `002-Wine list.jpg` e assim por diante. O arquivo recebe o nome de `sourceFilename`. Disponível quando `status` é `completed`. A transferência dispensa a criação em massa, pelo que [Obter a criação em massa atual](#obter-a-criação-em-massa-atual) deixa de a devolver. **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" ``` ## Problemas comuns > [accordion] 422 com "contains an invalid HTTP(S) URL" > > A mensagem indica a linha. Cada URL tem de ser um endereço `http` ou `https` com um domínio real, como `example.com/menu`. Corrija a linha e volte a enviar o pedido. > [accordion] 422 "CSV headers must be exactly: name,url." > > A primeira linha do CSV tem de ser `name,url`, por esta 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 outro lote. Envie um novo `idempotencyKey`. > [accordion] 409 "The bulk QR archive is not ready for download." > > A criação em massa ainda não terminou. Continue a consultar até `status` ser `completed`. > [accordion] 400 "Cannot cancel a finished bulk QR creation." > > A criação em massa já foi concluída, pelo que não pode ser revertida. > [accordion] 403 exceeded\_limit > > O seu espaço de trabalho está no plano Single QR, que não inclui a criação em massa. Mude para um plano superior. > [accordion] Recebi uma criação em massa anterior em vez de uma nova > > Outra criação em massa ainda está em curso no seu espaço de trabalho, ou reutilizou um `idempotencyKey`. Aguarde que termine ou use uma nova chave. ## Próximos passos > [card] [Personalização](https://docs.getqr.com/pt/api/guides/customization.md) > [card] [Códigos QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md) > [card] [Criação em massa na aplicação](https://docs.getqr.com/pt/bulk/overview.md) > [card] [Formato CSV](https://docs.getqr.com/pt/bulk/csv-format.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.