QR-koodien API

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.

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`

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.

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