API za QR-kode

Pregled

API za kode je osrčje platforme qr3.app. Z njim ustvarjate, posodabljate in brišete dinamične in statične QR-kode.

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

Zavezujoča pogodba REST

Naslednja pogodba velja za vse odjemalce:

POST /v1/codes sprejema samo vrste url, vcard, wifi, email, sms in location. Polja so ploska: url; vsaj vcard_first_name ali vcard_last_name; wifi_ssid; email_to; sms_phone; ali oba location_lat in location_lng.
Dinamične so lahko samo kode url. Zahteve za ustvarjanje lahko po izbiri vključijo expires_at kot časovni žig ISO 8601; ab_enabled, ab_target_url_b in ab_weight_a (cilji A/B) so dovoljeni za dinamične kode url; redirect_after_expiry ni del pogodbe za ustvarjanje.
GET /v1/codes podpira samo limit, cursor in status (live, paused, flagged, draft).
POST /v1/codes/batch sprejema url, vcard in wifi. Omejitev je 10 za Free, 500 za Pro in 1.000 zapisov za Business/Agency/Enterprise na zahtevo. Pregledi URL se sinhrono izvajajo za največ 50 elementov URL; nad 50 je potreben skip_url_scan: true.

Ustvarjanje QR-kode

`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

Odgovor (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" }
}

Vrste QR-kod

Vrsta	Opis	Obvezna polja
`url`	URL spletnega mesta (dinamični ali statični)	`url`
`vcard`	Vizitka (vCard 3.0)	`vcard_first_name` ali `vcard_last_name`
`wifi`	Konfiguracija Wi-Fi	`wifi_ssid`
`email`	E-pošta (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Lokacija (geo:)	`location_lat`, `location_lng`

Paketno ustvarjanje

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

Odgovor (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
  }
}

Seznam QR-kod

`GET /v1/codes`

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

Parametri poizvedbe:

Parameter	Vrsta	Privzeto	Opis
`cursor`	string	—	Kazalec (cursor) za paginacijo
`limit`	integer	20	Število rezultatov na stran (največ 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

Pridobivanje QR-kode

`GET /v1/codes/:id`

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

Posodabljanje QR-kode

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

Dinamične QR-kode omogočajo spreminjanje ciljnega URL-ja kadarkoli — brez potrebe po ponovnem tiskanju QR-kode.

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

Pristajalna stran in zunanje povezave

Za dinamične kode url lahko nastavite is_landing_page: true (ob ustvarjanju ali prek PATCH). Skeniranje bo nato namesto preusmeritve prikazalo stran, ki jo gosti qr3, z javnimi datotekami in zunanjimi povezavami kode. Zunanje povezave se prenesejo kot polje links:

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

0–20 povezav na kodo; label ima lahko 1–100 znakov; url mora biti http(s) (≤ 2048 znakov).
Vsak URL se preveri z Google Web Risk — nevaren URL vrne 422.
Če Google Web Risk med shranjevanjem ni dosegljiv, je povezava kljub temu sprejeta, vendar označena za ponovno preverjanje. Dnevno opravilo ponovno preveri shranjene povezave (in redno preverja tiste, ki so bile označene kot varne) ter samodejno začasno zaustavi kodo, če je povezava pozneje prepoznana kot nevarna.
"links": [] izbriše vse povezave. Oglejte si vodnik za pristajalne strani.

Brisanje QR-kode

`DELETE /v1/codes/:id`

Mehki izbris (soft-delete) — QR-koda se arhivira, podatki o skeniranju pa se ohranijo.

Drugi DELETE za isto kodo vrne 404, tudi če obe zahtevi prispeta hkrati. Webhook qr.deleted se pošlje natanko enkrat.

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

Prenos slik QR-kod

Vsi slikovni formati so javno dostopni — preverjanje pristnosti ni potrebno.

Format	URL	Uporaba
SVG (vektorski)	`/v1/codes/:code/qr.svg`	Splet, prilagajanje velikosti, digitalni mediji
PNG (rastrski)	`/v1/codes/:code/qr.png`	E-pošta, predstavitve
PDF (vektorski)	`/v1/codes/:code/qr.pdf`	Privzeto: kvadraten (samo koda); `?format=a4` za tiskalni list
EPS (vektorski)	`/v1/codes/:code/qr.eps`	Profesionalni tiskarski delovni procesi (Adobe, tiskarne)

Izbirno: ?size=N — velikost modula v slikovnih pikah (2–20, privzeto: 4) za SVG, PNG in EPS. PDF uporablja fiksno velikost modula.

Samo PDF: ?format=a4|square — format strani (privzeto: square — samo koda + prazno območje (quiet zone), brez belega prostora formata A4; a4 za list formata A4, pripravljen za tisk)

# 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

Barve in odpravljanje napak

Vse štiri poti slik sprejemajo tri izbirne parametre. Veljajo za ta posamezen priklic in imajo prednost pred barvami, ki so shranjene v kodi (naslednji razdelek).

Parameter	Vrednosti	Privzeto	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` ali `RGB`	`000000`	se izriše	se izriše kot tiskarska barva
`bg`	Hex kot `fg` ali `transparent`	`ffffff`	se izriše	se izriše kot tiskarska barva
`ecc`	`L`, `M`, `Q`, `H`	`M`	učinkuje	učinkuje

Zapis: Velike in male črke niso pomembne, # je izbiren. Če ga pošljete, ga kodirajte kot %23.
Neveljavne vrednosti se štejejo kot nenastavljene. ?fg=lila vrne barvo, shranjeno v kodi, ali običajno črno, če ni shranjena nobena barva, s statusom 200 in nikoli napake. Samo izrecna vrednost ?fg=000000 prisili črno barvo.
bg=transparent vrne SVG, PDF ali EPS brez ozadja in PNG s pravim alfa kanalom. Podlaga, na katero namestite kodo, mora biti svetla in na vseh straneh puščati 4 module praznega območja (tiha cona). Temna koda na temnem ozadju ni berljiva.
PDF in EPS zapisujeta črno in sivo kot sivinsko lestvico (samo črna plošča), vse ostale barve pa kot CMYK v celih odstotkih, na primer 1F4E79 kot C74 M36 Y0 K53. Takoj ko je izbrana barva, se za kodo in njeno tiho cono nahaja prekrivno polnilo, belo ali v barvi bg, enako kot pri SVG. Brez barv ostaneta obe datoteki nespremenjeni. Pretvorba in omejitve: Barve pri tisku.
Kontrastnost: Pot slike je ne preverja. Priporočljivo je razmerje vsaj 4:1 in temni moduli na svetli podlagi. #1F4E79 na beli ima razmerje 8,7:1, #ff6600 na beli pa le 2,9:1.
ecc spremeni vzorec pik, ne pa vsebine. Natisnjena koda še naprej deluje, vendar ne mešajte starih in novih datotek za tisk. Q ali H naredita kodo bolj robustno, na primer na valoviti lepenki. Logotip vedno zahteva H.
Z logotipom ostane območje za logotipom belo, tudi pri barvnem ali prosojnem ozadju.
Predpomnilnik: samo dejanska standardna slika (črna na belem, odpravljanje napak M, brez logotipa) se dostavi kot nespremenljiva za 24 ur; vsaka druga upodobitev pa za 5 minut. Pri PDF in EPS vsako podano ozadje šteje kot odstopanje: bg=ffffff tam izriše belo polnilo, ki ga standardna datoteka nima.
Paket: Barve in odpravljanje napak so na voljo v vsakem paketu, tudi v brezplačnem.

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

Shranjevanje barv na kodi

PATCH /v1/codes/:id shrani barve kot appearance na kodi. Slikovne poti jih nato izrišejo privzeto, brez parametrov.

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

Odgovor (HTTP 200, skrajšan):

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

Vrednosti: foreground_color kot #RRGGBB, background_color kot #RRGGBB ali transparent. Drugi ključi vrnejo 400.
Združevanje: Izpuščeno polje ohrani svojo shranjeno vrednost. null ponastavi polje, "appearance": null pa obe. Črna in bela se ne shranita; odgovor ju prikazuje kot null.
Vsak odgovor kode vsebuje appearance, prav tako webhooks qr.created in qr.updated.
Vrstni red v slikovnih poteh: najprej parameter, nato shranjena barva, nato privzeta vrednost. ?fg=000000 zato vrne črno tiskarsko datoteko barvne kode.
Vgrajene slike: Slikovni URL sledi shranjenim barvam, v kolikor jih sam ne določi s fg in bg: URL brez parametrov pri obeh barvah, ?fg=000000 pri ozadju, ?ecc=Q prav tako pri obeh. Po spremembi barve lahko stran, ki vgrajuje tak URL, še vedno prikazuje staro sliko: do 24 ur, če je URL do takrat dostavljal standardno sliko (črno na belem, odpravljanje napak M, brez logotipa), sicer pa do 5 minut. Rešitev je lasten parameter v URL-ju, ki se spremeni z vsako spremembo barve, na primer ?v=2 ali updated_at kode, kot na nadzorni plošči. Slikovne poti neznane parametre prezrejo.
Popravljanje napak se nikoli ne shrani. Izbere se ob vsakem prenosu z ?ecc=.
Samo prek PATCH: POST /v1/codes, paketna obdelava (batch) in uvoz zavrnejo appearance z 422.
PDF in EPS izrisujeta shranjene barve kot tiskarske barve, natanko tako kot parametri. Ker se bela barva nikoli ne shrani, dobi koda s shranjeno barvo ospredja tam belo polnilo, tako kot v SVG.

Preverjanje kontrasta

API preveri par, ki izhaja iz zahteve in shranjene vrednosti:

Stopnja	Kdaj	Odgovor
`blocked`	kontrast pod 1,5:1	`422`, nič se ne shrani
`critical`	pod 2:1 ali razlika v svetlosti pod 0,30; opozorilo skupaj z logotipom; katero koli prosojno ozadje	`200` z `meta.issues`
`warning`	pod 4:1 ali razlika v svetlosti pod 0,50; svetli moduli na temnem ozadju	`200` z `meta.issues`
ok	vse ostalo	`200`, `meta.issues` je prazen

Vsak vnos v meta.issues vsebuje code, severity, field, message in neobvezno hints, kot je contrast_ratio — enaka oblika kot sporočila o skladnosti digitalnega potnega lista izdelka (DPP). Prosojno ozadje ni nikoli blokirano, saj je svetla koda na temni embalaži dejanski primer uporabe. Podlaga kljub temu potrebuje izrazit kontrast in okoli sebe prazno mirno območje v velikosti 4 modulov.

Nalaganje in odstranjevanje logotipa (POST in DELETE /v1/codes/:id/logo) prav tako preverita shranjene barve in vrneta ugotovitve v meta.issues: z logotipom opozorilo postane critical, brez njega pa je spet le opozorilo.

Če druga zahteva hkrati spreminja isto kodo, API uveljavi spremembe na najnovejšem stanju. Šele ko to spodleti trikrat zapored, odgovori s 409; odjemalec nato ponovno naloži kodo in ponovi spremembo.

Logotip

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

Zahteva multipart, polje file: PNG, JPEG ali WebP, največ 1 MB, prepoznano po magičnih bajtih. Normalizira sliko v prosojen 512×512-PNG in zamenja obstoječi logotip.

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

Antwort (HTTP 201): posodobljena koda z nastavljenim logo_file_id.

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

Odstrani logotip in izbriše shranjeni objekt. Idempotentno — klic brez obstoječega logotipa še naprej vrača 200.

Če druga zahteva hkrati spremeni logotip iste kode (drugi prenos ali odstranitev), POST in DELETE /v1/codes/:id/logo vrneta 409 (errors/conflict) in ne spremenita ničesar; prenesena slika se zavrže. Ponovno naložite kodo in poskusite znova. Dva sočasna klica DELETE /v1/codes/:id/logo nista v konfliktu; oba vrneta 200.

Če je nastavljen, vsi štirje formati — qr.svg, qr.png, qr.pdf in qr.eps — vgradijo slikovne pike logotipa in zvišajo popravljanje napak na H. Celotna pogodba — vključno s tem, katera sprememba (dodajanje/odstranjevanje nasproti zamenjavi) spremeni vzorec pik — ter navodila za tiskanje so na voljo v Logo v QR-kodi.

Komentarji

Komentarji omogočajo povratne zanke med agencijami in strankami.

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

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

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

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

Komentarji, ustvarjeni v Nadzorni plošči, so pripisani uporabniku, ki jih je ustvaril (author_id); komentarji, ustvarjeni z navadnimi ključi API, ostanejo nepripisani (author_id: null). Komentar lahko izbriše le njegov avtor ali org_admin/ws_admin — navadni ključi API lahko izbrišejo samo nepripisane komentarje, ki so bili ustvarjeni prek API-ja.

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