QR-koodide API

Siduv REST-leping

Järgmine leping kehtib kõigile klientidele:

POST /v1/codes aktsepteerib ainult tüüpe url, vcard, wifi, email, sms ja location. Väljad on tasapinnalised: url; vähemalt vcard_first_name või vcard_last_name; wifi_ssid; email_to; sms_phone; või mõlemad location_lat ja location_lng.
Ainult url-koodid võivad olla dünaamilised. Loomistaotlused võivad soovi korral sisaldada expires_at ISO 8601 ajatemplina; ab_enabled, ab_target_url_b ja ab_weight_a (A/B sihtkohad) on lubatud dünaamiliste url-koodide puhul; redirect_after_expiry ei kuulu loomislepingusse.
GET /v1/codes toetab ainult limit, cursor ja status (live, paused, flagged, draft).
POST /v1/codes/batch aktsepteerib url, vcard ja wifi. Piirang on Free puhul 10, Pro puhul 500 ning Business/Agency/Enterprise puhul 1 000 kirjet päringu kohta. URL-i skannid töötavad sünkroonselt kuni 50 URL-i kirje puhul; üle 50 nõuab skip_url_scan: true.

Ü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`

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

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`

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.

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