API pre QR kódy

Záväzný REST kontrakt

Nasledujúci kontrakt platí pre všetkých klientov:

POST /v1/codes prijíma iba typy url, vcard, wifi, email, sms a location. Polia sú ploché: url; aspoň vcard_first_name alebo vcard_last_name; wifi_ssid; email_to; sms_phone; alebo location_lat a location_lng spolu.
Dynamické môžu byť iba kódy url. Požiadavky na vytvorenie môžu voliteľne obsahovať expires_at ako časovú pečiatku ISO 8601; ab_enabled, ab_target_url_b a ab_weight_a (A/B destinácie) sú prípustné pre dynamické kódy url; redirect_after_expiry nie je súčasťou kontraktu vytvorenia.
GET /v1/codes podporuje iba limit, cursor a status (live, paused, flagged, draft).
POST /v1/codes/batch prijíma url, vcard a wifi. Limit je 10 pre Free, 500 pre Pro a 1 000 záznamov pre Business/Agency/Enterprise na požiadavku. Kontroly URL bežia synchronne najviac pre 50 položiek URL; nad 50 je potrebné skip_url_scan: true.

Prehľad

API pre kódy je srdcom qr3.app. Umožňuje vám vytvárať, aktualizovať a mazať dynamické a statické QR kódy.

Základná URL: https://qr3.app/v1/codes

Vytvorenie QR kódu

`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

Odpoveď (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" }
}

Typy QR kódov

Typ	Popis	Povinné polia
`url`	URL adresa webu (dynamická alebo statická)	`url`
`vcard`	Vizitka (vCard 3.0)	`vcard_first_name` alebo `vcard_last_name`
`wifi`	Konfigurácia Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Poloha (geo:)	`location_lat`, `location_lng`

Hromadné vytváranie

`POST /v1/codes/batch`

Vytvorí až 1 000 QR kódov v jedinej požiadavke. Ideálne pre hromadné použitie.

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

Odpoveď (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
  }
}

Zoznam QR kódov

`GET /v1/codes`

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

Query parametre:

Parameter	Typ	Predvolené	Popis
`cursor`	string	—	Kurzor pre stránkovanie (pagination)
`limit`	integer	20	Počet výsledkov na stránku (max. 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

Získanie QR kódu

`GET /v1/codes/:id`

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

Aktualizácia QR kódu

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

Dynamické QR kódy umožňujú kedykoľvek zmeniť cieľovú URL adresu — bez nutnosti opätovnej tlače QR kódu.

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

Pristávacia stránka (Landing page) & externé odkazy

Pre dynamické url kódy môžete nastaviť is_landing_page: true (pri vytváraní alebo cez PATCH). Naskenovanie potom namiesto presmerovania zobrazí stránku hostovanú na qr3 s verejnými súbormi a externými odkazmi kódu. Externé odkazy sa odovzdávajú ako pole links:

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

0–20 odkazov na kód; label má 1–100 znakov; url musí byť http(s) (≤ 2048 znakov).
Každá URL adresa sa kontroluje pomocou Google Web Risk — nebezpečná URL vráti 422.
Ak je služba Web Risk pri ukladaní nedostupná, odkaz sa napriek tomu prijme, ale označí sa na opätovnú kontrolu. Denná úloha (job) znova kontroluje uložené odkazy (a pravidelne preveruje tie, ktoré boli vyhodnotené ako bezpečné) a automaticky pozastaví kód, ak sa odkaz neskôr ukáže ako nebezpečný.
"links": [] vymaže všetky odkazy. Pozrite si sprievodcu pristávacími stránkami.

Vymazanie QR kódu

`DELETE /v1/codes/:id`

Soft-delete (mäkké vymazanie) — QR kód sa archivuje, dáta o skenovaní zostanú zachované.

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

Stiahnutie QR obrázkov

Všetky formáty obrázkov sú verejne dostupné — nevyžaduje sa žiadna autentifikácia.

Formát	URL	Použitie
SVG (vektor)	`/v1/codes/:code/qr.svg`	Web, škálovanie, digitálne médiá
PNG (raster)	`/v1/codes/:code/qr.png`	E-mail, prezentácie
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Predvolené: štvorcový (iba kód); `?format=a4` pre tlačový hárok
EPS (vektor)	`/v1/codes/:code/qr.eps`	Profesionálna tlač (Adobe, tlačiarne)

Voliteľné: ?size=N — veľkosť modulu v pixeloch (2–20, predvolené: 4) pre SVG, PNG a EPS. PDF používa fixnú veľkosť modulu.

Iba PDF: ?format=a4|square — formát strany (predvolené: square — iba kód + ochranná zóna (quiet zone), bez bieleho miesta formátu A4; a4 pre A4 hárok pripravený na tlač)

# 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

Komentáre

Komentáre umožňujú spätnú väzbu medzi agentúrami a klientmi.

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