API za QR-kode

Pregled

API za kode je osrčje platforme qr3.app. Z njim ustvarjaš, posodabljaš in brišeš dinamične in statične QR-kode.

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

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`

A/B testiranje

Testiraj dva različna ciljna URL-ja z uteženo preusmeritvijo:

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

Potek veljavnosti (Expiry)

QR-kode lahko samodejno potečejo:

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

Po poteku veljavnosti se izvede preusmeritev na redirect_after_expiry ali pa se prikaže stran s kodo stanja 410.

Paketno ustvarjanje

`POST /v1/codes/batch`

Ustvari do 1.000 QR-kod v enem samem zahtevku. Idealno za množično uporabo.

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`

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 nastaviš 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. Oglej 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.

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

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`

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