Criação de QR em massa

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

null

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
`POST`	`/api/v1/bulk-qr-creations`	Criar a partir de JSON
`POST`	`/api/v1/bulk-qr-creations/csv`	Criar a partir de um ficheiro CSV
`GET`	`/api/v1/bulk-qr-creations/{id}`	Obter uma criação em massa
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	Cancelar uma criação em massa
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	Transferir o arquivo ZIP

Como funciona

Inicie a criação em massa

Envie as suas linhas com Criar a partir de JSON ou Criar a partir de um ficheiro CSV. A API responde 202 com a criação em massa e o respetivo id.

Acompanhe o progresso

Chame Obter uma criação em massa a cada poucos segundos até status ser completed ou failed.

Transfira o arquivo ZIP

Quando status for completed, chame 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.
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.

Cabeçalhos

string

obrigatório

Bearer seguido da sua chave de API. Consulte Autenticação.

string

application/json para Criar a partir de JSON, multipart/form-data para Criar a partir de um ficheiro CSV.

O objeto de criação em massa

string

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

string

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

string

Nome do ficheiro de origem.

integer

Número de linhas.

integer

Códigos QR criados até ao momento.

integer

Imagens de códigos QR geradas até ao momento.

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.

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 reinicia uma criação em massa parada.

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.

string | null

Caminho de Transferir o arquivo ZIP, quando status é completed.

string

Data de início, ISO 8601.

string

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

string | null

Data de conclusão, ISO 8601.

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.

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

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.

object[]

obrigatório

Códigos QR a criar, até 100. Cada linha é { "name": "...", "url": "..." } e não aceita outros campos. Consulte Linhas.

object

obrigatório

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.

string

obrigatório

Nome apresentado no painel e usado para o arquivo, de 1 a 255 caracteres.

string

obrigatório

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

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

{
  "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, 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.

file

obrigatório

O ficheiro CSV.

string

obrigatório

O objeto de design, serializado em JSON, por exemplo {"styles":{"dotsOptions":{"type":"rounded"}}}. Envie {} para o design predefinido.

string

obrigatório

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

string

Nome apresentado no painel e usado para o arquivo, até 255 caracteres. Por predefinição, o nome do ficheiro carregado.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "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.

string

obrigatório

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

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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.

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.

string

obrigatório

ID da criação em massa.

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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 deixa de a devolver.

string

obrigatório

ID da criação em massa.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

Problemas comuns

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.

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.

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.

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.

400 "Cannot cancel a finished bulk QR creation."

A criação em massa já foi concluída, pelo que não pode ser revertida.

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.

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.

API

Criação de QR em massa

Como funciona

Linhas

Cabeçalhos

O objeto de criação em massa

Obter a criação em massa atual

Criar a partir de JSON

Criar a partir de um ficheiro CSV

Obter uma criação em massa

Cancelar uma criação em massa

Transferir o arquivo ZIP

Problemas comuns

Próximos passos

Personalização

Códigos QR

Criação em massa na aplicação

Formato CSV

​Como funciona

​Linhas

​Cabeçalhos

​O objeto de criação em massa

​Obter a criação em massa atual

​Criar a partir de JSON

​Criar a partir de um ficheiro CSV

​Obter uma criação em massa

​Cancelar uma criação em massa

​Transferir o arquivo ZIP

​Problemas comuns

​Próximos passos

Personalização

Códigos QR

Criação em massa na aplicação

Formato CSV

Como funciona

Linhas

Cabeçalhos

O objeto de criação em massa

Obter a criação em massa atual

Criar a partir de JSON

Criar a partir de um ficheiro CSV

Obter uma criação em massa

Cancelar uma criação em massa

Transferir o arquivo ZIP

Problemas comuns

Próximos passos