API za QR-kode

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.

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`

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