API za QR kodove

Pregled

API za kodove je srce platforme qr3.app. Pomoću njega stvarate, ažurirate i brišete dinamičke i statičke QR kodove.

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

Stvaranje QR koda

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

Vrsta	Opis	Obavezna polja
`url`	URL web-stranice (dinamički ili statički)	`url`
`vcard`	Posjetnica (vCard 3.0)	`vcard_first_name` ili `vcard_last_name`
`wifi`	Konfiguracija Wi-Fi mreže	`wifi_ssid`
`email`	E-pošta (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Lokacija (geo:)	`location_lat`, `location_lng`

A/B testiranje

Testirajte dva različita ciljna URL-a s ponderiranim preusmjeravanjem:

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

Istek (Expiry)

QR kodovi mogu automatski isteći:

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

Nakon isteka, korisnik se preusmjerava na redirect_after_expiry ili se prikazuje stranica s greškom 410.

Skupno stvaranje

`POST /v1/codes/batch`

Stvara do 1.000 QR kodova u jednom zahtjevu. Idealno za masovnu primjenu.

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

Popis QR kodova

`GET /v1/codes`

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

Query parametri:

Parametar	Vrsta	Zadano	Opis
`cursor`	string	—	Kursor za paginaciju
`limit`	integer	20	Broj rezultata po stranici (maks. 100)
`status`	string	—	Filtar: `live`, `paused`, `flagged`, `draft`

Dohvaćanje QR koda

`GET /v1/codes/:id`

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

Ažuriranje QR koda

`PATCH /v1/codes/:id`

Dinamički QR kodovi omogućuju promjenu ciljnog URL-a u bilo kojem trenutku — bez potrebe za ponovnim ispisom QR koda.

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

Odredišna stranica i vanjske poveznice

Za dinamičke url kodove možete postaviti is_landing_page: true (prilikom stvaranja ili putem PATCH zahtjeva). Skeniranje će tada, umjesto preusmjeravanja, prikazati stranicu koju hosta qr3 s javnim datotekama i vanjskim poveznicama koda. Vanjske poveznice prenose se kao 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 poveznica po kodu; label ima 1–100 znakova; url mora biti http(s) (≤ 2048 znakova).
Svaki URL provjerava se pomoću usluge Google Web Risk — nesiguran URL vraća 422.
Ako Google Web Risk nije dostupan prilikom spremanja, poveznica se ipak prihvaća, ali se označava za ponovnu provjeru. Dnevni zadatak ponovno provjerava spremljene poveznice (a one koje su klasificirane kao sigurne provjerava periodički) i automatski pauzira kod ako se poveznica kasnije prepozna kao nesigurna.
"links": [] briše sve poveznice. Pogledajte vodič za odredišne stranice.

Brisanje QR koda

`DELETE /v1/codes/:id`

Meko brisanje (Soft-Delete) — QR kod se arhivira, a podaci o skeniranju se zadržavaju.

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

Preuzimanje slika QR kodova

Svi formati slika javno su dostupni — nije potrebna autentifikacija.

Format	URL	Upotreba
SVG (vektor)	`/v1/codes/:code/qr.svg`	Web, skaliranje, digitalni mediji
PNG (raster)	`/v1/codes/:code/qr.png`	E-pošta, prezentacije
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Standardno: kvadratno (samo kod); `?format=a4` za list za ispis
EPS (vektor)	`/v1/codes/:code/qr.eps`	Profesionalni tijekovi rada za ispis (Adobe, tiskare)

Izborno: ?size=N — veličina modula u pikselima (2–20, zadano: 4) za SVG, PNG und EPS. PDF koristi fiksnu veličinu modula.

Samo PDF: ?format=a4|square — format stranice (zadano: square — samo kod + prazan prostor (Quiet Zone), bez A4 praznog prostora; a4 za list papira formata A4 spreman za ispis)

# 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

Komentari

Komentari omogućuju povratne informacije između agencija i klijenata.

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