> ## 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. # Massenerstellung > Erstellen Sie bis zu 100 QR-Codes auf einmal und laden Sie sie als ZIP-Archiv herunter. > [!NOTE] > > Die GetQR API befindet sich in der Beta-Phase und steht ausgewählten Workspaces zur Verfügung. Details können sich bis zur allgemeinen Veröffentlichung noch ändern. Eine Massenerstellung macht aus einer Liste von Namen und URLs Website-QR-Codes mit einem gemeinsamen Design. Sie läuft im Hintergrund: Starten Sie sie, fragen Sie ihren Fortschritt ab und laden Sie dann das ZIP-Archiv herunter. | Methode | Pfad | Beschreibung | | - | - | - | | `GET` | `/api/v1/bulk-qr-creations` | [Aktuelle Massenerstellung abrufen](#aktuelle-massenerstellung-abrufen) | | `POST` | `/api/v1/bulk-qr-creations` | [Aus JSON erstellen](#aus-json-erstellen) | | `POST` | `/api/v1/bulk-qr-creations/csv` | [Aus einer CSV-Datei erstellen](#aus-einer-csv-datei-erstellen) | | `GET` | `/api/v1/bulk-qr-creations/{id}` | [Massenerstellung abrufen](#massenerstellung-abrufen) | | `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Massenerstellung abbrechen](#massenerstellung-abbrechen) | | `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Archiv herunterladen](#archiv-herunterladen) | ## So funktioniert es **1. Massenerstellung starten** Senden Sie Ihre Zeilen mit [Aus JSON erstellen](#aus-json-erstellen) oder [Aus einer CSV-Datei erstellen](#aus-einer-csv-datei-erstellen). Die API antwortet mit `202`, der Massenerstellung und ihrer `id`. **2. Fortschritt abfragen** Rufen Sie alle paar Sekunden [Massenerstellung abrufen](#massenerstellung-abrufen) auf, bis `status` den Wert `completed` oder `failed` hat. **3. Archiv herunterladen** Wenn `status` den Wert `completed` hat, rufen Sie [Archiv herunterladen](#archiv-herunterladen) auf, um ein ZIP mit den QR-Code-Bildern zu erhalten. * **Limit.** Bis zu 100 Zeilen pro Massenerstellung. * **Eine nach der anderen.** Pro Workspace läuft nur eine Massenerstellung. Wenn Sie eine weitere starten, während eine läuft, erhalten Sie die laufende zurück. * **Idempotenz.** Jede Anfrage braucht einen `idempotencyKey`. Wiederholen Sie eine Anfrage mit demselben Schlüssel und demselben Body, erhalten Sie die bereits gestartete Massenerstellung. Derselbe Schlüssel mit einem anderen Body liefert `422`. * **Zeilen.** Jede Zeile braucht einen `name` und eine `url`. Siehe [Zeilen](#zeilen). * **Tarif.** Im Tarif Single QR ist die Massenerstellung nicht verfügbar: Die Anfrage liefert `403 exceeded_limit`. ## Zeilen * **Name.** Wird zum Titel des QR-Codes. Wird getrimmt und auf 40 Zeichen gekürzt. Wiederholte Namen (ohne Beachtung der Groß- und Kleinschreibung) erhalten eine Nummer: `Menu`, `Menu 2`, `Menu 3`. * **URL.** Wird zum Ziel. Sie muss eine `http`- oder `https`-Adresse mit einer echten Domain sein, etwa `example.com/menu`, und darf keine Leerzeichen enthalten. Eine URL ohne Schema erhält `https://`. * **Leere Zeilen.** Zeilen ohne Namen und ohne URL werden übersprungen. Eine Zeile mit nur einem von beiden wird abgelehnt. Jeder QR-Code ist ein `website`-QR-Code mit Kurzlink. Siehe [QR-Typen](https://docs.getqr.com/de/api/guides/qr-types.md). ## Header **Authorization** `string` *required* `Bearer` gefolgt von Ihrem API-Schlüssel. Siehe [Authentifizierung](https://docs.getqr.com/de/api/authentication.md). **Content-Type** `string` `application/json` für [Aus JSON erstellen](#aus-json-erstellen), `multipart/form-data` für [Aus einer CSV-Datei erstellen](#aus-einer-csv-datei-erstellen). ## Das Objekt der Massenerstellung **id** `string` ID der Massenerstellung, zum Beispiel `cm2k7x9qb0003ax8eb4f6gh2t`. **status** `string` `queued`, `processing`, `packaging` oder `completed`. Eine fehlgeschlagene oder abgebrochene Massenerstellung durchläuft `rollingBack` bis `failed`. **sourceFilename** `string` Name der Quelldatei. **totalCount** `integer` Anzahl der Zeilen. **createdCount** `integer` Bisher erstellte QR-Codes. **renderedCount** `integer` Bisher gerenderte QR-Code-Bilder. **percent** `integer` Gesamtfortschritt, 0 bis 100. Das Erstellen reicht bis 40, das Rendern bis 90, das Verpacken ist 95, und `completed` ist 100. **stalled** `boolean` `true`, wenn eine laufende Massenerstellung seit 2 Minuten keinen Fortschritt gemacht hat. Fragen Sie weiter ab: [Massenerstellung abrufen](#massenerstellung-abrufen) startet eine hängende Massenerstellung neu. **error** `object | null` Wenn `status` den Wert `failed` hat: `code` und `message`. Eine abgebrochene Massenerstellung hat den Code `cancelled_by_user`. Eine fehlgeschlagene Massenerstellung wird zurückgerollt, sodass keiner ihrer QR-Codes erhalten bleibt. **downloadUrl** `string | null` Pfad von [Archiv herunterladen](#archiv-herunterladen), sobald `status` den Wert `completed` hat. **createdAt** `string` Startdatum, ISO 8601. **updatedAt** `string` Datum der letzten Aktualisierung, ISO 8601. **completedAt** `string | null` Abschlussdatum, ISO 8601. **failedAt** `string | null` Datum des Fehlschlags, ISO 8601. ## Aktuelle Massenerstellung abrufen `GET /api/v1/bulk-qr-creations` Liefert die Massenerstellung, die in Ihrem Workspace noch läuft. Läuft keine, liefert der Endpunkt die zuletzt beendete (`completed` oder `failed`), bis sie verworfen wird: Das geschieht durch das Herunterladen ihres Archivs oder durch Verwerfen im Dashboard. Andernfalls liefert er `null`. Verwenden Sie ihn, um die Überwachung nach einem Neustart fortzusetzen. ```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 ``` ## Aus JSON erstellen `POST /api/v1/bulk-qr-creations` Startet eine Massenerstellung aus einer Liste von Zeilen. Antwortet mit `202 Accepted`. Die Massenerstellung läuft im Hintergrund. **rows** `object[]` *required* Zu erstellende QR-Codes, bis zu 100. Jede Zeile ist `{ "name": "...", "url": "..." }` und akzeptiert keine weiteren Felder. Siehe [Zeilen](#zeilen). **design** `object` *required* Design für alle QR-Codes: `styles`, `frameOptions` und `logoOptions`, alle optional. Senden Sie `{}` für das Standarddesign. Andere Felder werden abgelehnt. Siehe [Anpassung](https://docs.getqr.com/de/api/guides/customization.md). **sourceFilename** `string` *required* Name, der im Dashboard angezeigt und für das Archiv verwendet wird, 1 bis 255 Zeichen. **idempotencyKey** `string` *required* Ihr eigener Schlüssel für diese Massenerstellung, 8 bis 100 Zeichen. ```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 } ``` ## Aus einer CSV-Datei erstellen `POST /api/v1/bulk-qr-creations/csv` Wie [Aus JSON erstellen](#aus-json-erstellen), erwartet die Zeilen aber als CSV-Datei, gesendet als `multipart/form-data`. Antwortet mit `202 Accepted`. Die Datei muss eine `.csv`-Datei mit höchstens 1.000.000 Bytes sein. Ihre Kopfzeile muss genau `name,url` lauten, gefolgt von bis zu 100 Datenzeilen. Siehe [CSV-Format](https://docs.getqr.com/de/bulk/csv-format.md). **file** `file` *required* Die CSV-Datei. **design** `string` *required* Das Design-Objekt, als JSON serialisiert, zum Beispiel `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Senden Sie `{}` für das Standarddesign. **idempotencyKey** `string` *required* Ihr eigener Schlüssel für diese Massenerstellung, 8 bis 100 Zeichen. **sourceFilename** `string` Name, der im Dashboard angezeigt und für das Archiv verwendet wird, bis zu 255 Zeichen. Standard ist der Name der hochgeladenen Datei. ```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 } ``` ## Massenerstellung abrufen `GET /api/v1/bulk-qr-creations/{id}` Liefert Status und Fortschritt einer Massenerstellung. Fragen Sie den Endpunkt ab, solange `status` den Wert `queued`, `processing` oder `packaging` hat. `downloadUrl` erscheint, sobald das Archiv bereit ist. **id** `string` *required* ID der Massenerstellung. Nehmen Sie sie aus der Antwort beim Erstellen oder beim Abruf der aktuellen Massenerstellung. ```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 } ``` ## Massenerstellung abbrechen `DELETE /api/v1/bulk-qr-creations/{id}` Stoppt eine laufende Massenerstellung und löscht die QR-Codes, die sie bereits erstellt hat. Das Zurückrollen erfolgt während der Anfrage, daher hat die Antwort normalerweise `status` `failed` und `error.code` `cancelled_by_user`. Wird eine bereits fehlgeschlagene Massenerstellung abgebrochen, wird sie unverändert zurückgegeben. > [!WARNING] > > Eine abgeschlossene Massenerstellung lässt sich nicht abbrechen: Die Anfrage liefert `400`. Löschen Sie ihre QR-Codes stattdessen einzeln über [QR-Codes](https://docs.getqr.com/de/api/endpoints/qr-codes.md). **id** `string` *required* ID der Massenerstellung. ```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" } ``` ## Archiv herunterladen `GET /api/v1/bulk-qr-creations/{id}/download` Liefert ein ZIP-Archiv mit einem JPEG in 1024 px pro QR-Code, benannt nach seiner Zeile: `001-Menu.jpg`, `002-Wine list.jpg` und so weiter. Das Archiv ist nach `sourceFilename` benannt. Verfügbar, sobald `status` den Wert `completed` hat. Mit dem Herunterladen wird die Massenerstellung verworfen, sodass [Aktuelle Massenerstellung abrufen](#aktuelle-massenerstellung-abrufen) sie nicht mehr liefert. **id** `string` *required* ID der Massenerstellung. ```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" ``` ## Häufige Probleme > [accordion] 422 mit "contains an invalid HTTP(S) URL" > > Die Meldung nennt die Zeile. Jede URL muss eine `http`- oder `https`-Adresse mit einer echten Domain sein, etwa `example.com/menu`. Korrigieren Sie die Zeile und senden Sie die Anfrage erneut. > [accordion] 422 "CSV headers must be exactly: name,url." > > Die erste Zeile der CSV-Datei muss `name,url` lauten, in dieser Reihenfolge, kleingeschrieben und ohne weitere Spalten. > [accordion] 422 "This idempotencyKey was already used with a different request body." > > Schlüssel lassen sich nicht für einen anderen Stapel wiederverwenden. Senden Sie einen neuen `idempotencyKey`. > [accordion] 409 "The bulk QR archive is not ready for download." > > Die Massenerstellung ist noch nicht abgeschlossen. Fragen Sie weiter ab, bis `status` den Wert `completed` hat. > [accordion] 400 "Cannot cancel a finished bulk QR creation." > > Die Massenerstellung ist bereits abgeschlossen und lässt sich daher nicht zurückrollen. > [accordion] 403 exceeded\_limit > > Ihr Workspace nutzt den Tarif Single QR, der keine Massenerstellung enthält. Wechseln Sie zu einem höheren Tarif. > [accordion] Ich habe eine ältere Massenerstellung statt einer neuen erhalten > > In Ihrem Workspace läuft noch eine andere Massenerstellung, oder Sie haben einen `idempotencyKey` wiederverwendet. Warten Sie, bis sie abgeschlossen ist, oder verwenden Sie einen neuen Schlüssel. ## Wie geht es weiter? > [card] [Anpassung](https://docs.getqr.com/de/api/guides/customization.md) > [card] [QR-Codes](https://docs.getqr.com/de/api/endpoints/qr-codes.md) > [card] [Massenerstellung in der App](https://docs.getqr.com/de/bulk/overview.md) > [card] [CSV-Format](https://docs.getqr.com/de/bulk/csv-format.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.