> ## 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. # Creazioni di QR in blocco > Crea fino a 100 QR code in una volta e scaricali in un archivio ZIP. > [!NOTE] > > 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](#ottieni-la-creazione-in-blocco-attuale) | | `POST` | `/api/v1/bulk-qr-creations` | [Crea da JSON](#crea-da-json) | | `POST` | `/api/v1/bulk-qr-creations/csv` | [Crea da un file CSV](#crea-da-un-file-csv) | | `GET` | `/api/v1/bulk-qr-creations/{id}` | [Ottieni una creazione in blocco](#ottieni-una-creazione-in-blocco) | | `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Annulla una creazione in blocco](#annulla-una-creazione-in-blocco) | | `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Scarica l'archivio](#scarica-l-archivio) | ## Come funziona **1. Avvia la creazione in blocco** Invia le righe con [Crea da JSON](#crea-da-json) o [Crea da un file CSV](#crea-da-un-file-csv). L'API risponde `202` con la creazione in blocco e il suo `id`. **2. Controlla l'avanzamento** Chiama [Ottieni una creazione in blocco](#ottieni-una-creazione-in-blocco) ogni pochi secondi finché `status` non è `completed` o `failed`. **3. Scarica l'archivio** Quando `status` è `completed`, chiama [Scarica l'archivio](#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](#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](https://docs.getqr.com/it/api/guides/qr-types.md). ## Header **Authorization** `string` *required* `Bearer` seguito dalla tua chiave API. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md). **Content-Type** `string` `application/json` per [Crea da JSON](#crea-da-json), `multipart/form-data` per [Crea da un file CSV](#crea-da-un-file-csv). ## L'oggetto creazione in blocco **id** `string` ID della creazione in blocco, ad esempio `cm2k7x9qb0003ax8eb4f6gh2t`. **status** `string` `queued`, `processing`, `packaging` o `completed`. Una creazione in blocco non riuscita o annullata passa da `rollingBack` a `failed`. **sourceFilename** `string` Nome del file di origine. **totalCount** `integer` Numero di righe. **createdCount** `integer` QR code creati finora. **renderedCount** `integer` Immagini dei QR code generate finora. **percent** `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. **stalled** `boolean` `true` quando una creazione in blocco in corso non avanza da 2 minuti. Continua a controllare: [Ottieni una creazione in blocco](#ottieni-una-creazione-in-blocco) riavvia una creazione in blocco bloccata. **error** `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. **downloadUrl** `string | null` Percorso di [Scarica l'archivio](#scarica-l-archivio), quando `status` è `completed`. **createdAt** `string` Data di avvio, ISO 8601. **updatedAt** `string` Data dell'ultimo aggiornamento, ISO 8601. **completedAt** `string | null` Data di completamento, ISO 8601. **failedAt** `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. ```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 ``` ## 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. **rows** `object[]` *required* QR code da creare, fino a 100. Ogni riga è `{ "name": "...", "url": "..." }` e non accetta altri campi. Consulta [Righe](#righe). **design** `object` *required* Design applicato a ogni QR code: `styles`, `frameOptions` e `logoOptions`, tutti facoltativi. Invia `{}` per il design predefinito. Gli altri campi vengono rifiutati. Consulta [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md). **sourceFilename** `string` *required* Nome mostrato nella dashboard e usato per l'archivio, da 1 a 255 caratteri. **idempotencyKey** `string` *required* La tua chiave per questa creazione in blocco, da 8 a 100 caratteri. ```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 } ``` ## Crea da un file CSV `POST /api/v1/bulk-qr-creations/csv` Come [Crea da JSON](#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](https://docs.getqr.com/it/bulk/csv-format.md). **file** `file` *required* Il file CSV. **design** `string` *required* L'oggetto design, serializzato in JSON, ad esempio `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Invia `{}` per il design predefinito. **idempotencyKey** `string` *required* La tua chiave per questa creazione in blocco, da 8 a 100 caratteri. **sourceFilename** `string` Nome mostrato nella dashboard e usato per l'archivio, fino a 255 caratteri. Predefinito: il nome del file caricato. ```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 } ``` ## 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. **id** `string` *required* ID della creazione in blocco. Prendilo dalla risposta della creazione o della creazione in blocco attuale. ```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 } ``` ## 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. > [!WARNING] > > 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](https://docs.getqr.com/it/api/endpoints/qr-codes.md). **id** `string` *required* ID della creazione in blocco. ```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" } ``` ## 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](#ottieni-la-creazione-in-blocco-attuale) smette di restituirla. **id** `string` *required* ID della creazione in blocco. ```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" ``` ## Problemi comuni > [accordion] 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. > [accordion] 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. > [accordion] 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`. > [accordion] 409 "The bulk QR archive is not ready for download." > > La creazione in blocco non è ancora completata. Continua a controllare finché `status` non è `completed`. > [accordion] 400 "Cannot cancel a finished bulk QR creation." > > La creazione in blocco è già completata, quindi non può essere annullata. > [accordion] 403 exceeded\_limit > > Il tuo workspace ha il piano Single QR, che non include la creazione in blocco. Passa a un piano superiore. > [accordion] 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. ## Passaggi successivi > [card] [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md) > [card] [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md) > [card] [Creazione in blocco nell'app](https://docs.getqr.com/it/bulk/overview.md) > [card] [Formato CSV](https://docs.getqr.com/it/bulk/csv-format.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.