QR kodų API

Apžvalga

„Codes“ API yra „qr3.app“ šerdis. Su ja galite kurti, atnaujinti ir ištrinti dinaminius bei statinius QR kodus.

Bazinis URL: https://qr3.app/v1/codes

QR kodo kūrimas

`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

Atsakymas (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 kodų tipai

Tipas	Aprašymas	Privalomi laukai
`url`	Svetainės URL (dinaminis arba statinis)	`url`
`vcard`	Vizitinė kortelė (vCard 3.0)	`vcard_first_name` arba `vcard_last_name`
`wifi`	Wi-Fi konfigūracija	`wifi_ssid`
`email`	El. paštas (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Vieta (geo:)	`location_lat`, `location_lng`

A/B testavimas

Išbandykite du skirtingus tikslinius URL adresus su svoriniu nukreipimu:

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

Galiojimo pabaiga (Expiry)

QR kodų galiojimo laikas gali pasibaigti automatiškai:

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

Pasibaigus galiojimo laikui, vartotojas nukreipiamas į redirect_after_expiry arba parodomas 410 puslapis.

Masinis kūrimas (Batch)

`POST /v1/codes/batch`

Sukurkite iki 1 000 QR kodų vienoje užklausoje. Idealiai tinka masiniam naudojimui.

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

Atsakymas (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 kodų sąrašas

`GET /v1/codes`

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

Užklausos parametrai (Query Parameters):

Parametras	Tipas	Numatytoji reikšmė	Aprašymas
`cursor`	string	—	Žymeklis (cursor) puslapiavimui
`limit`	integer	20	Rezultatų skaičius puslapyje (maks. 100)
`status`	string	—	Filtras: `live`, `paused`, `flagged`, `draft`

QR kodo gavimas

`GET /v1/codes/:id`

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

QR kodo atnaujinimas

`PATCH /v1/codes/:id`

Dinaminiai QR kodai leidžia bet kada pakeisti tikslinį URL adresą – nereikia iš naujo spausdinti QR kodo.

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

Nukreipimo puslapis ir išorinės nuorodos

Dinaminiams url kodams galite nustatyti is_landing_page: true (kuriant arba naudojant PATCH). Tokiu atveju nuskaičius kodą, užuot nukreipus tiesiogiai, bus parodytas „qr3“ priglobtas puslapis su kodo viešaisiais failais ir išorinėmis nuorodomis. Išorinės nuorodos perduodamos kaip links masyvas:

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

Nuo 0 iki 20 nuorodų vienam kodui; label ilgis yra 1–100 simbolių; url privalo būti http(s) (≤ 2048 simbolių).
Kiekvienas URL adresas yra tikrinamas naudojant Google Web Risk – nesaugus URL grąžina 422.
Jei išsaugojimo metu Web Risk yra nepasiekiamas, nuoroda vis tiek priimama, tačiau pažymima pakartotiniam patikrinimui. Kasdien vykdomas procesas iš naujo patikrina išsaugotas nuorodas (o saugias nuorodas tikrina periodiškai) ir automatiškai sustabdo kodą, jei vėliau nuoroda pripažįstama nesaugia.
"links": [] ištrina visas nuorodas. Žr. Nukreipimo puslapio vadovą.

QR kodo ištrynimas

`DELETE /v1/codes/:id`

Švelnus ištrynimas (Soft-Delete) – QR kodas archyvuojamas, nuskaitymo duomenys išsaugomi.

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

QR kodų paveikslėlių atsisiuntimas

Visi paveikslėlių formatai yra viešai prieinami – autentifikavimas nereikalingas.

Formatas	URL	Naudojimas
SVG (vektorinis)	`/v1/codes/:code/qr.svg`	Web, mastelio keitimas, skaitmeninė terpė
PNG (rastrinis)	`/v1/codes/:code/qr.png`	El. paštas, prezentacijos
PDF (vektorinis)	`/v1/codes/:code/qr.pdf`	Standartinis: kvadratinis (tik kodas); `?format=a4` spausdinimo lapui
EPS (vektorinis)	`/v1/codes/:code/qr.eps`	Profesionalūs spaudos procesai (Adobe, spaustuvės)

Pasirinktinai: ?size=N – modulio dydis pikseliais (2–20, numatytasis: 4) SVG, PNG ir EPS formatams. PDF naudoja fiksuotą modulio dydį.

Tik PDF: ?format=a4|square – puslapio formatas (numatytasis: square – tik kodas + ramybės zona (Quiet Zone), be A4 tuščios vietos; a4 spausdinimui paruoštam A4 lapui)

# 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

Komentarai

Komentarai leidžia kurti grįžtamojo ryšio ciklus tarp agentūrų ir klientų.

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