qrlink API

REST API pro napojení vašich systémů: evidence majetku, e-shopu, intranetu nebo skriptu, který hromadně zakládá kódy. Odpovědi jsou v JSON, kódování UTF-8, časy ve formátu ISO 8601.

Adresa: https://qrlink.cz/api/v1

Nejste programátor? Po přihlášení najdete návod krok za krokem s hotovými postupy pro PowerShell a Excel.

Přístup

API zapíná provozovatel u účtu na požádání (tarify Firma a Individuál). Klíče pak vytváří vlastník účtu v Účet → API.
Každý klíč má oprávnění: Čtení (vždy), Úpravy obsahu a Servis. Volitelně ho jde omezit na vybrané skupiny kódů, na IP adresy a dobu platnosti.
Klíč posílejte v hlavičce Authorization: Bearer qrl_…. V adrese ho API odmítne, protože by zůstal v logách serverů a v historii prohlížeče.
Klíč se ukáže jen jednou při vytvoření, u nás je uložený jen jeho otisk. Když unikne, zrušte ho v Účet → API, přestane fungovat okamžitě.
Každou změnu přes API uvidíte v Záznamu změn účtu jako „API: název klíče“. O novém klíči přijde vlastníkovi e-mail.

Ukázky

curl -H "Authorization: Bearer $QRLINK_KEY" https://qrlink.cz/api/v1/codes?limit=20

curl -X POST https://qrlink.cz/api/v1/codes \
  -H "Authorization: Bearer $QRLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Návod k čerpadlu","type":"redirect",
       "content":{"url":"https://example.cz/navod"},
       "groups":["Čerpadla"]}'

curl -X PATCH https://qrlink.cz/api/v1/codes/AB3CD5 \
  -H "Authorization: Bearer $QRLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

curl -X POST https://qrlink.cz/api/v1/codes/AB3CD5/files \
  -H "Authorization: Bearer $QRLINK_KEY" \
  -F "file=@navod.pdf" -F "label=Návod k obsluze"

Odpovědi a stránkování

Úspěšná odpověď má data v klíči data. Seznam kódů vrací nejvýš limit položek a v next_cursor hodnotu pro další stránku (pošlete ji jako parametr cursor). Na poslední stránce je next_cursor null.

{
  "data": [
    {
      "code": "AB3CD5",
      "url": "https://qrlink.cz/AB3CD5",
      "title": "Návod k čerpadlu",
      "type": "redirect",
      "status": "active",
      "blocked": false,
      "over_limit": false,
      "protected": false,
      "groups": [{"id": 12, "name": "Čerpadla"}],
      "scans": 48,
      "valid_from": null,
      "valid_until": null,
      "created_at": "2026-03-02T09:15:00+01:00"
    }
  ],
  "next_cursor": "YzEyMzQ"
}

Detail kódu (GET /codes/{kód}) má navíc content podle typu, viz Obsah podle typu. Data a časy jsou ve formátu ISO 8601, prázdné hodnoty null.

Koncové body

Metoda	Adresa	Oprávnění	Popis
`GET`	`/`	Bez klíče	Název a verze API, odkaz na tuto dokumentaci. Hodí se k ověření, že adresa funguje.
`GET`	`/me`	Čtení	Účet, klíč, jeho oprávnění, využití limitů a typy kódů v tarifu (card_types).
`GET`	`/codes`	Čtení	Seznam kódů. Filtry: type, status (active, paused), group (ID skupiny), q (název nebo kód), updated_since (datum a čas). Stránkování: limit (1–100, výchozí 50), cursor.
`GET`	`/codes/{kód}`	Čtení	Detail kódu včetně obsahu. Funguje i se záložní adresou kódu.
`POST`	`/codes`	Úpravy obsahu	Nový kód: title, type, content, groups. Kód se vygeneruje. Vrací 201 a detail.
`PATCH`	`/codes/{kód}`	Úpravy obsahu	Úprava: title, status (active, paused), type, content, groups. U obsahu stačí poslat měněná pole.
`DELETE`	`/codes/{kód}`	Úpravy obsahu	Kód do koše. Vlastník ho může v aplikaci 30 dní obnovit. Vrací 204.
`POST`	`/codes/{kód}/files`	Úpravy obsahu	PDF ke kódu typu documents, asset nebo product (multipart/form-data: file, volitelně label a visibility public, password, members).
`DELETE`	`/codes/{kód}/files/{id}`	Úpravy obsahu	Smaže soubor nebo odkaz.
`POST`	`/codes/{kód}/links`	Úpravy obsahu	Odkaz ke kódu typu documents, asset nebo product: url, label.
`POST`	`/codes/{kód}/log`	Servis	Záznam do servisního deníku karty zařízení: date, kind (inspection, service, repair, purchase, install, note), text, cost, u revize volitelně result (ok = vyhovělo, fail = nevyhovělo; nevyhovělo termín neposune, s výsledkem je text nepovinný). Revize posune datum příští revize.
`GET`	`/codes/{kód}/stats`	Čtení	Načtení kódu. Parametry from, to (RRRR-MM-DD), interval (day, month).
`GET`	`/groups`	Čtení	Skupiny účtu s počtem kódů.
`GET`	`/stats`	Čtení	Načtení všech kódů (nebo group, code). Parametry from, to, interval. Po dnech nejvýš 366 dní.
`GET`	`/reports`	Čtení	Hlášení závad. Parametry state (open, new, progress, done, all), since. E-mail oznamovatele API nevrací.
`PATCH`	`/reports/{id}`	Servis	Stav hlášení: state (new, progress, done), note, to_log (zapsat opravu do deníku). Po vyřešení dostane oznamovatel e-mail, pokud o něj požádal.

Obsah podle typu

redirect: url, volitelně next_url a switch_at (od kdy platí nová adresa).
vcard: first_name, last_name, org, job_title, department, note, birthday a seznamy phones, emails, urls (položky {"type": "work", "value": "…"}), addresses (street, city, zip, country) a socials.
documents: heading, body (text se značkami: prázdný řádek = odstavec, ## nadpis, ### podnadpis, -# malá poznámka, - odrážka, 1. číslovaný seznam, > rámeček, --- čára, **tučně**, *kurzíva*, [text](https://…) odkaz). Soubory a odkazy zvlášť přes /files a /links.
asset: name, model, inventory_no, serial_no, category, location, state, kind (equipment, property, job = zakázka, object = nemovitost), last_inspection, next_inspection, inspection_months, inspection_result (jen čtení: výsledek poslední revize ok/fail), notify_owner (upozornění na revizi i vlastníkovi účtu, výchozí true), notify_emails (další e-maily pro upozornění, pole nejvýš 5 adres; dostanou připomínku s kontaktem na vás a odkazem pro odhlášení), lat, lng a další pole karty; u zakázky job_no, installed_at, technician, job_scope, customer, customer_contact, owner_web, service_info, owner_address (adresa firmy), owner_public_email (e-mail pro zákazníky, na kartě veřejně; owner_email je jen pro zprávy z karty); u nemovitosti offer (sale, rent, reserved, sold, rented nebo prázdné) a offer_price (samotné číslo se uloží s mezerami po tisících a Kč, např. 5490000 → 5 490 000 Kč; jiná měna se napíše za číslo, např. 250000 €), offer_url (odkaz na inzerát), offer_note (krátká zpráva na kartě, nejvýš 190 znaků). Zakázka nemá stav, state je u ní vždy active (jen vyřazená má retired).
wifi: ssid, security (WPA, WEP, nopass), password, hidden, note. Heslo Wi-Fi jde jen nastavit, API ho nevrací.
luggage (zavazadlo): owner_name, phone, email, show_phone, show_email (ukázat na štítku, výchozí false), form_always (formulář pro nálezce i mimo stav ztraceno, výchozí false), home (odkud), destination (kam), depart_date, return_date (RRRR-MM-DD), flight_out, flight_back, stay (ubytování), stay_public (ukázat během cesty, výchozí true; false = jen ztracené), home_address, home_show (never výchozí, lost, always), note, lost (true = ztraceno), lost_note. Čtení vrací navíc lost_at a route_now, cestu, jak ji štítek ukazuje dnes (direction out nebo od dne návratu back).
product (výrobek, v224): name, brand, model, description, specs (řádky Název: hodnota), contact_role (maker výrobce, seller prodejce, service servis), contact_name, contact_phone, contact_email, contact_web, inquiry (tlačítko Poptat u dílů bez odkazu do e‑shopu, zpráva přijde na e‑mail účtu, výchozí false), drawing_file_id (rozkres, ID obrázku nahraného ke kódu) a seznamy parts (náhradní díly) a accessories (příslušenství). Položka: name, part_no (objednací číslo), price (text, holé číslo se ukáže v Kč), url (e‑shop), grp (skupina), pos (pozice na rozkresu, jen u dílů), note, link_code (kód jiného výrobku v účtu, položka pak vede na jeho stránku), photo_file_id (ID obrázku kódu: fotka položky nahraná v aplikaci nebo obrázek ze souborů). Poslaný seznam nahradí celý dosavadní seznam, neposlaný zůstane. Nejvýš 300 položek v seznamu. Soubory a odkazy jako u documents.

Skupiny (groups) posílejte jako pole ID nebo názvů. Neexistující název se založí, u klíče omezeného na skupiny ne. Heslo kódu, VIP adresu ani předání kódu API nemění, to zůstává v aplikaci.

Chyby a limity

Chyba vrací stavový kód a {"error": {"code": "…", "message": "…", "fields": {…}}}.

401 chybějící, neplatný, zrušený nebo prošlý klíč. Po 20 neplatných pokusech za 10 minut z jedné IP adresy API vrací 429.
403 klíč nemá oprávnění, jiná IP adresa, API účtu vypnuté, zablokovaný kód nebo pozastavené předplatné (při změnách). Kód card_type_not_allowed: typ kódu (u asset podle kind) není v tarifu účtu, povolené typy vrací /me v card_types (job a object = asset s tímto druhem). Kód, který už typ má, jde upravovat dál.
404 kód neexistuje, nepatří účtu, nebo je mimo skupiny klíče.
409 plný limit kódů, souborů nebo úložiště. 422 chybná pole (podrobnosti ve fields).
429 víc než 60 požadavků za minutu na klíč. Hlavičky X-RateLimit-Remaining a Retry-After řeknou, kdy znovu.

API funguje jen přes HTTPS a nepoužívá cookies. Volání z prohlížeče na cizím webu (CORS) není povolené, klíč patří jen na server.

Chcete API zapnout pro svůj účet? Napište na info@qrlink.cz, případně se podívejte na přehled možností API nebo ceník.