API pre QR kódy

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

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.

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

Druhé DELETE na rovnaký kód vráti 404, aj keď obe požiadavky prídu v rovnakom čase. Webhook qr.deleted sa odošle presne raz.

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

Farby a korekcia chýb

Všetky štyri obrazové trasy prijímajú tri voliteľné parametre. Platia pre toto jedno vyžiadanie a majú prednosť pred farbami uloženými v kóde (nasledujúca časť).

Parameter	Hodnoty	Predvolené	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` alebo `RGB`	`000000`	vykresľuje sa	vykresľuje sa ako tlačová farba
`bg`	Hex ako `fg` alebo `transparent`	`ffffff`	vykresľuje sa	vykresľuje sa ako tlačová farba
`ecc`	`L`, `M`, `Q`, `H`	`M`	aplikuje sa	aplikuje sa

Spôsob zápisu: Na veľkosti písmen nezáleží, # je voliteľné. Ak sa odosiela, musí byť zakódované ako %23.
Neplatné hodnoty sa počítajú ako nenastavené. ?fg=lila vráti farbu uloženú v kóde, alebo normálnu čiernu, ak nie je uložená žiadna farba, s kódom 200 a nikdy nie chybu. Iba explicitné ?fg=000000 vynúti čiernu.
bg=transparent vráti SVG, PDF alebo EPS bez pozadia a PNG so skutočným alfa kanálom. Podklad, na ktorý kód umiestnite, musí byť svetlý a musí zo všetkých strán ponechať voľnú tichú zónu s veľkosťou 4 modulov. Tmavý kód na tmavom podklade nie je čitateľný.
PDF a EPS zapisujú čiernu a sivú ako odtiene sivej (iba čierna platňa) a akúkoľvek inú farbu ako CMYK v celých percentách, napríklad 1F4E79 ako C74 M36 Y0 K53. Akonáhle je zvolená farba, za kódom a jeho tichou zónou sa nachádza nepriehľadná výplň, biela alebo vo farbe bg, rovnako ako v SVG. Bez farieb zostávajú oba súbory nezmenené. Prevod a obmedzenia: Farby v tlači.
Čitateľnosť: Obrazová trasa nekontroluje kontrast. Odporúča sa pomer aspoň 4:1 a tmavé moduly na svetlom pozadí. #1F4E79 na bielej má pomer 8,7:1, #ff6600 na bielej iba 2,9:1.
ecc mení vzor bodov, nie obsah. Vytlačený kód funguje aj naďalej, staré a nové tlačové súbory sa však nesmú miešať. Q alebo H robia kód robustnejším, napríklad na vlnitej lepenke. Logo vždy vyžaduje H.
S logom zostáva plocha za logom biela, a to aj pri farebnom alebo transparentnom pozadí.
Ukladanie do vyrovnávacej pamäte: Iba skutočný štandardný obrázok (čierny na bielom, korekcia chýb M, bez loga) sa doručuje ako nemenný po dobu 24 hodín; akékoľvek iné vykreslenie po dobu 5 minút. Pri PDF a EPS sa akékoľvek zadané pozadie považuje za odchýlku: bg=ffffff tam vykreslí bielu výplň, ktorú štandardný súbor nemá.
Tarifa: Farby a korekcia chýb sú k dispozícii v každej tarife, aj v bezplatnej.

cURL
TypeScript SDK

# Dark blue code on white
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79" -o qr-blue.svg

# Transparent PNG for a layout on a light surface
curl "https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10&bg=transparent" -o qr-transparent.png

# More robust for corrugated board: error correction Q
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?ecc=Q" -o qr-q.pdf

// @qr3/sdk 1.2.0 or later — imageUrl() only builds the URL, it sends no request
// Dark blue code on white
qr3.codes.imageUrl('r7f3Kx', { format: 'svg', fg: '1F4E79' });
// → https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79

// Transparent PNG for a layout on a light surface
qr3.codes.imageUrl('r7f3Kx', { format: 'png', size: 10, bg: 'transparent' });

// More robust for corrugated board: error correction Q
qr3.codes.imageUrl('r7f3Kx', { format: 'pdf', ecc: 'Q' });

Uloženie farieb v kóde

PATCH /v1/codes/:id ukladá farby ako appearance v kóde. Obrázkové trasy ich potom predvolene vykresľujú bez parametrov.

cURL
TypeScript SDK

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance": {"foreground_color": "#1F4E79"}}'

// @qr3/sdk 1.2.0 or later
const code = await qr3.codes.update('qr_a1b2c3d4', {
  appearance: { foreground_color: '#1F4E79' },
});
code.appearance; // { foreground_color: '#1F4E79', background_color: null }
code.issues;     // contrast check findings, absent when there are none

Odpoveď (HTTP 200, skrátená):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "appearance": { "foreground_color": "#1F4E79", "background_color": null }
  },
  "meta": { "request_id": "req_xyz", "issues": [] }
}

Hodnoty: foreground_color ako #RRGGBB, background_color ako #RRGGBB alebo transparent. Iné kľúče vrátia 400.
Zlúčenie: Vynechané pole si zachová svoju uloženú hodnotu. null resetuje jedno pole, "appearance": null obe. Čierna a biela sa neukladajú; odpoveď ich zobrazuje ako null.
Každá odpoveď s kódom obsahuje appearance, rovnako ako webhooky qr.created a qr.updated.
Poradie v obrázkových trasách: najprv parameter, potom uložená farba, potom predvolená hodnota. ?fg=000000 preto vráti čierny tlačový súbor farebného kódu.
Vložené obrázky: Adresa URL obrázka sa riadi uloženými farbami všade tam, kde ich sama nenastavuje pomocou fg a bg: adresa URL bez parametrov pre obe farby, ?fg=000000 pre pozadie, ?ecc=Q takisto pre obe. Po zmene farby môže stránka, ktorá takúto adresu URL vkladá, stále zobrazovať starý obrázok: až 24 hodín, ak adresa URL dovtedy poskytovala predvolený obrázok (čierny na bielom, korekcia chýb M, bez loga), inak až 5 minút. Nápravou je vlastný parameter v adrese URL, ktorý sa mení s každou zmenou farby, napríklad ?v=2 alebo updated_at kódu ako v dashboarde. Obrázkové trasy neznáme parametre ignorujú.
Oprava chýb sa nikdy neukladá. Volí sa pri každom stiahnutí pomocou ?ecc=.
Iba cez PATCH: POST /v1/codes, batch a import odmietnu appearance s kódom 422.
PDF a EPS vykresľujú uložené farby ako tlačové farby, rovnako ako parametre. Pretože biela sa nikdy neukladá, kód s uloženou farbou popredia tam získa bielu výplň, rovnako ako v SVG.

Kontrola kontrastu

API kontroluje pár, ktorý vyplýva z požiadavky a uloženej hodnoty:

Úroveň	Kedy	Odpoveď
`blocked`	kontrast pod 1,5:1	`422`, nič sa neuloží
`critical`	pod 2:1 alebo rozdiel jasu pod 0,30; varovanie spolu s logom; akékoľvek transparentné pozadie	`200` s `meta.issues`
`warning`	pod 4:1 alebo rozdiel jasu pod 0,50; svetlé moduly na tmavom pozadí	`200` s `meta.issues`
ok	všetko ostatné	`200`, `meta.issues` je prázdne

Každý záznam v meta.issues má code, severity, field, message a voliteľne hints ako contrast_ratio — rovnaký formát ako správy o zhode pre digitálny pas produktu (DPP). Transparentné pozadie sa nikdy nezablokuje, pretože svetlý kód na tmavom obale je reálny prípad použitia. Podklad však stále vyžaduje výrazný kontrast a okolo seba voľnú ochrannú zónu s veľkosťou 4 modulov.

Nahrávanie a odstraňovanie loga (POST a DELETE /v1/codes/:id/logo) vykonávajú rovnakú kontrolu uložených farieb a taktiež vracajú nálezy v meta.issues: s logom sa varovanie zmení na critical, bez loga je to opäť varovanie.

Ak iná požiadavka zmení rovnaký kód v rovnakom okamihu, API aplikuje zmeny na najnovší stav. Až keď to zlyhá trikrát za sebou, odpovie s kódom 409; klient potom kód znova načíta a zmenu zopakuje.

Logo

`POST /v1/codes/:id/logo`

Multipart požiadavka, pole file: PNG, JPEG alebo WebP, maximálne 1 MB, rozpoznané podľa magic bytes. Normalizuje obrázok na transparentné 512×512-PNG a nahradí existujúce logo.

curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/logo \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

Antwort (HTTP 201): aktualizovaný kód s nastaveným logo_file_id.

`DELETE /v1/codes/:id/logo`

Odstráni logo a vymaže uložený objekt. Idempotentné — volanie bez existujúceho loga naďalej vracia 200.

Ak iná požiadavka zmení logo rovnakého kódu v rovnakom okamihu (druhé nahranie alebo odstránenie), POST a DELETE /v1/codes/:id/logo odpovedia s kódom 409 (errors/conflict) a nezmenia nič; nahraný obrázok sa zahodí. Načítajte kód znova a skúste to znova. Dve súčasné volania DELETE /v1/codes/:id/logo nepredstavujú konflikt; obe vrátia 200.

Ak je nastavené, všetky štyri formáty — qr.svg, qr.png, qr.pdf a qr.eps — vložia pixely loga a zvýšia korekciu chýb na H. Kompletná špecifikácia — vrátane toho, ktorá zmena (pridanie/odstránenie vs. nahradenie) mení vzor bodov — ako aj pokyny na tlač nájdete v časti Logo v QR kóde.

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`

Komentáre v Dashboarde sa priraďujú používateľovi, ktorý ich vytvoril (author_id); komentáre vytvorené prostredníctvom samotných API kľúčov zostávajú nepriradené (author_id: null). Vymazať komentár môže iba samotný autor alebo org_admin/ws_admin — samotné API kľúče môžu vymazať iba nepriradené komentáre vytvorené cez API.

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