API pro QR kódy

Přehled

API pro kódy je srdcem qr3.app. Umožňuje vám vytvářet, aktualizovat a mazat dynamické i statické QR kódy.

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

Závazný REST kontrakt

Následující kontrakt platí pro všechny klienty:

POST /v1/codes přijímá pouze typy url, vcard, wifi, email, sms a location. Pole jsou plochá: url; alespoň vcard_first_name nebo vcard_last_name; wifi_ssid; email_to; sms_phone; nebo location_lat a location_lng.
Dynamické mohou být pouze kódy url. Požadavky na vytvoření mohou volitelně obsahovat expires_at jako časový údaj ISO 8601; ab_enabled, ab_target_url_b a ab_weight_a (A/B cíle) jsou přípustné pro dynamické kódy url; redirect_after_expiry není součástí kontraktu vytvoření.
GET /v1/codes podporuje pouze limit, cursor a status (live, paused, flagged, draft).
POST /v1/codes/batch přijímá url, vcard a wifi. Limit je 10 pro Free, 500 pro Pro a 1 000 záznamů pro Business/Agency/Enterprise na požadavek. Kontroly URL běží synchronně nejvýše pro 50 položek URL; nad 50 je nutné skip_url_scan: true.

Vytvoření 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

Odpověď (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ódů

Typ	Popis	Povinná pole
`url`	URL webové stránky (dynamická nebo statická)	`url`
`vcard`	Vizitka (vCard 3.0)	`vcard_first_name` nebo `vcard_last_name`
`wifi`	Konfigurace Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Poloha (geo:)	`location_lat`, `location_lng`

Hromadné vytváření (Batch)

`POST /v1/codes/batch`

Vytvoří až 1 000 QR kódů v jediném požadavku. Ideální pro hromadné použití.

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

Odpověď (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
  }
}

Seznam QR kódů

`GET /v1/codes`

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

Query parametry:

Parametr	Typ	Výchozí	Popis
`cursor`	string	—	Kurzor pro stránkování (pagination)
`limit`	integer	20	Výsledků na stránku (max. 100)
`status`	string	—	Filtr: `live`, `paused`, `flagged`, `draft`

Načtení QR kódu

`GET /v1/codes/:id`

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

Aktualizace 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í kdykoli změnit cílovou URL — aniž byste museli QR kód znovu tisknout.

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

Vstupní stránka (Landing page) & externí odkazy

Pro dynamické url kódy můžete nastavit is_landing_page: true (při vytváření nebo pomocí PATCH). Skenování pak místo přesměrování zobrazí stránku hostovanou na qr3 s veřejnými soubory a externími odkazy daného kódu. Externí odkazy se předávají jako 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 odkazů na kód; label má 1–100 znaků; url musí být http(s) (≤ 2048 znaků).
Každá URL je kontrolována pomocí Google Web Risk — nebezpečná URL vrátí 422.
Pokud je služba Web Risk při ukládání nedostupná, odkaz je přesto přijat, ale je označen pro opětovnou kontrolu. Denní úloha (job) znovu kontroluje uložené odkazy (a ty, které byly vyhodnoceny jako bezpečné, pravidelně prověřuje) a automaticky pozastaví kód, pokud je některý odkaz později vyhodnocen jako nebezpečný.
"links": [] smaže všechny odkazy. Viz Průvodce vstupní stránkou.

Smazání QR kódu

`DELETE /v1/codes/:id`

Soft-delete — QR kód je archivován, data o skenování zůstávají zachována.

Druhý požadavek DELETE na stejný kód vrátí 404, i když oba požadavky dorazí ve stejný okamžik. Webhook qr.deleted je odeslán přesně jednou.

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

Stažení obrázků QR kódů

Všechny formáty obrázků jsou veřejně dostupné — není vyžadováno žádné ověření.

Formát	URL	Použití
SVG (vektor)	`/v1/codes/:code/qr.svg`	Web, škálování, digitální média
PNG (rastr)	`/v1/codes/:code/qr.png`	E-mail, prezentace
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Výchozí: čtvercový (pouze kód); `?format=a4` pro tiskový arch
EPS (vektor)	`/v1/codes/:code/qr.eps`	Profesionální tiskové procesy (Adobe, tiskárny)

Volitelné: ?size=N — velikost modulu v pixelech (2–20, výchozí: 4) pro SVG, PNG a EPS. PDF používá pevnou velikost modulu.

Pouze PDF: ?format=a4|square — formát stránky (výchozí: square — pouze kód + ochranná zóna (quiet zone), žádné bílé místo formátu A4; a4 pro tiskový arch formátu A4)

# 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

Barvy a korekce chyb

Všechny čtyři obrázkové trasy přijímají tři volitelné parametry. Platí pro toto jedno vyvolání a mají přednost před barvami uloženými u kódu (další část).

Parametr	Hodnoty	Výchozí	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` nebo `RGB`	`000000`	vykresluje se	vykresluje se jako tisková barva
`bg`	Hex jako `fg` nebo `transparent`	`ffffff`	vykresluje se	vykresluje se jako tisková barva
`ecc`	`L`, `M`, `Q`, `H`	`M`	aplikuje se	aplikuje se

Zápis: Na velikosti písmen nezáleží, # je volitelné. Při odeslání se kóduje jako %23.
Neplatné hodnoty se počítají jako nenastavené. ?fg=lila vrátí barvu uloženou v kódu, nebo normální černou, pokud žádná uložená není, s kódem 200 a nikdy ne chybu. Pouze výslovné ?fg=000000 vynutí černou.
bg=transparent vrátí SVG, PDF nebo EPS bez pozadí a PNG se skutečným alfa kanálem. Podklad, na který kód umístíte, musí být světlý a musí ponechat kolem dokola ochrannou zónu o velikosti 4 modulů. Tmavý kód na tmavém podkladu není čitelný.
PDF a EPS zapisují černou a šedou jako stupně šedi (pouze černý plát) a jakoukoli jinou barvu jako CMYK v celých procentech, například 1F4E79 jako C74 M36 Y0 K53. Jakmile je zvolena barva, leží za kódem a jeho ochrannou zónou neprůhledná výplň, bílá nebo v barvě bg, stejně jako v SVG. Bez barev zůstávají oba soubory beze změny. Převod a omezení: Barvy při tisku.
Čitelnost: Obrázková trasa nekontroluje kontrast. Doporučuje se poměr alespoň 4:1 a tmavé moduly na světlém pozadí. #1F4E79 na bílé má poměr 8,7:1, #ff6600 na bílé pouze 2,9:1.
ecc mění vzor bodů, nikoli obsah. Vytištěný kód funguje dál, staré a nové tiskové soubory se však nesmí míchat. Q nebo H činí kód robustnějším, například na vlnité lepence. Logo vždy vyžaduje H.
S logem zůstává plocha za logem bílá, a to i při barevném nebo průhledném pozadí.
Ukládání do mezipaměti: Pouze skutečný standardní obrázek (černý na bílém, korekce chyb M, bez loga) je doručován jako neměnný po dobu 24 hodin; jakékoli jiné vykreslení po dobu 5 minut. U PDF a EPS se jakékoli zadané pozadí počítá jako odchylka: bg=ffffff tam vykreslí bílou výplň, kterou standardní soubor nemá.
Plán: Barvy a korekce chyb jsou k dispozici v každém plánu, i v tom bezplatném.

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žení barev ke kódu

PATCH /v1/codes/:id ukládá barvy jako appearance ke kódu. Obrázkové routy je pak vykreslují ve výchozím nastavení, bez parametrů.

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

Odpověď (HTTP 200, zkráceno):

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

Hodnoty: foreground_color jako #RRGGBB, background_color jako #RRGGBB nebo transparent. Jiné klíče vrátí 400.
Sloučení: Vynechané pole si ponechá svou uloženou hodnotu. null resetuje jedno pole, "appearance": null obě. Černá a bílá se neukládají; odpověď je zobrazuje jako null.
Každá odpověď s kódem obsahuje appearance, stejně jako webhooky qr.created a qr.updated.
Pořadí v obrázkových routách: nejprve parametr, poté uložená barva, následně výchozí hodnota. ?fg=000000 proto vrátí černý tiskový soubor barevného kódu.
Vložené obrázky: URL adresa obrázku se řídí uloženými barvami, pokud je sama nenastavuje pomocí fg a bg: URL adresa bez parametrů u obou barev, ?fg=000000 u pozadí, ?ecc=Q rovněž u obou. Po změně barev může stránka, která takovou URL adresu vkládá, stále zobrazovat starý obrázek: po dobu až 24 hodin, pokud URL adresa do té doby doručovala výchozí obrázek (černý na bílém, korekce chyb M, bez loga), jinak po dobu až 5 minut. Nápravou je váš vlastní parametr v URL adrese, který se mění s každou změnou barvy, například ?v=2 nebo updated_at kódu jako v dashboardu. Neznámé parametry obrázkové routy ignorují.
Oprava chyb se nikdy neukládá. Volí se při každém stažení pomocí ?ecc=.
Pouze přes PATCH: POST /v1/codes, batch a import odmítnou appearance s kódem 422.
PDF a EPS vykreslují uložené barvy jako tiskové barvy, stejně jako parametry. Protože bílá se nikdy neukládá, kód s uloženou barvou popředí tam získá bílou výplň, stejně jako v SVG.

Kontrola kontrastu

API kontroluje dvojici, která vyplývá z požadavku a uložené hodnoty:

Úroveň	Kdy	Odpověď
`blocked`	Kontrast pod 1,5:1	`422`, nic se neuloží
`critical`	pod 2:1 nebo rozdíl jasu pod 0,30; varování společně s logem; jakékoli transparentní pozadí	`200` s `meta.issues`
`warning`	pod 4:1 nebo rozdíl jasu pod 0,50; světlé moduly na tmavém pozadí	`200` s `meta.issues`
ok	cokoli jiného	`200`, `meta.issues` je prázdné

Každý záznam v meta.issues obsahuje code, severity, field, message a volitelně hints jako contrast_ratio — stejný formát jako zprávy o shodě digitálního pasu výrobku (DPP). Transparentní pozadí není nikdy zablokováno, protože světlý kód na tmavém obalu je reálný případ použití. Podklad přesto vyžaduje výrazný kontrast a kolem dokola volnou ochrannou zónu o velikosti 4 modulů.

Nahrání a odstranění loga (POST a DELETE /v1/codes/:id/logo) provádějí stejnou kontrolu uložených barev a také vracejí nálezy v meta.issues: s logem se varování stává critical, bez něj je to opět varování.

Pokud jiný požadavek změní stejný kód ve stejném okamžiku, API aplikuje změny na nejnovější stav. Teprve když to selže třikrát za sebou, odpoví kódem 409; klient pak kód načte znovu a změnu opakuje.

Logo

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

Multipart požadavek, pole file: PNG, JPEG nebo WebP, maximálně 1 MB, rozpoznáno podle magic bytes. Normalizuje obrázek na transparentní PNG o rozměrech 512×512 a nahradí stávající logo.

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

Odpověď (HTTP 201): aktualizovaný kód s nastaveným logo_file_id.

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

Odstraní logo a smaže uložený objekt. Idempotentní — volání bez existujícího loga stále vrací 200.

Pokud jiný požadavek změní logo stejného kódu ve stejném okamžiku (druhé nahrání nebo odstranění), POST a DELETE /v1/codes/:id/logo odpoví kódem 409 (errors/conflict) a nezmění nic; nahraný obrázek je zahozen. Načtěte kód znovu a zkuste to ještě jednou. Dvě současná volání DELETE /v1/codes/:id/logo nepředstavují konflikt; obě vrátí 200.

Pokud je nastaveno, všechny čtyři formáty — qr.svg, qr.png, qr.pdf a qr.eps — vloží pixely loga a zvýší úroveň korekce chyb na H. Kompletní specifikace — včetně toho, která změna (přidání/odstranění vs. nahrazení) mění vzor bodů — a také pokyny pro tisk jsou k dispozici v sekci Logo v QR kódu.

Komentáře

Komentáře umožňují zpětnou vazbu mezi agenturami a klienty.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

Komentáře v Dashboardu jsou přiřazeny vytvářejícímu uživateli (author_id); komentáře vytvořené pouze pomocí API klíčů zůstávají nepřiřazené (author_id: null). Smazat komentář smí pouze samotný autor nebo org_admin/ws_admin — samotné API klíče mohou mazat pouze nepřiřazené komentáře vytvořené přes 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 }'