API za QR kodove

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

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.

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.

Drugi DELETE istog koda vraća 404, čak i ako oba zahtjeva stignu u isto vrijeme. Webhook qr.deleted šalje se točno jednom.

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

Boje i ispravak pogrešaka

Sve četiri rute slika prihvaćaju tri neobavezna parametra. Oni vrijede za taj konkretan dohvat i imaju prednost pred bojama koje su spremljene na kodu (sljedeći odjeljak).

Parametar	Vrijednosti	Standardno	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` ili `RGB`	`000000`	iscrtava se	iscrtava se kao tiskarska boja
`bg`	Hex kao `fg` ili `transparent`	`ffffff`	iscrtava se	iscrtava se kao tiskarska boja
`ecc`	`L`, `M`, `Q`, `H`	`M`	djeluje	djeluje

Način pisanja: Velika i mala slova nisu važna, # je neobavezan. Ako se šalje, kodira se kao %23.
Nevaljane vrijednosti smatraju se nepostavljenima. ?fg=lila vraća boju pohranjenu na kodu, ili normalnu crnu ako nijedna nije pohranjena, s 200 i nikada pogrešku. Samo izričit ?fg=000000 prisilno postavlja crnu boju.
bg=transparent vraća SVG, PDF ili EPS bez pozadine i PNG sa stvarnim alfa kanalom. Podloga na koju se kod postavlja mora biti svijetla i ostavljati slobodna 4 modula mirne zone sa svih strana. Tamni kod na tamnoj podlozi nije čitljiv.
PDF i EPS zapisuju crnu i sivu kao sivi ton (samo crna ploča), a svaku drugu boju kao CMYK u cijelim postocima, na primjer 1F4E79 kao C74 M36 Y0 K53. Čim se odabere boja, iza koda i njegove mirne zone nalazi se neprozirna ispuna, bijela ili u boji bg, kao u SVG-u. Bez boja obje datoteke ostaju nepromijenjene. Pretvorba i ograničenja: Boje u tisku.
Čitljivost: Ruta slike ne provjerava kontrast. Preporučuje se najmanje 4:1 i tamni moduli na svijetloj podlozi. #1F4E79 na bijeloj ima 8,7:1, #ff6600 na bijeloj samo 2,9:1.
ecc mijenja uzorak točaka, a ne sadržaj. Tiskani kod nastavlja raditi, ali se stare i nove datoteke za tisak ne smiju miješati. Q ili H čine kod robusnijim, primjerice na valovitom kartonu. Logo uvijek zahtijeva H.
S logotipom područje iza logotipa ostaje bijelo, čak i kod obojene ili prozirne pozadine.
Predmemoriranje: Samo se stvarna standardna slika (crno na bijelom, ispravak pogrešaka M, bez logotipa) isporučuje kao nepromjenjiva tijekom 24 sata; svaki drugi prikaz tijekom 5 minuta. Za PDF i EPS bilo koja navedena pozadina računa se kao odstupanje: bg=ffffff tamo iscrtava bijelu ispunu koju standardna datoteka nema.
Tarifa: Boje i ispravak pogrešaka dostupni su u svakoj tarifi, pa tako i u besplatnoj.

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

Spremanje boja na kodu

PATCH /v1/codes/:id sprema boje kao appearance na kodu. Rute slika ih zatim iscrtavaju prema zadanim postavkama, bez parametara.

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, skraćeno):

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

Vrijednosti: foreground_color kao #RRGGBB, background_color kao #RRGGBB ili transparent. Ostali ključevi rezultiraju s 400.
Spajanje: Izostavljeno polje zadržava svoju spremljenu vrijednost. null resetira jedno polje, "appearance": null oba. Crna i bijela se ne spremaju; odgovor ih prikazuje kao null.
Svaki odgovor koda sadrži appearance, kao i webhooks qr.created i qr.updated.
Redoslijed u rutama slika: najprije parametar, zatim spremljena boja, a potom zadana vrijednost. ?fg=000000 stoga isporučuje crnu datoteku za ispis obojanog koda.
Ugrađene slike: URL slike prati spremljene boje u onoj mjeri u kojoj ih sam ne određuje s fg i bg: URL bez parametara za obje boje, ?fg=000000 za pozadinu, a ?ecc=Q također za obje. Nakon promjene boje, stranica koja ugrađuje takav URL može još uvijek prikazivati staru sliku: do 24 sata ako je URL do tada isporučivao standardnu sliku (crna na bijeloj, ispravak pogrešaka M, bez logotipa), inače do 5 minuta. Rješenje je vlastiti parametar na URL-u koji se mijenja sa svakom promjenom boje, poput ?v=2 ili updated_at koda kao na nadzornoj ploči. Rute slika ignoriraju nepoznate parametre.
Ispravak pogrešaka se nikada ne sprema. Odabire se po preuzimanju pomoću ?ecc=.
Samo putem PATCH: POST /v1/codes, batch i uvoz odbijaju appearance s 422.
PDF i EPS iscrtavaju spremljene boje kao tiskarske boje, baš kao i parametre. Budući da se bijela boja nikada ne sprema, kod sa spremljenom bojom prednjeg plana tamo dobiva bijelu ispunu, kao u SVG-u.

Provjera kontrasta

API provjerava par koji proizlazi iz zahtjeva i spremljene vrijednosti:

Razina	Kada	Odgovor
`blocked`	kontrast ispod 1,5:1	`422`, ništa se ne sprema
`critical`	ispod 2:1 ili razlika u svjetlini ispod 0,30; upozorenje zajedno s logotipom; bilo koja prozirna pozadina	`200` s `meta.issues`
`warning`	ispod 4:1 ili razlika u svjetlini ispod 0,50; svijetli moduli na tamnoj pozadini	`200` s `meta.issues`
ok	sve ostalo	`200`, `meta.issues` je prazan

Svaki unos u meta.issues ima code, severity, field, message i opcionalno hints kao što je contrast_ratio — isti oblik kao i poruke o usklađenosti digitalne putovnice o proizvodu (DPP). Prozirna pozadina nikada se ne blokira jer je svijetli kod na tamnoj ambalaži stvarni slučaj upotrebe. Podloga ipak treba jasan kontrast i slobodnu zonu mirovanja od 4 modula sa svih strana.

Učitavanje i uklanjanje logotipa (POST i DELETE /v1/codes/:id/logo) također provjeravaju spremljene boje i vraćaju nalaze u meta.issues: s logotipom upozorenje postaje critical, a bez njega ponovno upozorenje.

Ako drugi zahtjev promijeni isti kod u istom trenutku, API primjenjuje promjene na najnovije stanje. Tek ako to ne uspije tri puta zaredom, odgovara s 409; klijent tada ponovno učitava kod i ponavlja promjenu.

Logo

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

Multipart-zahtjev, polje file: PNG, JPEG ili WebP, najviše 1 MB, prepoznato po magic bytes. Normalizira sliku na transparentni 512×512-PNG i zamjenjuje postojeći logo.

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

Odgovor (HTTP 201): ažurirani kod, s postavljenim logo_file_id.

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

Uklanja logo i briše spremljeni objekt. Idempotentno — poziv bez postojećeg logotipa i dalje vraća 200.

Ako drugi zahtjev istovremeno promijeni logotip istog koda (drugi prijenos ili uklanjanje), POST i DELETE /v1/codes/:id/logo odgovaraju s 409 (errors/conflict) i ne mijenjaju ništa; prenesena slika se odbacuje. Ponovno učitajte kod i pokušajte ponovno. Dva istovremena poziva DELETE /v1/codes/:id/logo nisu konflikt; oba vraćaju 200.

Ako je postavljen, sva četiri formata — qr.svg, qr.png, qr.pdf i qr.eps — ugrađuju piksele logotipa i povećavaju ispravljanje pogrešaka na H. Cijeli ugovor — uključujući i to koja promjena (dodavanje/uklanjanje naspram zamjene) mijenja uzorak točaka — kao i upute za ispis nalaze se pod Logo u QR kodu.

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`

Komentari na Nadzornoj ploči dodjeljuju se korisniku koji ih je izradio (author_id); komentari stvoreni putem običnog API ključa ostaju nedodijeljeni (author_id: null). Komentar može obrisati samo sam autor ili org_admin/ws_admin — API ključ bez korisničke sesije može obrisati samo nedodijeljene komentare stvorene putem 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 }'