API pre QR kódy

Prehľad

API pre kódy je srdcom qr3.app. Pomocou nej môžete 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 webovej stránky (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`

A/B testovanie

Otestujte dve rôzne cieľové URL s váženým presmerovaním:

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

Expirácia (Expiry)

QR kódy môžu expirovať automaticky:

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

Po expirácii dôjde buď k presmerovaniu na redirect_after_expiry, alebo sa zobrazí stránka s kódom 410.

Hromadné vytváranie (Batch)

`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	Výsledky 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`

Dynamické QR kódy umožňujú kedykoľvek zmeniť cieľovú URL — 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 je kontrolovaná pomocou Google Web Risk — nebezpečná URL vráti 422.
Ak je služba Web Risk pri ukladaní nedostupná, odkaz sa napriek tomu akceptuje, 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 — 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 obrázkov QR kódov

Všetky formáty obrázkov sú verejne prístupné — 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álne tlačové procesy (Adobe, tlačiarne)

Voliteľné: ?size=N — veľkosť modulu v pixeloch (2 – 20, predvolené: 4) pre SVG, PNG und 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), žiadne biele miesto 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 }'