QR-koodien joukkoluonti

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

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
`POST`	`/api/v1/bulk-qr-creations`	Luo JSON-datasta
`POST`	`/api/v1/bulk-qr-creations/csv`	Luo CSV-tiedostosta
`GET`	`/api/v1/bulk-qr-creations/{id}`	Hae joukkoluonti
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	Peruuta joukkoluonti
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	Lataa arkisto

Miten se toimii

Käynnistä joukkoluonti

Lähetä rivisi päätepisteeseen Luo JSON-datasta tai Luo CSV-tiedostosta. API vastaa 202 ja palauttaa joukkoluonnin ja sen id-tunnuksen.

Seuraa edistymistä

Kutsu päätepistettä Hae joukkoluonti muutaman sekunnin välein, kunnes status on completed tai failed.

Lataa ZIP-arkisto

Kun status on completed, kutsu päätepistettä 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.
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.

Otsakkeet

string

vaadittu

Bearer ja sen perässä API-avaimesi. Katso Todennus.

string

application/json päätepisteelle Luo JSON-datasta, multipart/form-data päätepisteelle Luo CSV-tiedostosta.

Joukkoluontiobjekti

string

Joukkoluonnin tunnus, esimerkiksi cm2k7x9qb0003ax8eb4f6gh2t.

string

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

string

Lähdetiedoston nimi.

integer

Rivien määrä.

integer

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

integer

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

integer

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

boolean

true, kun käynnissä oleva joukkoluonti ei ole edistynyt 2 minuuttiin. Jatka seurantaa: Hae joukkoluonti käynnistää jumittuneen joukkoluonnin uudelleen.

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

string | null

Lataa arkisto -päätepisteen polku, kun status on completed.

string

Aloituspäivä, ISO 8601.

string

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

string | null

Valmistumispäivä, ISO 8601.

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.

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

Luo JSON-datasta

POST /api/v1/bulk-qr-creations Käynnistää joukkoluonnin riviluettelosta. Vastaa 202 Accepted. Joukkoluonti toimii taustalla.

object[]

vaadittu

Luotavat QR-koodit, enintään 100. Jokainen rivi on { "name": "...", "url": "..." }, eikä se ota muita kenttiä. Katso Rivit.

object

vaadittu

Jokaiseen QR-koodiin sovellettava ulkoasu: styles, frameOptions ja logoOptions, kaikki valinnaisia. Lähetä {} oletusulkoasua varten. Muut kentät hylätään. Katso Mukauttaminen.

string

vaadittu

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

string

vaadittu

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

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
}

Luo CSV-tiedostosta

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

file

vaadittu

CSV-tiedosto.

string

vaadittu

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

string

vaadittu

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

string

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

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
}

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.

string

vaadittu

Joukkoluonnin tunnus. Ota se luonnin tai nykyisen joukkoluonnin vastauksesta.

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
}

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.

Valmistunutta joukkoluontia ei voi peruuttaa: pyyntö palauttaa 400. Poista sen QR-koodit sen sijaan yksi kerrallaan QR-koodit-päätepisteillä.

string

vaadittu

Joukkoluonnin tunnus.

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

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 lakkaa palauttamasta sitä.

string

vaadittu

Joukkoluonnin tunnus.

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>

Yleisiä ongelmia

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.

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.

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

Avaimia ei voi käyttää uudelleen eri erälle. Lähetä uusi idempotencyKey.

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

Joukkoluonti ei ole vielä valmis. Jatka kyselyä, kunnes status on completed.

400 "Cannot cancel a finished bulk QR creation."

Joukkoluonti on jo valmis, joten sitä ei voi perua.

403 exceeded_limit

Työtilasi on Single QR -tilauksessa, johon joukkoluonti ei sisälly. Päivitä tilaus.

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.

API

QR-koodien joukkoluonti

Miten se toimii

Rivit

Otsakkeet

Joukkoluontiobjekti

Hae nykyinen joukkoluonti

Luo JSON-datasta

Luo CSV-tiedostosta

Hae joukkoluonti

Peruuta joukkoluonti

Lataa arkisto

Yleisiä ongelmia

Mitä seuraavaksi

Mukauttaminen

QR-koodit

Joukkoluonti sovelluksessa

CSV-muoto

​Miten se toimii

​Rivit

​Otsakkeet

​Joukkoluontiobjekti

​Hae nykyinen joukkoluonti

​Luo JSON-datasta

​Luo CSV-tiedostosta

​Hae joukkoluonti

​Peruuta joukkoluonti

​Lataa arkisto

​Yleisiä ongelmia

​Mitä seuraavaksi

Mukauttaminen

QR-koodit

Joukkoluonti sovelluksessa

CSV-muoto

Miten se toimii

Rivit

Otsakkeet

Joukkoluontiobjekti

Hae nykyinen joukkoluonti

Luo JSON-datasta

Luo CSV-tiedostosta

Hae joukkoluonti

Peruuta joukkoluonti

Lataa arkisto

Yleisiä ongelmia

Mitä seuraavaksi