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

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`

A/B-testaus

Testaa kahta eri kohde-URL-osoitetta painotetulla uudelleenohjauksella:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Vanhentuminen (Expiry)

QR-koodit voivat vanhentua automaattisesti:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Vanhentumisen jälkeen käyttäjä joko ohjataan osoitteeseen redirect_after_expiry tai hänelle näytetään 410-sivu.

Eräluonti (Batch)

`POST /v1/codes/batch`

Luo jopa 1 000 QR-koodia yhdellä pyynnöllä. Ihanteellinen massakäyttöön.

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`

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.

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

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`

# 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 }'