Creazioni di QR in blocco

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

L’API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

Una creazione in blocco trasforma un elenco di nomi e URL in QR code Website con un unico design condiviso. Viene eseguita in background: avviala, controllane l’avanzamento, poi scarica l’archivio ZIP.

Metodo	Percorso	Descrizione
`GET`	`/api/v1/bulk-qr-creations`	Ottieni la creazione in blocco attuale
`POST`	`/api/v1/bulk-qr-creations`	Crea da JSON
`POST`	`/api/v1/bulk-qr-creations/csv`	Crea da un file CSV
`GET`	`/api/v1/bulk-qr-creations/{id}`	Ottieni una creazione in blocco
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	Annulla una creazione in blocco
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	Scarica l’archivio

Come funziona

Avvia la creazione in blocco

Invia le righe con Crea da JSON o Crea da un file CSV. L’API risponde 202 con la creazione in blocco e il suo id.

Controlla l'avanzamento

Chiama Ottieni una creazione in blocco ogni pochi secondi finché status non è completed o failed.

Scarica l'archivio

Quando status è completed, chiama Scarica l’archivio per ottenere uno ZIP con le immagini dei QR code.

Limite. Fino a 100 righe per creazione in blocco.
Una alla volta. In ogni workspace può essere eseguita una sola creazione in blocco. Se ne avvii un’altra mentre una è in corso, ricevi quella in corso.
Idempotenza. Ogni richiesta richiede una idempotencyKey. Se ripeti una richiesta con la stessa chiave e lo stesso corpo, ricevi la creazione in blocco già avviata. La stessa chiave con un corpo diverso restituisce 422.
Righe. Ogni riga richiede un name e un url. Consulta Righe.
Piano. La creazione in blocco non è disponibile con il piano Single QR: la richiesta restituisce 403 exceeded_limit.

Righe

Nome. Diventa il titolo del QR code. Gli spazi iniziali e finali vengono rimossi e il nome viene troncato a 40 caratteri. Ai nomi ripetuti (senza distinzione tra maiuscole e minuscole) viene aggiunto un numero: Menu, Menu 2, Menu 3.
URL. Diventa la destinazione. Deve essere un indirizzo http o https con un dominio reale, come example.com/menu, e non deve contenere spazi. A un URL senza schema viene aggiunto https://.
Righe vuote. Le righe senza nome né URL vengono saltate. Una riga con uno solo dei due viene rifiutata.

Ogni QR code è un QR code website su un link breve. Consulta Tipi di QR.

string

obbligatorio

Bearer seguito dalla tua chiave API. Consulta Autenticazione.

string

application/json per Crea da JSON, multipart/form-data per Crea da un file CSV.

L’oggetto creazione in blocco

string

ID della creazione in blocco, ad esempio cm2k7x9qb0003ax8eb4f6gh2t.

string

queued, processing, packaging o completed. Una creazione in blocco non riuscita o annullata passa da rollingBack a failed.

string

Nome del file di origine.

integer

Numero di righe.

integer

QR code creati finora.

integer

Immagini dei QR code generate finora.

integer

Avanzamento complessivo, da 0 a 100. La creazione arriva fino a 40, la generazione delle immagini fino a 90, il confezionamento dell’archivio è 95 e completed è 100.

boolean

true quando una creazione in blocco in corso non avanza da 2 minuti. Continua a controllare: Ottieni una creazione in blocco riavvia una creazione in blocco bloccata.

object | null

Quando status è failed: code e message. Una creazione in blocco annullata ha il codice cancelled_by_user. Una creazione in blocco non riuscita viene annullata completamente, quindi nessuno dei suoi QR code viene conservato.

string | null

Percorso di Scarica l’archivio, quando status è completed.

string

Data di avvio, ISO 8601.

string

Data dell’ultimo aggiornamento, ISO 8601.

string | null

Data di completamento, ISO 8601.

string | null

Data dell’errore, ISO 8601.

Ottieni la creazione in blocco attuale

GET /api/v1/bulk-qr-creations Restituisce la creazione in blocco ancora in corso nel tuo workspace. Se non ce n’è nessuna in corso, restituisce l’ultima terminata (completed o failed) finché non viene archiviata: ciò avviene quando ne scarichi l’archivio o la chiudi nella dashboard. Altrimenti restituisce null. Usalo per riprendere il monitoraggio dopo un riavvio.

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

Crea da JSON

POST /api/v1/bulk-qr-creations Avvia una creazione in blocco da un elenco di righe. Risponde 202 Accepted. La creazione in blocco viene eseguita in background.

object[]

obbligatorio

QR code da creare, fino a 100. Ogni riga è { "name": "...", "url": "..." } e non accetta altri campi. Consulta Righe.

object

obbligatorio

Design applicato a ogni QR code: styles, frameOptions e logoOptions, tutti facoltativi. Invia {} per il design predefinito. Gli altri campi vengono rifiutati. Consulta Personalizzazione.

string

obbligatorio

Nome mostrato nella dashboard e usato per l’archivio, da 1 a 255 caratteri.

string

obbligatorio

La tua chiave per questa creazione in blocco, da 8 a 100 caratteri.

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
}

Crea da un file CSV

POST /api/v1/bulk-qr-creations/csv Come Crea da JSON, ma accetta le righe come file CSV inviato in multipart/form-data. Risponde 202 Accepted. Il file deve essere un .csv di al massimo 1.000.000 di byte. La riga di intestazione deve essere esattamente name,url, seguita da un massimo di 100 righe di dati. Consulta Formato CSV.

file

obbligatorio

Il file CSV.

string

obbligatorio

L’oggetto design, serializzato in JSON, ad esempio {"styles":{"dotsOptions":{"type":"rounded"}}}. Invia {} per il design predefinito.

string

obbligatorio

La tua chiave per questa creazione in blocco, da 8 a 100 caratteri.

string

Nome mostrato nella dashboard e usato per l’archivio, fino a 255 caratteri. Predefinito: il nome del file caricato.

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
}

Ottieni una creazione in blocco

GET /api/v1/bulk-qr-creations/{id} Restituisce lo stato e l’avanzamento di una creazione in blocco. Interrogalo periodicamente finché status è queued, processing o packaging. downloadUrl compare quando l’archivio è pronto.

string

obbligatorio

ID della creazione in blocco. Prendilo dalla risposta della creazione o della creazione in blocco attuale.

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
}

Annulla una creazione in blocco

DELETE /api/v1/bulk-qr-creations/{id} Interrompe una creazione in blocco in corso ed elimina i QR code che ha già creato. L’annullamento avviene durante la richiesta, quindi la risposta ha normalmente status failed ed error.code cancelled_by_user. Annullare una creazione in blocco già non riuscita la restituisce invariata.

Una creazione in blocco completata non può essere annullata: la richiesta restituisce 400. Elimina invece i suoi QR code uno alla volta con QR code.

string

obbligatorio

ID della creazione in blocco.

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

Scarica l’archivio

GET /api/v1/bulk-qr-creations/{id}/download Restituisce un archivio ZIP con un JPEG da 1024 px per ogni QR code, con il nome della sua riga: 001-Menu.jpg, 002-Wine list.jpg e così via. L’archivio prende il nome da sourceFilename. Disponibile quando status è completed. Il download archivia la creazione in blocco, quindi Ottieni la creazione in blocco attuale smette di restituirla.

string

obbligatorio

ID della creazione in blocco.

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>

Problemi comuni

422 con "contains an invalid HTTP(S) URL"

Il messaggio indica la riga. Ogni URL deve essere un indirizzo http o https con un dominio reale, come example.com/menu. Correggi la riga e invia di nuovo la richiesta.

422 "CSV headers must be exactly: name,url."

La prima riga del CSV deve essere name,url, in quest’ordine e in minuscolo, senza altre colonne.

422 "This idempotencyKey was already used with a different request body."

Le chiavi non possono essere riutilizzate per un lotto diverso. Invia una nuova idempotencyKey.

409 "The bulk QR archive is not ready for download."

La creazione in blocco non è ancora completata. Continua a controllare finché status non è completed.

400 "Cannot cancel a finished bulk QR creation."

La creazione in blocco è già completata, quindi non può essere annullata.

403 exceeded_limit

Il tuo workspace ha il piano Single QR, che non include la creazione in blocco. Passa a un piano superiore.

Ho ricevuto una creazione in blocco precedente invece di una nuova

Un’altra creazione in blocco è ancora in corso nel tuo workspace, oppure hai riutilizzato una idempotencyKey. Attendi che termini oppure usa una nuova chiave.

API

Creazioni di QR in blocco

Come funziona

Righe

Header

L’oggetto creazione in blocco

Ottieni la creazione in blocco attuale

Crea da JSON

Crea da un file CSV

Ottieni una creazione in blocco

Annulla una creazione in blocco

Scarica l’archivio

Problemi comuni

Passaggi successivi

Personalizzazione

QR code

Creazione in blocco nell'app

Formato CSV

​Come funziona

​Righe

​Header

​L’oggetto creazione in blocco

​Ottieni la creazione in blocco attuale

​Crea da JSON

​Crea da un file CSV

​Ottieni una creazione in blocco

​Annulla una creazione in blocco

​Scarica l’archivio

​Problemi comuni

​Passaggi successivi

Personalizzazione

QR code

Creazione in blocco nell'app

Formato CSV

Come funziona

Righe

Header

L’oggetto creazione in blocco

Ottieni la creazione in blocco attuale

Crea da JSON

Crea da un file CSV

Ottieni una creazione in blocco

Annulla una creazione in blocco

Scarica l’archivio

Problemi comuni

Passaggi successivi