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

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`

A/B tesztelés

Tesztelj két különböző cél-URL-t súlyozott átirányítással:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Lejárat (Expiry)

A QR-kódok automatikusan lejárhatnak:

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

A lejárat után a rendszer vagy a redirect_after_expiry címre irányít át, vagy egy 410-es hibaoldalt jelenít meg.

Kötegelt létrehozás

`POST /v1/codes/batch`

Akár 1000 QR-kódot is létrehoz egyetlen kérésben (Request). Ideális tömeges alkalmazásokhoz.

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`

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.

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

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`

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