QR-koodien API

Yleiskatsaus

Codes-API on qr3.app-palvelun sydän. Sen avulla voit luoda, päivittää ja poistaa dynaamisia ja staattisia QR-koodeja.

Perus-URL: https://qr3.app/v1/codes

Sitova REST-sopimus

Seuraava sopimus koskee kaikkia asiakkaita:

POST /v1/codes hyväksyy vain tyypit url, vcard, wifi, email, sms ja location. Kentät ovat tasaisia: url; vähintään vcard_first_name tai vcard_last_name; wifi_ssid; email_to; sms_phone; tai molemmat location_lat ja location_lng.
Vain url-koodit voivat olla dynaamisia. Luontipyynnöt voivat valinnaisesti sisältää expires_at-kentän ISO 8601 -aikaleimana; ab_enabled, ab_target_url_b ja ab_weight_a (A/B-kohteet) hyväksytään dynaamisille url-koodeille; redirect_after_expiry ei kuulu luontisopimukseen.
GET /v1/codes tukee vain limit, cursor ja status (live, paused, flagged, draft).
POST /v1/codes/batch hyväksyy url, vcard ja wifi. Raja on Free-tasolla 10, Pro-tasolla 500 ja Business/Agency/Enterprise-tasolla 1 000 tietuetta pyyntöä kohden. URL-tarkistukset suoritetaan synkronisesti enintään 50 URL-kohteelle; yli 50 kohteelle vaaditaan skip_url_scan: true.

Luo QR-koodi

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

Vastaus (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

QR-koodityypit

Tyyppi	Kuvaus	Pakolliset kentät
`url`	Verkkosivuston URL (dynaaminen tai staattinen)	`url`
`vcard`	Käyntikortti (vCard 3.0)	`vcard_first_name` tai `vcard_last_name`
`wifi`	Wi-Fi-määritykset	`wifi_ssid`
`email`	Sähköposti (mailto:)	`email_to`
`sms`	Tekstiviesti (SMS)	`sms_phone`
`location`	Sijainti (geo:)	`location_lat`, `location_lng`

Eräluonti (Batch)

`POST /v1/codes/batch`

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Vastaus (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

QR-koodiluettelo

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Kyselyparametrit (Query parameters):

Parametri	Tyyppi	Oletus	Kuvaus
`cursor`	string	—	Kursori sivutusta varten
`limit`	integer	20	Tuloksia per sivu (maks. 100)
`status`	string	—	Suodatin: `live`, `paused`, `flagged`, `draft`

Hae QR-koodi

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Päivitä QR-koodi

`PATCH /v1/codes/:id`

Update contract: url may be changed only for an existing type: "url" code, and its value must use http:// or https://. Other code types must not receive url; invalid requests return 422.

Dynaamiset QR-koodit mahdollistavat kohde-URL-osoitteen muuttamisen milloin tahansa — ilman, että QR-koodia tarvitsee tulostaa uudelleen.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Laskeutumissivu & ulkoiset linkit

Dynaamisille url-koodeille voit asettaa arvon is_landing_page: true (luonnin yhteydessä tai PATCH-pyynnöllä). Skannaus näyttää tällöin qr3-palvelun isännöimän sivun, joka sisältää koodin julkiset tiedostot ja ulkoiset linkit, uudelleenohjauksen sijaan. Ulkoiset linkit välitetään links-taulukkona:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0–20 linkkiä per koodi; label on 1–100 merkkiä; url on oltava http(s) (≤ 2048 merkkiä).
Jokainen URL-osoite tarkistetaan Google Web Risk -palvelulla — turvaton URL-osoite palauttaa virheen 422.
Jos Web Risk ei ole tavoitettavissa tallennushetkellä, linkki hyväksytään silti, mutta se merkitään uudelleentarkistusta varten. Päivittäinen taustatyö tarkistaa tallennetut linkit uudelleen (ja puhtaiksi luokitellut linkit säännöllisesti uudestaan) ja keskeyttää koodin automaattisesti, jos jokin linkki havaitaan myöhemmin turvattomaksi.
"links": [] poistaa kaikki linkit. Katso laskeutumissivun opas.

Poista QR-koodi

`DELETE /v1/codes/:id`

Pehmeä poisto (Soft-Delete) — QR-koodi arkistoidaan, skannaustiedot säilytetään.

Toinen DELETE-pyyntö samalle koodille palauttaa tilakoodin 404, vaikka molemmat pyynnöt saapuisivat samanaikaisesti. Webhook qr.deleted lähetetään tasan kerran.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Lataa QR-kuvat

Kaikki kuvamuodot ovat julkisestii saatavilla — todennusta ei tarvita.

Muoto	URL	Käyttö
SVG (vektori)	`/v1/codes/:code/qr.svg`	Web, skaalaus, digitaalinen
PNG (rasteri)	`/v1/codes/:code/qr.png`	Sähköposti, esitykset
PDF (vektori)	`/v1/codes/:code/qr.pdf`	Oletus: neliö (vain koodi); `?format=a4` tulostusarkille
EPS (vektori)	`/v1/codes/:code/qr.eps`	Ammattimaiset tulostustyönkulut (Adobe, kirjapainot)

Valinnainen: ?size=N — moduulikoko pikseleinä (2–20, oletus: 4) SVG-, PNG- ja EPS-muodoille. PDF käyttää kiinteää moduulikokoa.

Vain PDF: ?format=a4|square — sivumuoto (oletus: square — vain koodi + suoja-alue (Quiet Zone), ei A4-tyhjää tilaa; a4 tulostusvalmiille A4-arkille)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Värit ja virheenkorjaus

Kaikki neljä kuvareittiä ottavat vastaan kolme valinnaista parametria. Ne koskevat vain kyseistä noutokertaa ja ohittavat koodiin tallennetut värit (seuraava osio).

Parametri	Arvot	Oletus	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` tai `RGB`	`000000`	piirretään	piirretään painovärinä
`bg`	Hex kuten `fg` tai `transparent`	`ffffff`	piirretään	piirretään painovärinä
`ecc`	`L`, `M`, `Q`, `H`	`M`	vaikuttaa	vaikuttaa

Kirjoitusasu: Kirjainkoolla ei ole väliä, # on valinnainen. Jos se lähetetään, se on koodattava muodossa %23.
Virheelliset arvot katsotaan puuttuviksi. ?fg=lila palauttaa koodiin tallennetun värin, tai normaalin mustan, jos mitään väriä ei ole tallennettu, tilakoodilla 200 eikä koskaan virhettä. Vain nimenomainen ?fg=000000 pakottaa mustan värin.
bg=transparent palauttaa SVG-, PDF- tai EPS-tiedoston ilman taustaa ja PNG-kuvan aidolla alfaväylällä. Alustan, jolle koodi sijoitetaan, on oltava vaalea, ja sen ympärille on jätettävä 4 moduulin suojavyöhyke. Tumma koodi tummalla alustalla ei ole luettavissa.
PDF ja EPS kirjoittavat mustan ja harmaan harmaasävyinä (vain mustalevy) ja kaikki muut värit CMYK-muodossa kokonaisina prosentteina, esimerkiksi 1F4E79 muodossa C74 M36 Y0 K53. Heti kun väri valitaan, koodin ja sen suojavyöhykkeen takana on peittävä tausta, valkoinen tai bg-värinen, kuten SVG-tiedostossa. Ilman värejä molemmat tiedostot pysyvät muuttumattomina. Muunnos ja rajoitukset: Värit tulostuksessa.
Kontrasti: Kuvareitti ei tarkista sitä. Suositus on vähintään 4:1 ja tummat moduulit vaalealla taustalla. #1F4E79 valkoisella taustalla on 8,7:1, #ff6600 valkoisella taustalla vain 2,9:1.
ecc muuttaa pistekuviota, ei sisältöä. Tulostettu koodi toimii edelleen, mutta vanhoja ja uusia tulostustiedostoja ei pidä sekoittaa keskenään. Q tai H tekevät koodista vikasietoisemman esimerkiksi aaltopahvilla. Logo pakottaa aina tason H.
Logon kanssa logon takana oleva alue pysyy valkoisena myös värillisellä tai läpinäkyvällä taustalla.
Välimuisti: Vain todellinen oletuskuva (musta valkoisella, virheenkorjaus M, ei logoa) toimitetaan muuttumattomana 24 tunnin ajan; kaikki muut versiot 5 minuutin ajan. PDF- ja EPS-muodoissa mikä tahansa määritetty tausta lasketaan poikkeamaksi: bg=ffffff piirtää sinne valkoisen täytön, jota oletustiedostossa ei ole.
Paketti: Värit ja virheenkorjaus ovat käytettävissä kaikissa paketeissa, myös ilmaisessa.

cURL
TypeScript SDK

# Dark blue code on white
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79" -o qr-blue.svg

# Transparent PNG for a layout on a light surface
curl "https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10&bg=transparent" -o qr-transparent.png

# More robust for corrugated board: error correction Q
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?ecc=Q" -o qr-q.pdf

// @qr3/sdk 1.2.0 or later — imageUrl() only builds the URL, it sends no request
// Dark blue code on white
qr3.codes.imageUrl('r7f3Kx', { format: 'svg', fg: '1F4E79' });
// → https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79

// Transparent PNG for a layout on a light surface
qr3.codes.imageUrl('r7f3Kx', { format: 'png', size: 10, bg: 'transparent' });

// More robust for corrugated board: error correction Q
qr3.codes.imageUrl('r7f3Kx', { format: 'pdf', ecc: 'Q' });

Värien tallentaminen koodiin

PATCH /v1/codes/:id tallentaa värit koodin appearance-kenttään. Kuvareitit piirtävät ne tällöin oletuksena ilman parametreja.

cURL
TypeScript SDK

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance": {"foreground_color": "#1F4E79"}}'

// @qr3/sdk 1.2.0 or later
const code = await qr3.codes.update('qr_a1b2c3d4', {
  appearance: { foreground_color: '#1F4E79' },
});
code.appearance; // { foreground_color: '#1F4E79', background_color: null }
code.issues;     // contrast check findings, absent when there are none

Vastaus (HTTP 200, lyhennetty):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "appearance": { "foreground_color": "#1F4E79", "background_color": null }
  },
  "meta": { "request_id": "req_xyz", "issues": [] }
}

Arvot: foreground_color muodossa #RRGGBB, background_color muodossa #RRGGBB tai transparent. Muut avaimet palauttavat koodin 400.
Yhdistäminen: Pois jätetty kenttä säilyttää tallennetun arvonsa. null nollaa kentän, "appearance": null nollaa molemmat. Mustaa ja valkoista ei tallenneta; vastaus näyttää ne arvona null.
Jokainen koodivastaus sisältää kentän appearance, samoin kuin webhookit qr.created ja qr.updated.
Järjestys kuvareiteillä: ensin parametri, sitten tallennettu väri, sitten oletus. Siksi ?fg=000000 palauttaa värillisen koodin mustan painotiedoston.
Upotetut kuvat: Kuvan URL-osoite noudattaa tallennettuja värejä siltä osin kuin se ei itse määritä niitä parametreilla fg ja bg: URL-osoite ilman parametreja noudattaa molempia värejä, ?fg=000000 noudattaa vain taustaväriä ja ?ecc=Q noudattaa jälleen molempia. Värien muuttamisen jälkeen sivu, johon tällainen URL-osoite on upotettu, voi näyttää vielä vanhan kuvan: jopa 24 tunnin ajan, jos URL-osoite toimitti siihen asti oletuskuvan (musta valkoisella, virheenkorjaus M, ilman logoa), muuten jopa 5 minuutin ajan. Ratkaisuna on oma parametri URL-osoitteessa, joka muuttuu jokaisen värimuutoksen myötä, kuten ?v=2 tai koodin updated_at kuten Dashboard-näkymässä. Kuvareitit jättävät tuntemattomat parametrit huomiotta.
Virheenkorjausta ei koskaan tallenneta. Se valitaan latauskohtaisesti parametrilla ?ecc=.
Vain PATCH-metodilla: POST /v1/codes, eräajo (batch) ja tuonti hylkäävät kentän appearance virhekoodilla 422.
PDF ja EPS piirtävät tallennetut värit painoväreinä, aivan kuten parametritkin. Koska valkoista ei koskaan tallenneta, koodi, jossa on tallennettu etualan väri, saa sinne valkoisen täytön, kuten SVG-tiedostossa.

Kontrastintarkistus

API tarkistaa parin, joka muodostuu pyynnöstä ja tallennetusta arvosta:

Taso	Milloin	Vastaus
`blocked`	kontrasti alle 1,5:1	`422`, mitään ei tallenneta
`critical`	alle 2:1 tai kirkkausero alle 0,30; varoitus yhdessä logon kanssa; mikä tahansa läpinäkyvä tausta	`200` ja `meta.issues`
`warning`	alle 4:1 tai kirkkausero alle 0,50; vaaleat moduulit tummalla pohjalla	`200` ja `meta.issues`
ok	kaikki muu	`200`, `meta.issues` on tyhjä

Jokaisella merkinnällä kentässä meta.issues on code, severity, field, message ja valinnaisesti hints, kuten contrast_ratio — sama muoto kuin digitaalisen tuotepassin vaatimustenmukaisuusilmoituksilla. Läpinäkyvää taustaa ei koskaan estetä, koska vaalea koodi tummassa pakkauksessa on todellinen käyttötapaus. Tausta vaatii silti selvän kontrastin ja ympärilleen tyhjän 4 moduulin suoja-alueen.

Logon lataaminen ja poistaminen (POST ja DELETE /v1/codes/:id/logo) tekevät saman tarkistuksen tallennetuille väreille ja palauttavat löydökset samalla tavalla kentässä meta.issues: logon kanssa varoituksesta tulee critical, ilman logoa se on jälleen varoitus.

Jos toinen pyyntö muuttaa samaa koodia samalla hetkellä, API soveltaa muutokset uusimpaan tilaan. Vasta kun tämä epäonnistuu kolme kertaa peräkkäin, se vastaa virheellä 409; asiakasohjelma lataa koodin tällöin uudelleen ja toistaa muutoksen.

Logo

`POST /v1/codes/:id/logo`

Multipart-pyyntö, kenttä file: PNG, JPEG tai WebP, enintään 1 MB, tunnistetaan magic bytes -tavuista. Normalisoi kuvan läpinäkyväksi 512×512-PNG-kuvaksi ja korvaa olemassa olevan logon.

curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/logo \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

Antwort (HTTP 201): päivitetty koodi, jossa logo_file_id on asetettu.

`DELETE /v1/codes/:id/logo`

Poistaa logon ja poistaa tallennetun objektin. Idempotentti — kutsu ilman olemassa olevaa logoa palauttaa silti 200.

Jos toinen pyyntö muuttaa saman koodin logoa samalla hetkellä (toinen lataus tai poisto), POST ja DELETE /v1/codes/:id/logo vastaavat virheellä 409 (errors/conflict) eivätkä muuta mitään; ladattu kuva hylätään. Lataa koodi uudelleen ja yritä uudelleen. Kaksi samanaikaista kutsua polkuun DELETE /v1/codes/:id/logo ei aiheuta konfliktia; molemmat palauttavat 200.

Jos se on asetettu, kaikki neljä formaattia — qr.svg, qr.png, qr.pdf ja qr.eps — upottavat logon pikselit ja nostavat virheenkorjauksen tasolle H. Täydellinen sopimus — mukaan lukien se, mikä muutos (lisääminen/poistaminen vs. korvaaminen) muuttaa pistekuviota — sekä tulostusohjeet löytyvät kohdasta Logo QR-koodissa.

Kommentit

Kommentit mahdollistavat palautesyklin toimistojen ja asiakkaiden välillä.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

Dashboard-kommentit liitetään ne luoneeseen käyttäjään (author_id); pelkillä API-avaimilla luodut kommentit jäävät ilman tekijää (author_id: null). Kommentin saa poistaa vain sen tekijä itse tai org_admin/ws_admin — pelkillä API-avaimilla voi poistaa ainoastaan sellaisia tekijättömiä kommentteja, jotka on luotu API:n kautta.

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'