API pro QR kódy

Přehled

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

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

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 webu (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`

A/B testování

Otestujte dvě různé cílové URL s váženým přesměrování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
}

Expirace (platnost)

Platnost QR kódů může automaticky vypršet:

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

Po vypršení platnosti dojde buď k přesměrování na redirect_after_expiry, nebo se zobrazí stránka s chybou 410.

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í
`limit`	integer	20	Výsledky na stránku (max. 100)
`status`	string	—	Filtr: `live`, `paused`, `flagged`, `draft`

Získání 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`

Dynamické QR kódy umožňují kdykoli změnit cílovou URL — bez nutnosti 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" }'

Landing page a 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 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á délku 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í chybu 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 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 pro landing page.

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.

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

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

Všechny obrazové formáty jsou veřejně přístupné — 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 (Rastrový)	`/v1/codes/:code/qr.png`	E-mail, prezentace
PDF (Vektor)	`/v1/codes/:code/qr.pdf`	Standardní: č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 und 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, žá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

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`

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