QR-koodide API

Ülevaade

Codes API on qr3.app süda. Selle abil saad luua, uuendada ja kustutada dünaamilisi ning staatilisi QR-koode.

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

QR-koodi loomine

`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

Vastus (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-koodi tüübid

Tüüp	Kirjeldus	Kohustuslikud väljad
`url`	Veebisaidi URL (dünaamiline või staatiline)	`url`
`vcard`	Visiitkaart (vCard 3.0)	`vcard_first_name` või `vcard_last_name`
`wifi`	Wi-Fi konfiguratsioon	`wifi_ssid`
`email`	E-post (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Asukoht (geo:)	`location_lat`, `location_lng`

A/B-testimine

Testi kahte erinevat siht-URL-i kaalutud ümbersuunamisega:

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

Aegumine (Expiry)

QR-koodid võivad automaatselt aeguda:

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

Pärast aegumist suunatakse kasutaja kas aadressile redirect_after_expiry või kuvatakse 410-leht.

Massloomine (Batch)

`POST /v1/codes/batch`

Loob kuni 1000 QR-koodi ühe päringuga. Ideaalne massrakenduste jaoks.

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

Vastus (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-koodide nimekiri

`GET /v1/codes`

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

Päringu parameetrid (Query parameters):

Parameeter	Tüüp	Vaikimisi	Kirjeldus
`cursor`	string	—	Kursor lehekülgede jaotamiseks (pagination)
`limit`	integer	20	Tulemusi lehe kohta (maksimaalselt 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

QR-koodi hankimine

`GET /v1/codes/:id`

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

QR-koodi uuendamine

`PATCH /v1/codes/:id`

Dünaamilised QR-koodid võimaldavad siht-URL-i igal ajal muuta — ilma et peaksid QR-koodi uuesti trükkima.

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

Maandumisleht ja välised lingid

Dünaamiliste url-koodide puhul saad määrata is_landing_page: true (loomisel või PATCH kaudu). Skannimine kuvab siis qr3 majutatud lehte koodi avalike failide ja väliste linkidega, selle asemel et edasi suunata. Välised lingid edastatakse massiivina links:

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

0–20 linki koodi kohta; label on 1–100 märki; url peab olema http(s) (≤ 2048 märki).
Iga URL-i kontrollitakse Google Web Risk teenusega — ebaturbe URL tagastab vastuse 422.
Kui Web Risk pole salvestamise ajal kättesaadav, võetakse link siiski vastu, kuid märgistatakse uueks kontrolliks. Igapäevane taustatöö kontrollib salvestatud linke uuesti (ja puhtaks liigitatud linke regulaarselt üle) ja peatab koodi automaatselt, kui mõni link tuvastatakse hiljem ebaturbana.
"links": [] kustutab kõik lingid. Vaata maandumislehe juhendit.

QR-koodi kustutamine

`DELETE /v1/codes/:id`

Pehme kustutamine (Soft-Delete) — QR-kood arhiveeritakse, skannimisandmed säilivad.

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

QR-piltide allalaadimine

Kõik pildivormingud on avalikult kättesaadavad — autentimist pole vaja.

Vorming	URL	Kasutusala
SVG (vektor)	`/v1/codes/:code/qr.svg`	Veeb, skaleerimine, digitaalne
PNG (raster)	`/v1/codes/:code/qr.png`	E-post, esitlused
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Vaikimisi: ruudukujuline (ainult kood); `?format=a4` trükilehe jaoks
EPS (vektor)	`/v1/codes/:code/qr.eps`	Professionaalsed trükitöövood (Adobe, trükikojad)

Valikuline: ?size=N — mooduli suurus pikslites (2–20, vaikimisi: 4) SVG, PNG ja EPS jaoks. PDF kasutab fikseeritud mooduli suurust.

Ainult PDF: ?format=a4|square — lehevorming (vaikimisi: square — ainult kood + turvaala (Quiet Zone), ilma A4 valge alata; a4 trükivalmis A4-lehe jaoks)

# 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

Kommentaarid

Kommentaarid võimaldavad tagasisideahelaid agentuuride ja klientide vahel.

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