QReturn API – Dokumentace

Autentizace

API používá HTTP Basic Auth. Jako uživatelské jméno zadejte svůj e-mail a jako heslo API klíč, který si vygenerujete v administraci v sekci API klíče.

Uživatel (username)

vas@email.cz

Heslo (password)

váš-api-klíč

Hlavička požadavku

Authorization: Basic base64(email:api_key)

Endpointy

POST /api/v1/qr/create

Vytvoří nový QR kód přiřazený k vašemu účtu. Vrátí veřejné ID a odkaz na QR kód.

Parametry požadavku

Parametr	Typ	Popis
payload povinný	object	Data QR kódu – struktura závisí na zvoleném typu (viz níže)
type volitelný	string	Typ QR kódu Výchozí: "url"
label volitelný	string	Popis pro vlastní orientaci Výchozí: "API created"

Odpovědi

{
  "status": "success",
  "public_id": "abc123",
  "link": "https://qreturn.cz/q/abc123"
}

{
  "status": "error",
  "message": "Neplatný typ QR kódu"
}

{
  "status": "error",
  "message": "Neplatný e-mail nebo API klíč."
}

Typy QR kódů

Parametr type určuje strukturu dat v payload.

🔗

url

Webový odkaz

📶

wifi

Wi-Fi připojení

👤

vcard

Vizitka

✉️

email

E-mailová adresa

📞

phone

Telefonní číslo

💬

sms

SMS zpráva

📝

text

Prostý text

📄

page

Stránka QKarta

QKarta `page`

QKarta je stránka složená z bloků, která se návštěvníkovi otevře po naskenování kódu. Jde o placený doplněk – endpointy ho povolí jen účtu s aktivovanými šablonami, jinak vrátí FORBIDDEN. Payload musí obsahovat alespoň jeden blok s obsahem.

Soubory (přílohy QKarty) se nenahrávají v payload, ale přes samostatné endpointy POST /api/v1/qr/files/upload (multipart) a POST /api/v1/qr/files/delete. Náhled konceptu vyrenderuje POST /api/v1/qr/preview.

Struktura payload:

title – nadpis stránky (povinné)
subtitle – podnadpis (volitelné)
accent – barva v #RRGGBB (volitelné, výchozí #2563eb)
blocks – pole bloků; každý má type, public (bool, výchozí true) a title

Typy bloků (block.type):

hero – eyebrow, title, text
fields – title + items: [{ label, value }]
checklist – title + items: [{ text, checked }]
links – title + items: [{ label, url, style: "primary"|"secondary", color }]
table – title, columns: [string] (max 5), rows: [[string]]
note – title, text

payload (page)

{
  "title": "Servisní karta",
  "subtitle": "Plynový kotel · kotelna 1. NP",
  "accent": "#2f8f46",
  "blocks": [
    { "type": "hero", "eyebrow": "QKarta", "title": "Servisní karta", "text": "Informace k zařízení." },
    { "type": "fields", "title": "Údaje", "items": [{ "label": "Výrobní číslo", "value": "A-12345" }] },
    { "type": "checklist", "title": "Kontrola", "items": [{ "text": "Těsnost", "checked": true }] },
    { "type": "links", "title": "Odkazy", "items": [{ "label": "Návod", "url": "https://example.com", "style": "primary" }] },
    { "type": "table", "title": "Historie", "columns": ["Datum", "Technik"], "rows": [["10. 8. 2026", "Jan Novák"]] },
    { "type": "note", "title": "Poznámka", "text": "Další prohlídka do 10. 2. 2027." }
  ]
}

Příklady použití

cURL

curl -X POST https://qreturn.cz/api/v1/qr/create \
  -u "vas@email.cz:vas-api-klic" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "label": "Firemní web",
    "payload": {
      "url": "https://example.com"
    }
  }'

PHP

$ch = curl_init('https://qreturn.cz/api/v1/qr/create');

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'vas@email.cz:vas-api-klic',
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'type'    => 'url',
        'label'   => 'Firemní web',
        'payload' => ['url' => 'https://example.com'],
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo $data['link']; // https://qreturn.cz/q/abc123

JavaScript (fetch)

const response = await fetch('https://qreturn.cz/api/v1/qr/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('vas@email.cz:vas-api-klic'),
  },
  body: JSON.stringify({
    type: 'url',
    label: 'Firemní web',
    payload: { url: 'https://example.com' },
  }),
});

const data = await response.json();
console.log(data.link); // https://qreturn.cz/q/abc123

Python (requests)

import requests

response = requests.post(
    'https://qreturn.cz/api/v1/qr/create',
    auth=('vas@email.cz', 'vas-api-klic'),
    json={
        'type': 'url',
        'label': 'Firemní web',
        'payload': {'url': 'https://example.com'},
    },
)

data = response.json()
print(data['link'])  # https://qreturn.cz/q/abc123

Chybové stavy

Kód	Význam	Popis
201	Created	QR kód byl úspěšně vytvořen
400	Bad Request	Neplatná data – chybný typ, chybějící payload apod.
401	Unauthorized	Chybějící nebo neplatné přihlašovací údaje
500	Internal Error	Neočekávaná chyba na straně serveru

Všechny chybové odpovědi mají jednotný formát:

{
  "status": "error",
  "message": "Popis chyby"
}