QR-kode.si REST API

API v1 — kreacija QR kod. Upravljanje prek spletnega vmesnika.

Na voljo sta dva endpointa: avtenticiran (s ključem, vsi tipi, sledenje skenov) in javni anonimni (brez ključa, samo URL tip, brez sledenja).

Začni v 3 korakih

1

Pridobi API ključ

Pojdi v nastavitve računa in klikni »Generiraj API ključ«. Ključ se prikaže samo enkrat — shrani ga.

2

Pošlji POST zahtevo

Dodaj Authorization: Bearer {ključ} header in JSON body s tipom in podatki QR kode.

3

Uporabi sliko

Odgovor vsebuje URL-je za SVG, PNG, JPG in WebP — neposredno uporabni v <img>, tiskanju ali nadaljnji obdelavi.

Avtentikacija

API ključ pridobite v nastavitvah računa. Vsak zahtevek mora vsebovati header:

Authorization: Bearer vaš_api_ključ

Endpoint

POST https://qr-kode.si/api/v1/qr/generate

Zahtevani header: Content-Type: application/json

Skupna polja (request body)

Polje Tip Obvezno Opis
typestringdaTip QR kode (glej spodaj)
namestringdaPrikazno ime (max 255 znakov)
colorstringneBarva modulov (#000000 privzeto). Ignorirana za upn/sepa.
dataobjectdaTip-specifična polja (glej tabele spodaj)

Tipi QR kod in polja

url — URL
Polje Tip Obvezno Opomba
url string da Sprejme http:// in https://
Primer zahteve
{
    "type": "url",
    "name": "Moja stran",
    "color": "#4f46e5",
    "data": {
        "url": "https://example.com"
    }
}
text — Besedilo
Polje Tip Obvezno Opomba
text string da Max 2000 znakov
Primer zahteve
{
    "type": "text",
    "name": "Pozdrav",
    "data": {
        "text": "Pozdravljeni na razstavi!"
    }
}
wifi — Wi-Fi
Polje Tip Obvezno Opomba
ssid string da Ime omrežja
password string ne Geslo
encryption string ne WPA (privzeto), WEP, nopass
hidden boolean ne true/false
Primer zahteve
{
    "type": "wifi",
    "name": "Gostinsko omrežje",
    "data": {
        "ssid": "Gosti-WiFi",
        "password": "geslo123",
        "encryption": "WPA"
    }
}
email — E-pošta
Polje Tip Obvezno Opomba
to string da E-mail naslov
subject string ne Zadeva
body string ne Vsebina
Primer zahteve
{
    "type": "email",
    "name": "Kontakt",
    "data": {
        "to": "info@example.com",
        "subject": "Povpraševanje",
        "body": "Pozdravljeni,"
    }
}
sms — SMS
Polje Tip Obvezno Opomba
phone string da Telefonska številka
message string ne Vsebina
Primer zahteve
{
    "type": "sms",
    "name": "Naroči se",
    "data": {
        "phone": "+38641234567",
        "message": "Naroči me prosim."
    }
}
geo — Lokacija
Polje Tip Obvezno Opomba
lat number ne Geografska širina (napaka le, če sta oba 0)
lng number ne Geografska dolžina (napaka le, če sta oba 0)
label string ne Naziv lokacije
Primer zahteve
{
    "type": "geo",
    "name": "Naša trgovina",
    "data": {
        "lat": 46.0569,
        "lng": 14.5058,
        "label": "Ljubljana center"
    }
}
event — Dogodek
Polje Tip Obvezno Opomba
summary string da Naziv
dtstart string da ISO 8601 (npr. 20251224T120000Z)
dtend string ne ISO 8601
location string ne Lokacija
Primer zahteve
{
    "type": "event",
    "name": "Konferenca 2025",
    "data": {
        "summary": "Letna konferenca",
        "dtstart": "20251015T090000Z",
        "dtend": "20251015T180000Z",
        "location": "Ljubljana"
    }
}
phone — Telefon
Polje Tip Obvezno Opomba
phone string da Telefonska številka
Primer zahteve
{
    "type": "phone",
    "name": "Pokliči nas",
    "data": {
        "phone": "+38641234567"
    }
}
vcard — Vizitka (vCard)
Polje Tip Obvezno Opomba
first_name string da Ime
last_name string ne Priimek
phone string ne Telefon
email string ne E-mail
org string ne Podjetje
title string ne Naziv
url string ne Spletna stran
address string ne Naslov
Primer zahteve
{
    "type": "vcard",
    "name": "Moja vizitka",
    "data": {
        "first_name": "Ana",
        "last_name": "Novak",
        "phone": "+38641234567",
        "email": "ana@example.com",
        "org": "Podjetje d.o.o.",
        "title": "Direktorica"
    }
}
mecard — Vizitka (meCard)
Polje Tip Obvezno Opomba
first_name string da Ime
last_name string ne Priimek
phone string ne Telefon
email string ne E-mail
Primer zahteve
{
    "type": "mecard",
    "name": "meCard vizitka",
    "data": {
        "first_name": "Ana",
        "last_name": "Novak",
        "phone": "+38641234567",
        "email": "ana@example.com"
    }
}
bitcoin — Bitcoin
Polje Tip Obvezno Opomba
address string da Bitcoin naslov (začne z 1, 3 ali bc1)
amount string ne Znesek BTC (max 8 decimalk)
label string ne Oznaka
message string ne Sporočilo
Primer zahteve
{
    "type": "bitcoin",
    "name": "Bitcoin donacija",
    "data": {
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "amount": "0.001",
        "label": "Donacija"
    }
}
whatsapp — WhatsApp
Polje Tip Obvezno Opomba
phone string da E.164 brez + (npr. 38640123456)
text string ne Predizpolnjeno sporočilo
Primer zahteve
{
    "type": "whatsapp",
    "name": "WhatsApp podpora",
    "data": {
        "phone": "38641234567",
        "text": "Pozdravljeni, zanima me..."
    }
}
upn — UPN (Slovenija)
Polje Tip Obvezno Opomba
recipient_name string da Max 33 znakov
recipient_iban string da IBAN (validiran z MOD-97)
recipient_bic string ne BIC/SWIFT
amount number ne EUR, 0 = odprt znesek
purpose_code string ne OTHR, IVPT, SALA... (privzeto OTHR)
payment_purpose string da Namen plačila (max 42 znakov)
reference string da Referenca (npr. SI00 123456789, max 26)
recipient_address string ne Max 33
recipient_city string ne Max 33
due_date string ne YYYY-MM-DD
payer_name string ne Max 33
payer_address string ne Max 33
payer_city string ne Max 33
Primer zahteve
{
    "type": "upn",
    "name": "Račun 2025-042",
    "data": {
        "recipient_name": "Podjetje d.o.o.",
        "recipient_iban": "SI56020100257654321",
        "amount": 49.99,
        "payment_purpose": "Plačilo računa 2025-042",
        "reference": "SI00 123456789"
    }
}
sepa — SEPA (EU)
Polje Tip Obvezno Opomba
recipient_name string da Max 70 znakov
recipient_iban string da IBAN (validiran)
recipient_bic string ne BIC (opcijsko v SEPA EEA)
amount number ne EUR, 0 = odprt znesek
purpose_code string ne 4-črkovna ISO koda (npr. IVPT)
reference string ne Strukturirana ref (RF..., max 35). Izključujoče s sepa_remittance.
sepa_remittance string ne Nestrukturirana ref (max 140). Izključujoče z reference.
sepa_beneficiary_info string ne Info za prejemnika (max 70)
Primer zahteve
{
    "type": "sepa",
    "name": "SEPA nakazilo",
    "data": {
        "recipient_name": "Example GmbH",
        "recipient_iban": "DE89370400440532013000",
        "recipient_bic": "COBADEFFXXX",
        "amount": 125,
        "sepa_remittance": "Invoice 2025-042"
    }
}

Odgovor (HTTP 201)

{
    "ok": true,
    "token": "abc123xyz",
    "image_svg": "https://qr-kode.si/storage/qr/abc123xyz.svg",
    "image_png": "https://qr-kode.si/storage/qr/abc123xyz.png",
    "image_jpg": "https://qr-kode.si/storage/qr/abc123xyz.jpg",
    "image_webp": "https://qr-kode.si/storage/qr/abc123xyz.webp"
}
Polje Opis
okVedno true pri uspešnem odgovoru
tokenUnikatni identifikator QR kode (10 znakov). Uporaben za referenco ali sledenje.
image_svgURL vektorske slike (SVG) — idealna za tisk v katerikoli velikosti brez izgube kakovosti
image_pngURL rastrske slike PNG — prosojno ozadje, primerno za digitalno uporabo in tisk
image_jpgURL rastrske slike JPG — belo ozadje, primerno za fotografije in splet kjer prosojnost ni potrebna
image_webpURL rastrske slike WebP — manjša datoteka od JPG/PNG ob enaki kakovosti, priporočeno za splet
redirect_urlPrisotno samo pri type=url — URL ki ga QR koda kodira; skeni se beležijo pri obisku tega naslova. Pri ostalih tipih polje ni v odgovoru.

Za plačilne tipe (upn/sepa) so URL-ji v /storage/upn/ oz. /storage/sepa/.

Napake

Ob napaki je ok: false in polje error z opisom.

HTTPPomen
400Napaka validacije (error polje vsebuje opis)
401Manjkajoč ali neveljaven API ključ
405Napačna HTTP metoda (samo POST)
429Rate limit prekoračen (avtenticiran: 100/uro; anonimni: 30/uro per IP). Header Retry-After pove kdaj.
500Interna napaka strežnika

Primeri kode

curl -X POST https://qr-kode.si/api/v1/qr/generate \
  -H "Authorization: Bearer VAŠ_API_KLJUČ" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "name": "Moja spletna stran",
    "color": "#4f46e5",
    "data": {
      "url": "https://example.com"
    }
  }'
Klice API vedno izvajaj samo s strežnika (PHP, Node.js, Python…) — API ključ mora ostati zaseben. Klic iz brskalnika (frontend JS) ni podprt in varnostno ni primeren, ker je ključ v JS kodi lahko javno viden vsakomur.

Javni anonimni endpoint

Hitro generiranje QR kode iz URL-ja brez API ključa. Primerno za vgradnjo v <img> na javnih straneh.

GET https://qr-kode.si/api/v1/qr/generate-public?url={url}&format={format}

Parametri (query string)

Polje Tip Obvezno Opis
urlstringdahttp:// ali https://, max 2048 znakov
formatstringnesvg (privzeto), png, jpg, webp

Odgovor

Vrne binarno sliko (ne JSON) s primernim Content-Type. Dodatni headerji:

  • Cache-Control: public, max-age=3600 — browser/CDN cache
  • X-Cache: HIT ali MISS — ali je bila slika vrnjena iz strežniškega cache-a

Omejitve

  • Rate limit: 30 zahtevkov/uro per IP (HTTP 429 + Retry-After header ob prekoračitvi)
  • Podpira samo tip URL (za ostale tipe uporabi avtenticiran endpoint)
  • Barva je fiksno črna (brez color parametra)
  • Brez sledenja skenov — QR koda kodira direktno podani URL, ne redirect
  • Cache slike na strežniku: 60 min

Primeri uporabe

<!-- Vgradnja v HTML -->
<img src="https://qr-kode.si/api/v1/qr/generate-public?url=https://example.com&format=png"
     alt="QR koda za example.com"
     width="300" height="300">
# Prenesi SVG
curl "https://qr-kode.si/api/v1/qr/generate-public?url=https://example.com" -o qr.svg

# Prenesi PNG
curl "https://qr-kode.si/api/v1/qr/generate-public?url=https://example.com&format=png" -o qr.png

API v1 podpira samo kreacijo. Upravljanje (brisanje, statistika) je na voljo prek spletnega vmesnika.