API pro QR kódy

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.

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

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.

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

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