QR kodų API

Privaloma REST sutartis

Ši sutartis taikoma visiems klientams:

POST /v1/codes priima tik url, vcard, wifi, email, sms ir location tipus. Laukai yra plokšti: url; bent vcard_first_name arba vcard_last_name; wifi_ssid; email_to; sms_phone; arba abu location_lat ir location_lng.
Dinaminiai gali būti tik url kodai. Kūrimo užklausose pasirinktinai gali būti expires_at su ISO 8601 laiko žyma; ab_enabled, ab_target_url_b ir ab_weight_a (A/B paskirties vietos) priimami dinaminiams url kodams; redirect_after_expiry nėra kūrimo sutarties dalis.
GET /v1/codes palaiko tik limit, cursor ir status (live, paused, flagged, draft).
POST /v1/codes/batch priima url, vcard ir wifi. Riba yra 10 Free, 500 Pro ir 1 000 Business/Agency/Enterprise planams vienoje užklausoje. URL tikrinimai sinchroniškai vykdomi daugiausia 50 URL elementų; viršijus 50 būtina skip_url_scan: true.

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`

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`

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.

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