API za QR kodove

Obvezujući REST ugovor

Sljedeći ugovor vrijedi za sve klijente:

POST /v1/codes prihvaća samo tipove url, vcard, wifi, email, sms i location. Polja su ravna: url; najmanje vcard_first_name ili vcard_last_name; wifi_ssid; email_to; sms_phone; ili oba location_lat i location_lng.
Samo url kodovi mogu biti dinamički. Zahtjevi za stvaranje mogu po želji sadržavati expires_at kao vremensku oznaku ISO 8601; ab_enabled, ab_target_url_b i ab_weight_a (A/B odredišta) prihvaćaju se za dinamičke url kodove; redirect_after_expiry nije dio ugovora o stvaranju.
GET /v1/codes podržava samo limit, cursor i status (live, paused, flagged, draft).
POST /v1/codes/batch prihvaća url, vcard i wifi. Ograničenje je 10 za Free, 500 za Pro i 1.000 zapisa za Business/Agency/Enterprise po zahtjevu. URL provjere se izvršavaju sinkrono za najviše 50 URL stavki; iznad 50 potreban je skip_url_scan: true.

Pregled

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

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

Izrada 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`	Wi-Fi konfiguracija	`wifi_ssid`
`email`	E-pošta (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Lokacija (geo:)	`location_lat`, `location_lng`

Skupna izrada

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

Popis QR kodova

`GET /v1/codes`

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

Parametri upita:

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`

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čki QR kodovi omogućuju vam 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 izrade ili putem PATCH zahtjeva). Skeniranjem će se tada prikazati stranica koju udomljuje qr3 s javnim datotekama i vanjskim poveznicama koda, umjesto preusmjeravanja. Vanjske poveznice prenose se kao niz 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 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 povremeno) 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: kvadratni oblik (samo kod); `?format=a4` za list za ispis
EPS (vektor)	`/v1/codes/:code/qr.eps`	Profesionalni tijekovi rada za ispis (Adobe, tiskare)

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

Samo PDF: ?format=a4|square — format stranice (zadano: square — samo kod + mirna zona, bez praznog A4 prostora; a4 za list 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 }'