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

# QR-koodien joukkoluonti

> Luo jopa 100 QR-koodia kerralla ja lataa ne ZIP-arkistona.

> [!NOTE]
>
> GetQR API on beetavaiheessa, ja se on käytettävissä valituissa työtiloissa. Yksityiskohdat voivat muuttua ennen yleistä julkaisua.

Joukkoluonti muuttaa nimien ja URL-osoitteiden luettelon Website-QR-koodeiksi, joilla on yhteinen ulkoasu. Se toimii taustalla: käynnistä se, seuraa sen edistymistä ja lataa sitten ZIP-arkisto.

| Metodi | Polku | Kuvaus |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [Hae nykyinen joukkoluonti](#hae-nykyinen-joukkoluonti) |
| `POST` | `/api/v1/bulk-qr-creations` | [Luo JSON-datasta](#luo-json-datasta) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [Luo CSV-tiedostosta](#luo-csv-tiedostosta) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [Hae joukkoluonti](#hae-joukkoluonti) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [Peruuta joukkoluonti](#peruuta-joukkoluonti) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [Lataa arkisto](#lataa-arkisto) |

## Miten se toimii

**1. Käynnistä joukkoluonti**

Lähetä rivisi päätepisteeseen [Luo JSON-datasta](#luo-json-datasta) tai [Luo CSV-tiedostosta](#luo-csv-tiedostosta). API vastaa `202` ja palauttaa joukkoluonnin ja sen `id`-tunnuksen.

**2. Seuraa edistymistä**

Kutsu päätepistettä [Hae joukkoluonti](#hae-joukkoluonti) muutaman sekunnin välein, kunnes `status` on `completed` tai `failed`.

**3. Lataa ZIP-arkisto**

Kun `status` on `completed`, kutsu päätepistettä [Lataa arkisto](#lataa-arkisto), niin saat QR-koodien kuvat ZIP-tiedostona.

* **Raja.** Enintään 100 riviä joukkoluontia kohti.
* **Yksi kerrallaan.** Työtilassa on käynnissä vain yksi joukkoluonti kerrallaan. Jos käynnistät uuden, kun yksi on käynnissä, saat käynnissä olevan.
* **Idempotenssi.** Jokainen pyyntö tarvitsee kentän `idempotencyKey`. Kun toistat pyynnön samalla avaimella ja samalla rungolla, saat jo käynnistetyn joukkoluonnin. Sama avain eri rungolla palauttaa `422`.
* **Rivit.** Jokainen rivi tarvitsee kentät `name` ja `url`. Katso [Rivit](#rivit).
* **Tilaus.** Joukkoluonti ei ole käytettävissä Single QR -tilauksessa: pyyntö palauttaa `403 exceeded_limit`.

## Rivit

* **Nimi.** Siitä tulee QR-koodin nimi. Alun ja lopun välilyönnit poistetaan, ja nimi katkaistaan 40 merkkiin. Toistuviin nimiin (kirjainkoosta riippumatta) lisätään numero: `Menu`, `Menu 2`, `Menu 3`.
* **URL.** Siitä tulee kohde. Sen on oltava `http`- tai `https`-osoite, jossa on oikea verkkotunnus, kuten `example.com/menu`, eikä siinä saa olla välilyöntejä. URL-osoitteeseen, josta skeema puuttuu, lisätään `https://`.
* **Tyhjät rivit.** Rivit, joilla ei ole nimeä eikä URL-osoitetta, ohitetaan. Rivi, jolla on vain toinen niistä, hylätään.

Jokainen QR-koodi on lyhytlinkin varassa toimiva `website`-QR-koodi. Katso [QR-tyypit](https://docs.getqr.com/fi/api/guides/qr-types.md).

## Otsakkeet

**Authorization** `string` *required*

`Bearer` ja sen perässä API-avaimesi. Katso [Todennus](https://docs.getqr.com/fi/api/authentication.md).

**Content-Type** `string`

`application/json` päätepisteelle [Luo JSON-datasta](#luo-json-datasta), `multipart/form-data` päätepisteelle [Luo CSV-tiedostosta](#luo-csv-tiedostosta).

## Joukkoluontiobjekti

**id** `string`

Joukkoluonnin tunnus, esimerkiksi `cm2k7x9qb0003ax8eb4f6gh2t`.

**status** `string`

`queued`, `processing`, `packaging` tai `completed`. Epäonnistunut tai peruutettu joukkoluonti kulkee tilan `rollingBack` kautta tilaan `failed`.

**sourceFilename** `string`

Lähdetiedoston nimi.

**totalCount** `integer`

Rivien määrä.

**createdCount** `integer`

Tähän mennessä luodut QR-koodit.

**renderedCount** `integer`

Tähän mennessä piirretyt QR-koodien kuvat.

**percent** `integer`

Kokonaisedistyminen, 0–100. Luonti vie arvoon 40, piirtäminen arvoon 90, paketointi on 95 ja `completed` on 100.

**stalled** `boolean`

`true`, kun käynnissä oleva joukkoluonti ei ole edistynyt 2 minuuttiin. Jatka seurantaa: [Hae joukkoluonti](#hae-joukkoluonti) käynnistää jumittuneen joukkoluonnin uudelleen.

**error** `object | null`

Kun `status` on `failed`: `code` ja `message`. Peruutetun joukkoluonnin koodi on `cancelled_by_user`. Epäonnistunut joukkoluonti perutaan kokonaan, joten yhtään sen QR-koodia ei säilytetä.

**downloadUrl** `string | null`

[Lataa arkisto](#lataa-arkisto) -päätepisteen polku, kun `status` on `completed`.

**createdAt** `string`

Aloituspäivä, ISO 8601.

**updatedAt** `string`

Viimeisimmän päivityksen päivä, ISO 8601.

**completedAt** `string | null`

Valmistumispäivä, ISO 8601.

**failedAt** `string | null`

Epäonnistumispäivä, ISO 8601.

## Hae nykyinen joukkoluonti

`GET /api/v1/bulk-qr-creations`

Palauttaa työtilassasi vielä käynnissä olevan joukkoluonnin. Jos mikään ei ole käynnissä, palauttaa viimeksi päättyneen (`completed` tai `failed`), kunnes se kuitataan: sen arkiston lataaminen tai kuittaaminen hallintapaneelissa tekee sen. Muuten palauttaa `null`. Käytä tätä seurannan jatkamiseen uudelleenkäynnistyksen jälkeen.

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

## Luo JSON-datasta

`POST /api/v1/bulk-qr-creations`

Käynnistää joukkoluonnin riviluettelosta. Vastaa `202 Accepted`. Joukkoluonti toimii taustalla.

**rows** `object[]` *required*

Luotavat QR-koodit, enintään 100. Jokainen rivi on `{ "name": "...", "url": "..." }`, eikä se ota muita kenttiä. Katso [Rivit](#rivit).

**design** `object` *required*

Jokaiseen QR-koodiin sovellettava ulkoasu: `styles`, `frameOptions` ja `logoOptions`, kaikki valinnaisia. Lähetä `{}` oletusulkoasua varten. Muut kentät hylätään. Katso [Mukauttaminen](https://docs.getqr.com/fi/api/guides/customization.md).

**sourceFilename** `string` *required*

Nimi, joka näkyy hallintapaneelissa ja jota käytetään arkistossa, 1–255 merkkiä.

**idempotencyKey** `string` *required*

Oma avaimesi tälle joukkoluonnille, 8–100 merkkiä.

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

## Luo CSV-tiedostosta

`POST /api/v1/bulk-qr-creations/csv`

Sama kuin [Luo JSON-datasta](#luo-json-datasta), mutta ottaa rivit CSV-tiedostona, joka lähetetään muodossa `multipart/form-data`. Vastaa `202 Accepted`.

Tiedoston on oltava enintään 1 000 000 tavun `.csv`-tiedosto. Sen otsikkorivin on oltava täsmälleen `name,url`, ja sen jälkeen voi olla enintään 100 datariviä. Katso [CSV-muoto](https://docs.getqr.com/fi/bulk/csv-format.md).

**file** `file` *required*

CSV-tiedosto.

**design** `string` *required*

Ulkoasuobjekti JSON-muotoon sarjallistettuna, esimerkiksi `{"styles":{"dotsOptions":{"type":"rounded"}}}`. Lähetä `{}` oletusulkoasua varten.

**idempotencyKey** `string` *required*

Oma avaimesi tälle joukkoluonnille, 8–100 merkkiä.

**sourceFilename** `string`

Nimi, joka näkyy hallintapaneelissa ja jota käytetään arkistossa, enintään 255 merkkiä. Oletus on ladatun tiedoston nimi.

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

## Hae joukkoluonti

`GET /api/v1/bulk-qr-creations/{id}`

Palauttaa joukkoluonnin tilan ja edistymisen. Kysele sitä, kun `status` on `queued`, `processing` tai `packaging`. `downloadUrl` ilmestyy, kun arkisto on valmis.

**id** `string` *required*

Joukkoluonnin tunnus. Ota se luonnin tai nykyisen joukkoluonnin vastauksesta.

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

## Peruuta joukkoluonti

`DELETE /api/v1/bulk-qr-creations/{id}`

Pysäyttää käynnissä olevan joukkoluonnin ja poistaa sen jo luomat QR-koodit. Peruutus suoritetaan pyynnön aikana, joten vastauksessa on yleensä `status` `failed` ja `error.code` `cancelled_by_user`. Jo epäonnistuneen joukkoluonnin peruuttaminen palauttaa sen muuttamattomana.

> [!WARNING]
>
> Valmistunutta joukkoluontia ei voi peruuttaa: pyyntö palauttaa `400`. Poista sen QR-koodit sen sijaan yksi kerrallaan [QR-koodit](https://docs.getqr.com/fi/api/endpoints/qr-codes.md)-päätepisteillä.

**id** `string` *required*

Joukkoluonnin tunnus.

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

## Lataa arkisto

`GET /api/v1/bulk-qr-creations/{id}/download`

Palauttaa ZIP-arkiston, jossa on yksi 1024 px:n JPEG-kuva QR-koodia kohti, nimettynä rivinsä mukaan: `001-Menu.jpg`, `002-Wine list.jpg` ja niin edelleen. Arkisto nimetään `sourceFilename`-arvon mukaan. Käytettävissä, kun `status` on `completed`. Lataaminen kuittaa joukkoluonnin, joten [Hae nykyinen joukkoluonti](#hae-nykyinen-joukkoluonti) lakkaa palauttamasta sitä.

**id** `string` *required*

Joukkoluonnin tunnus.

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

<binary archive data>
```

## Yleisiä ongelmia

> [accordion] 422 ja viesti "contains an invalid HTTP(S) URL"
>
> Viesti nimeää rivin. Jokaisen URL-osoitteen on oltava `http`- tai `https`-osoite, jossa on oikea verkkotunnus, kuten `example.com/menu`. Korjaa rivi ja lähetä pyyntö uudelleen.

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> CSV-tiedoston ensimmäisen rivin on oltava `name,url`, tässä järjestyksessä ja pienin kirjaimin, ilman muita sarakkeita.

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> Avaimia ei voi käyttää uudelleen eri erälle. Lähetä uusi `idempotencyKey`.

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> Joukkoluonti ei ole vielä valmis. Jatka kyselyä, kunnes `status` on `completed`.

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> Joukkoluonti on jo valmis, joten sitä ei voi perua.

> [accordion] 403 exceeded\_limit
>
> Työtilasi on Single QR -tilauksessa, johon joukkoluonti ei sisälly. Päivitä tilaus.

> [accordion] Sain vanhemman joukkoluonnin uuden sijaan
>
> Työtilassasi on vielä käynnissä toinen joukkoluonti, tai käytit `idempotencyKey`-avainta uudelleen. Odota, että se valmistuu, tai käytä uutta avainta.

## Mitä seuraavaksi

> [card] [Mukauttaminen](https://docs.getqr.com/fi/api/guides/customization.md)

> [card] [QR-koodit](https://docs.getqr.com/fi/api/endpoints/qr-codes.md)

> [card] [Joukkoluonti sovelluksessa](https://docs.getqr.com/fi/bulk/overview.md)

> [card] [CSV-muoto](https://docs.getqr.com/fi/bulk/csv-format.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.