Criação de QR codes 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 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
`POST`	`/api/v1/bulk-qr-creations`	Criar a partir de JSON
`POST`	`/api/v1/bulk-qr-creations/csv`	Criar a partir de um arquivo 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`	Baixar o ZIP

Como funciona

Inicie a criação em massa

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

Acompanhe o progresso

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

Baixe o ZIP

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

Cabeçalhos

string

obrigatório

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

string

application/json para Criar a partir de JSON, multipart/form-data para Criar a partir de um arquivo 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 com falha ou cancelada passa por rollingBack até failed.

string

Nome do arquivo de origem.

integer

Número de linhas.

integer

QR codes criados até agora.

integer

Imagens de QR codes geradas até agora.

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.

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

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.

string | null

Caminho de Baixar o 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 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.

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 roda em segundo plano.

object[]

obrigatório

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

object

obrigatório

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.

string

obrigatório

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

string

obrigatório

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 arquivo CSV

POST /api/v1/bulk-qr-creations/csv Igual a 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.

file

obrigatório

O arquivo CSV.

string

obrigatório

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

string

obrigatório

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

string

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

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

string

obrigatório

ID da criação em massa. Pegue-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} 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.

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.

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

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 deixa de retorná-la.

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

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.

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.

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.

400 "Cannot cancel a finished bulk QR creation."

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

403 exceeded_limit

Seu workspace está no plano Single QR, que não inclui criação em massa. Faça upgrade do plano.

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.

API

Criação de QR codes 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 arquivo CSV

Obter uma criação em massa

Cancelar uma criação em massa

Baixar o ZIP

Problemas comuns

Próximos passos

Personalização

QR codes

Criação em massa no app

Formato do 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 arquivo CSV

​Obter uma criação em massa

​Cancelar uma criação em massa

​Baixar o ZIP

​Problemas comuns

​Próximos passos

Personalização

QR codes

Criação em massa no app

Formato do 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 arquivo CSV

Obter uma criação em massa

Cancelar uma criação em massa

Baixar o ZIP

Problemas comuns

Próximos passos