QR-kódok API

Áttekintés

A Codes API a qr3.app szíve. Segítségével dinamikus és statikus QR-kódokat hozhatsz létre, frissíthetsz és törölhetsz.

Bázis URL: https://qr3.app/v1/codes

Kötelező REST-szerződés

Az alábbi szerződés minden kliensre érvényes:

A POST /v1/codes csak az url, vcard, wifi, email, sms és location típusokat fogadja el. A mezők laposak: url; legalább vcard_first_name vagy vcard_last_name; wifi_ssid; email_to; sms_phone; illetve location_lat és location_lng együtt.
Csak az url kódok lehetnek dinamikusak. A létrehozási kérések opcionálisan tartalmazhatnak expires_at mezőt ISO 8601 időbélyeggel; Az ab_enabled, ab_target_url_b és ab_weight_a (A/B célok) dinamikus url kódoknál megengedettek; a redirect_after_expiry nem része a létrehozási szerződésnek.
A GET /v1/codes csak a limit, cursor és status paramétereket támogatja (live, paused, flagged, draft).
A POST /v1/codes/batch az url, vcard és wifi típusokat fogadja el. A korlát Free esetén 10, Pro esetén 500, Business/Agency/Enterprise esetén pedig 1 000 rekord kérésenként. Az URL-vizsgálatok legfeljebb 50 URL-elemnél futnak szinkron módon; 50 felett skip_url_scan: true szükséges.

QR-kód létrehozása

`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

Válasz (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" }
}

QR-kód típusok

Típus	Leírás	Kötelező mezők
`url`	Weboldal URL (dinamikus vagy statikus)	`url`
`vcard`	Névjegykártya (vCard 3.0)	`vcard_first_name` vagy `vcard_last_name`
`wifi`	Wi-Fi konfiguráció	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Helyszín (geo:)	`location_lat`, `location_lng`

Kötegelt létrehozás

`POST /v1/codes/batch`

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

Válasz (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
  }
}

QR-kódok listázása

`GET /v1/codes`

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

Query paraméterek:

Paraméter	Típus	Alapértelmezett	Leírás
`cursor`	string	—	Kurzor a lapozáshoz (Pagination)
`limit`	integer	20	Találatok száma oldalanként (max. 100)
`status`	string	—	Szűrő: `live`, `paused`, `flagged`, `draft`

QR-kód lekérése

`GET /v1/codes/:id`

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

QR-kód frissítése

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

A dinamikus QR-kódok lehetővé teszik a cél-URL bármikori módosítását — anélkül, hogy a QR-kódot újra kellene nyomtatni.

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 és külső linkek

Dinamikus url kódok esetén beállíthatod az is_landing_page: true értéket (létrehozáskor vagy PATCH segítségével). A beolvasás ekkor az átirányítás helyett egy a qr3 által hosztolt oldalt jelenít meg a kódhoz tartozó nyilvános fájlokkal és külső linkekkel. A külső linkeket egy links tömbként (array) kell átadni:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

Kódonként 0–20 link; a label 1–100 karakter; az url formátuma http(s) kell legyen (≤ 2048 karakter).
Minden URL-t ellenőriz a Google Web Risk — a nem biztonságos URL 422-es hibát ad.
Ha a Web Risk nem érhető el a mentés során, a linket a rendszer elfogadja, de megjelöli újraellenőrzésre. Egy napi rendszerességgel futó feladat (job) újraellenőrzi a mentett linkeket (és a korábban biztonságosnak ítélteket is rendszeresen felülvizsgálja), és automatikusan szünetelteti a kódot, ha egy linket később nem biztonságosnak minősít.
A "links": [] törli az összes linket. Lásd a Landing page útmutatót.

QR-kód törlése

`DELETE /v1/codes/:id`

Soft-delete (szoftveres törlés) — a QR-kód archiválásra kerül, a beolvasási (scan) adatok megmaradnak.

Egy ugyanarra a kódra vonatkozó második DELETE kérés 404-es választ ad, még akkor is, ha mindkét kérés egyszerre érkezik be. A qr.deleted webhook pontosan egyszer kerül elküldésre.

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

QR-képek letöltése

Minden képformátum nyilvánosan elérhető — nincs szükség hitelesítésre.

Formátum	URL	Felhasználás
SVG (vektoros)	`/v1/codes/:code/qr.svg`	Web, skálázás, digitális
PNG (raszteres)	`/v1/codes/:code/qr.png`	E-mail, prezentációk
PDF (vektoros)	`/v1/codes/:code/qr.pdf`	Alapértelmezett: négyzetes (csak a kód); `?format=a4` nyomtatási laphoz
EPS (vektoros)	`/v1/codes/:code/qr.eps`	Professzionális nyomtatási munkafolyamatok (Adobe, nyomdák)

Opcionális: ?size=N — Modulméret pixelben (2–20, alapértelmezett: 4) SVG, PNG és EPS formátumokhoz. A PDF fix modulméretet használ.

Csak PDF: ?format=a4|square — Oldalformátum (alapértelmezett: square — csak a kód + Quiet Zone, nincs A4-es fehér margó; a4 nyomtatásra kész A4-es laphoz)

# 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

Színek és hibajavítás

Mind a négy képútvonal három opcionális paramétert fogad el. Ezek erre az egyetlen lekérésre érvényesek, és felülbírálják a kódhoz mentett színeket (következő szakasz).

Paraméter	Értékek	Alapértelmezett	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` vagy `RGB`	`000000`	kirajzolásra kerül	nyomdai színként kerül kirajzolásra
`bg`	Hex mint a `fg` vagy `transparent`	`ffffff`	kirajzolásra kerül	nyomdai színként kerül kirajzolásra
`ecc`	`L`, `M`, `Q`, `H`	`M`	érvényesül	érvényesül

Írásmód: A kis- és nagybetűk nem számítanak, a # opcionális. Ha elküldöd, %23 formában kell kódolni.
Az érvénytelen értékek nem beállítottnak számítanak. A ?fg=lila a kódon tárolt színt adja vissza, tárolt szín hiányában pedig a normál feketét, 200-as kóddal és soha nem hibával. Csak egy kifejezett ?fg=000000 kényszeríti ki a feketét.
bg=transparent háttér nélküli SVG-t, PDF-et vagy EPS-t, valamint valódi alfacsatornával rendelkező PNG-t eredményez. A felületnek, amelyre a kód kerül, világosnak kell lennie, és körös-körül 4 modulnyi csendes zónát szabadon kell hagyni. A sötét alapon lévő sötét kód nem olvasható.
PDF és EPS a feketét és a szürkét szürkeárnyalatosként (csak a fekete lemezen), minden más színt pedig egész százalékos CMYK-ként ír ki, például az 1F4E79 kódot C74 M36 Y0 K53 formában. Amint kiválasztasz egy színt, a kód és annak csendes zónája mögött egy átlátszatlan kitöltés jelenik meg, fehér vagy a bg színében, akárcsak az SVG esetében. Színek nélkül mindkét fájl változatlan marad. Konverzió és korlátok: Nyomtatási színek.
Kontraszt: A képútvonal ezt nem ellenőrzi. Legalább 4:1 arány, valamint világos alapon sötét modulok használata javasolt. A #1F4E79 fehér alapon 8,7:1 arányú, míg a #ff6600 fehér alapon mindössze 2,9:1.
ecc a pontmintázatot változtatja meg, nem a tartalmat. A már kinyomtatott kód továbbra is működik, de a régi és az új nyomtatási fájlokat ne keverd. A Q vagy H robusztusabbá teszi a kódot, például hullámkartonon. Logó használata esetén mindig kötelező a H.
Logóval a logó mögötti terület fehér marad, színes vagy átlátszó háttér esetén is.
Gyorsítótár (Cache): Csak a tényleges alapértelmezett kép (fekete fehéren, M hibajavítás, logó nélkül) kerül 24 órára megváltoztathatatlan módon kiszolgálásra; minden egyéb megjelenítés 5 percig. PDF és EPS esetén minden megadott háttér eltérésnek számít: a bg=ffffff egy olyan fehér kitöltést rajzol oda, amellyel az alapértelmezett fájl nem rendelkezik.
Díjcsomag: A színek és a hibajavítás minden díjcsomagban elérhetők, az ingyenesben is.

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

Színek mentése a kódhoz

A PATCH /v1/codes/:id elmenti a színeket appearance-ként a kódhoz. A kép-útvonalak ezután alapértelmezés szerint, paraméterek nélkül rajzolják ki őket.

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

Válasz (HTTP 200, rövidítve):

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

Értékek: foreground_color mint #RRGGBB, background_color mint #RRGGBB vagy transparent. Más kulcsok 400-as hibát eredményeznek.
Összefésülés: Egy elhagyott mező megtartja a mentett értékét. A null visszaállít egy mezőt, a "appearance": null mindkettőt. A fekete és a fehér nem kerül mentésre; a válaszban null-ként jelennek meg.
Minden kód-válasz tartalmazza az appearance mezőt, ahogy a qr.created és qr.updated webhookok is.
Sorrend a kép-útvonalakban: először a paraméter, majd a mentett szín, végül az alapértelmezett. A ?fg=000000 ezért egy színes kód fekete nyomtatási fájlját adja vissza.
Beágyazott képek: Egy kép-URL követi a tárolt színeket mindenhol, ahol saját maga nem állítja be azokat az fg és bg paraméterekkel: egy paraméterek nélküli URL mindkét színnél, a ?fg=000000 a háttérnél, a ?ecc=Q szintén mindkettőnél. Egy színváltoztatás után az ilyen URL-t beágyazó oldal még mutathatja a régi képet: legfeljebb 24 órán keresztül, ha az URL addig az alapértelmezett képet adta vissza (fekete fehéren, hibajavítás M, logó nélkül), egyébként legfeljebb 5 percig. A megoldás egy saját paraméter az URL-ben, amely minden színváltoztatással módosul, például ?v=2 vagy a kód updated_at értéke, mint a Dashboardon. A kép-útvonalak figyelmen kívül hagyják az ismeretlen paramétereket.
Hibajavítás soha nem kerül mentésre. Ez letöltésenként a ?ecc= paraméterrel választható ki.
Csak PATCH útján: A POST /v1/codes, a batch és az import elutasítja az appearance mezőt 422-es hibával.
PDF és EPS a mentett színeket nyomdai színekként rajzolják ki, pontosan úgy, mint a paramétereket. Mivel a fehér szín soha nem kerül mentésre, a mentett előtérszínnel rendelkező kód ott fehér kitöltést kap, akárcsak az SVG-ben.

Kontrasztellenőrzés

Az API ellenőrzi a kérésből és a mentett értékből adódó párt:

Szint	Mikor	Válasz
`blocked`	Kontraszt 1,5:1 alatt	`422`, semmi sem kerül mentésre
`critical`	2:1 alatt vagy fényességkülönbség 0,30 alatt; figyelmeztetés logóval együtt; bármilyen átlátszó háttér	`200` a `meta.issues` mezővel
`warning`	4:1 alatt vagy fényességkülönbség 0,50 alatt; világos modulok sötét alapon	`200` a `meta.issues` mezővel
ok	minden más	`200`, a `meta.issues` üres

Minden meta.issues bejegyzés rendelkezik a code, severity, field, message és opcionálisan a hints (például contrast_ratio) mezőkkel — ez megegyezik a digitális termékútlevél megfelelőségi üzeneteinek formátumával. Az átlátszó háttér soha nem kerül blokkolásra, mivel a sötét csomagoláson lévő világos kód valós használati eset. Az aljzatnak mindenesetre jelentős kontrasztra és körös-körül egy 4 modulból álló szabad csendes zónára van szüksége.

A logó feltöltése és eltávolítása (POST és DELETE /v1/codes/:id/logo) ugyanúgy ellenőrzi a mentett színeket, és a megállapításokat szintén a meta.issues mezőben adja vissza: logóval a figyelmeztetés critical szintűvé válik, logó nélkül pedig ismét figyelmeztetés lesz.

Ha egy másik kérés ugyanabban a pillanatban módosítja ugyanazt a kódot, az API a legfrissebb állapotra alkalmazza a változtatásokat. Csak ha ez egymás után háromszor meghiúsul, akkor válaszol 409-es hibával; a kliens ekkor újratölti a kódot, és megismétli a módosítást.

Logó

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

Multipart kérés, file mező: PNG, JPEG vagy WebP, legfeljebb 1 MB, a magic byte-ok alapján felismerve. A képet egy transzparens 512×512-es PNG-re normalizálja, és lecseréli a meglévő logót.

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

Válasz (HTTP 201): a frissített kód, beállított logo_file_id értékkel.

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

Eltávolítja a logót és törli a tárolt objektumot. Idempotens — a meglévő logó nélküli hívás továbbra is 200-at ad vissza.

Ha egy másik kérés ugyanabban a pillanatban módosítja ugyanazon kód logóját (egy második feltöltés vagy egy eltávolítás), a POST és a DELETE /v1/codes/:id/logo 409-es (errors/conflict) hibával válaszol, és semmit sem változtat; a feltöltött kép elvetésre kerül. Töltsd be újra a kódot, és próbáld meg újra. A DELETE /v1/codes/:id/logo két egyidejű hívása nem jelent konfliktust, mindkettő 200-at ad vissza.

Ha be van állítva, mind a négy formátum — a qr.svg, a qr.png, a qr.pdf és a qr.eps — beágyazza a logó képpontjait, és a hibajavítást H szintre emeli. A teljes szerződés — beleértve azt is, hogy melyik változtatás (hozzáadás/eltávolítás vs. csere) módosítja a pontmintázatot —, valamint a nyomtatási útmutatók a Logó a QR-kódban oldalon találhatók.

Megjegyzések

A megjegyzések lehetővé teszik a visszajelzési folyamatokat az ügynökségek és az ügyfelek között.

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

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

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

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

A Dashboardon létrehozott megjegyzések az azokat létrehozó felhasználóhoz vannak rendelve (author_id); a tisztán API-kulcsokkal létrehozott megjegyzések hozzárendelés nélkül maradnak (author_id: null). Egy megjegyzést csak maga a szerző vagy egy org_admin/ws_admin törölhet — a tisztán API-kulcsok csak a hozzárendelés nélküli, API-n keresztül létrehozott megjegyzéseket törölhetik.

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