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

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.

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.

Antrasis DELETE tam pačiam kodui grąžina 404, net jei abi užklausos gaunamos tuo pačiu metu. qr.deleted webhook pranešimas išsiunčiamas lygiai vieną kartą.

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

Spalvos ir klaidų taisymas

Visi keturi paveikslėlių maršrutai priima tris pasirinktinius parametrus. Jie galioja šiai konkrečiai užklausai ir turi pirmenybę prieš spalvas, išsaugotas kode (kitas skyrius).

Parametras	Reikšmės	Numatytoji	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` arba `RGB`	`000000`	piešiama	piešiama kaip spaudos spalva
`bg`	Hex, kaip `fg` arba `transparent`	`ffffff`	piešiama	piešiama kaip spaudos spalva
`ecc`	`L`, `M`, `Q`, `H`	`M`	veikia	veikia

Rašyba: Raidžių dydis nesvarbus, # yra pasirinktinis. Jei jį siunčiate, koduokite kaip %23.
Neteisingos reikšmės laikomos nenustatytomis. ?fg=lila grąžina kode išsaugotą spalvą, o jei spalva neišsaugota – įprastą juodą, su kodu 200 ir niekada negrąžina klaidos. Tik aiškiai nurodyta reikšmė ?fg=000000 priverstinai nustato juodą spalvą.
bg=transparent grąžina SVG, PDF arba EPS be fono ir PNG su tikru alfa kanalu. Pagrindas, ant kurio dedamas kodas, turi būti šviesus ir aplinkui palikti 4 modulių ramybės zoną. Tamsus kodas ant tamsaus fono yra neįskaitomas.
PDF ir EPS rašo juodą ir pilką spalvas kaip pilkumo tonus (tik juodoji plokštė), o bet kurią kitą spalvą – kaip CMYK sveikaisiais procentais, pavyzdžiui, 1F4E79 kaip C74 M36 Y0 K53. Kai tik pasirenkama spalva, po kodu ir jo ramybės zona atsiranda nepermatomas užpildas, baltas arba bg spalvos, kaip ir SVG failo atveju. Be spalvų abu failai lieka nepakeisti. Konvertavimas ir apribojimai: Spalvos spaudoje.
Kontrastas: Paveikslėlio maršrutas jo netikrina. Rekomenduojama bent 4:1 ir tamsūs moduliai šviesiame fone. #1F4E79 ant balto fono yra 8,7:1, #ff6600 ant balto fono – tik 2,9:1.
ecc keičia taškų šabloną, o ne turinį. Atspausdintas kodas veikia toliau, tačiau nemaišykite senų ir naujų spaudos failų. Q arba H padaro kodą tvirtesnį, pavyzdžiui, ant gofruoto kartono. Logotipas visada reikalauja H.
Su logotipu plotas už logotipo lieka baltas, net ir esant spalvotam arba skaidriam fonui.
Talpykla: tik tikrasis standartinis paveikslėlis (juodas ant balto, klaidų taisymas M, be logotipo) 24 valandas pateikiamas kaip nekintamas; bet kuris kitas atvaizdavimas – 5 minutes. PDF ir EPS formatams bet koks nurodytas fonas laikomas nukrypimu: bg=ffffff ten nubraižo baltą užpildą, kurio standartinis failas neturi.
Planas: Spalvos ir klaidų taisymas yra prieinami visuose planuose, įskaitant ir nemokamą.

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

Spalvų išsaugojimas prie kodo

PATCH /v1/codes/:id išsaugo spalvas kaip appearance prie kodo. Vaizdo maršrutai jas tada atvaizduoja pagal numatytuosius nustatymus, be parametrų.

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

Atsakymas (HTTP 200, sutrumpintas):

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

Reikšmės: foreground_color kaip #RRGGBB, background_color kaip #RRGGBB arba transparent. Kiti raktai grąžina 400.
Sujungimas: Praleistas laukas išlaiko savo išsaugotą reikšmę. null atstato lauką, "appearance": null – abu laukus. Juoda ir balta spalvos nėra išsaugomos; atsakyme jos rodomos kaip null.
Kiekviename kodo atsakyme yra appearance, taip pat ir webhookuose qr.created ir qr.updated.
Eiliškumas vaizdo maršrutuose: pirmiausia parametras, tada išsaugota spalva, tada numatytoji reikšmė. Todėl ?fg=000000 pateikia spalvoto kodo juodą spausdinimo failą.
Įterpti paveikslėliai: Paveikslėlio URL seka išsaugotas spalvas, jei pats jų nenustato su fg ir bg: URL be parametrų – abiem spalvoms, ?fg=000000 – fonui, ?ecc=Q – taip pat abiem. Pakeitus spalvą, puslapis, kuriame įterptas toks URL, vis dar gali rodyti seną paveikslėlį: iki 24 valandų, jei URL iki tol grąžino numatytąjį paveikslėlį (juodą baltame fone, klaidų taisymas M, be logotipo), kitu atveju – iki 5 minučių. Išeitis – nuosavas parametras URL adresu, kuris keičiasi su kiekvienu spalvos pakeitimu, pavyzdžiui, ?v=2 arba kodo updated_at, kaip valdymo skydelyje. Paveikslėlių maršrutai ignoruoja nežinomus parametrus.
Klaidų taisymas niekada neišsaugomas. Jis pasirenkamas kiekvienam atsisiuntimui naudojant ?ecc=.
Tik per PATCH: POST /v1/codes, paketinis apdorojimas ir importavimas atmeta appearance su 422.
PDF ir EPS išsaugotas spalvas atvaizduoja kaip spaudos spalvas, lygiai taip pat kaip ir parametrus. Kadangi balta spalva niekada neišsaugoma, kodas su išsaugota priekinio plano spalva ten gauna baltą užpildą, kaip ir SVG.

Kontrasto patikra

API tikrina porą, kuri susidaro iš užklausos ir išsaugotos reikšmės:

Lygis	Kada	Atsakymas
`blocked`	Kontrastas mažesnis nei 1,5:1	`422`, niekas neišsaugoma
`critical`	mažesnis nei 2:1 arba ryškumo skirtumas mažesnis nei 0,30; įspėjimas kartu su logotipu; bet koks skaidrus fonas	`200` su `meta.issues`
`warning`	mažesnis nei 4:1 arba ryškumo skirtumas mažesnis nei 0,50; šviesūs moduliai tamsiame fone	`200` su `meta.issues`
ok	visa kita	`200`, `meta.issues` yra tuščias

Kiekvienas įrašas meta.issues turi code, severity, field, message ir pasirinktinai hints, pavyzdžiui, contrast_ratio — tokia pati forma kaip ir skaitmeninio produkto paso atitikties pranešimai. Skaidrus fonas niekada nėra blokuojamas, nes šviesus kodas ant tamsios pakuotės yra realus naudojimo atvejis. Vis dėlto pagrindui reikalingas aiškus kontrastas ir aplinkui esanti laisva 4 modulių ramybės zona.

Logotipo įkėlimas ir pašalinimas (POST ir DELETE /v1/codes/:id/logo) taip pat patikrina išsaugotas spalvas ir pateikia rezultatus meta.issues objekte: su logotipu įspėjimas tampa critical, o be logotipo – vėl įspėjimu.

Jei kita užklausa tuo pačiu metu keičia tą patį kodą, API pritaiko pakeitimus naujausiai būsenai. Tik tada, kai tai nepavyksta tris kartus iš eilės, ji atsako su 409; tuomet klientas iš naujo įkelia kodą ir pakartoja pakeitimą.

Logotipas

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

Multipart užklausa, laukas file: PNG, JPEG arba WebP, ne daugiau kaip 1 MB, atpažįstamas pagal „magic bytes“. Normalizuoja paveikslėlį į permatomą 512×512-PNG ir pakeičia esamą logotipą.

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

Atsakymas (HTTP 201): atnaujintas kodas su nustatytu logo_file_id.

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

Pašalina logotipą ir ištrina išsaugotą objektą. Idempotentiška — užklausa be esamo logotipo vis tiek grąžina 200.

Jei kita užklausa tuo pačiu metu keičia to paties kodo logotipą (antrasis įkėlimas arba pašalinimas), POST ir DELETE /v1/codes/:id/logo atsako su 409 (errors/conflict) ir nieko nekeičia; įkeltas paveikslėlis yra atmetamas. Įkelkite kodą iš naujo ir bandykite dar kartą. Du vienu metu atlikti DELETE /v1/codes/:id/logo iškvietimai nėra konfliktas; abu grąžina 200.

Jei jis nustatytas, visi keturi formatai — qr.svg, qr.png, qr.pdf ir qr.eps — įterpia logotipo pikselius ir padidina klaidų taisymą iki H. Visas aprašymas — įskaitant tai, kuris pakeitimas (pridėjimas / pašalinimas ar pakeitimas) keičia taškų raštą — bei spausdinimo rekomendacijos pateikiamos skyriuje Logotipas QR kode.

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`

Valdymo skydelyje sukurti komentarai yra priskiriami juos sukūrusiam naudotojui (author_id); komentarai, sukurti naudojant tik API raktą, lieka nepriskirti (author_id: null). Ištrinti komentarą gali tik pats jo autorius arba org_admin/ws_admin — naudojant tik API raktą galima ištrinti tik nepriskirtus, per API sukurtus komentarus.

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