{"openapi":"3.1.0","info":{"title":"Kverton API","version":"1","description":"Dynamické kódy, statistiky, vykreslení, webhooky. Klíč v hlavičce Authorization: Bearer."},"servers":[{"url":"https://kverton.cz/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/me":{"get":{"operationId":"me","summary":"Tým, tarif a kvóta","description":"Komu klíč patří, jaký tarif tým má a kolik volání dnes zbývá.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"team":{"id":12,"name":"Kavárna U Lípy","plan":"pro"},"limits":{"dynamic_codes":50,"api_calls_per_day":5000},"usage":{"api_calls_today":42,"dynamic_codes":7}}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}}}},"/codes":{"get":{"operationId":"codes.list","summary":"Seznam dynamických kódů","description":"Stránkovaný seznam. Filtr podle skupiny a textu v popisku.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":1234,"slug":"a7k2m","short_url":"https://kvrt.net/a7k2m","label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","active":true,"expires_at":null,"group_id":null,"password_protected":false,"utm":{"source":"kverton","medium":"qr","campaign":null},"safety_state":"clear","created_at":"2026-09-01T10:00:00Z","last_scan_at":"2026-09-03T08:12:00Z"}],"page":1,"per_page":50,"total":1}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"group","in":"query","required":false,"schema":{"type":"integer"},"description":"ID skupiny"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Hledání v popisku"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Stránka (od 1)"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Velikost stránky (1–200, výchozí 50)"}]},"post":{"operationId":"codes.create","summary":"Založit dynamický kód","description":"Vrátí kód včetně krátké adresy. Kód vytiskněte jako QR s obsahem short_url (SVG umí /render).","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":1234,"slug":"a7k2m","short_url":"https://kvrt.net/a7k2m","label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","active":true,"expires_at":null,"group_id":null,"password_protected":false,"utm":{"source":"kverton","medium":"qr","campaign":null},"safety_state":"clear","created_at":"2026-09-01T10:00:00Z","last_scan_at":"2026-09-03T08:12:00Z"}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","expires_at":"2026-12-31","group_id":null,"password":null,"utm":{"source":"kverton","medium":"qr","campaign":"podzim"}}}}}}},"/codes/{id}":{"get":{"operationId":"codes.get","summary":"Detail kódu","description":"Jeden kód včetně pravidel přesměrování.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":1234,"slug":"a7k2m","short_url":"https://kvrt.net/a7k2m","label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","active":true,"expires_at":null,"group_id":null,"password_protected":false,"utm":{"source":"kverton","medium":"qr","campaign":null},"safety_state":"clear","created_at":"2026-09-01T10:00:00Z","last_scan_at":"2026-09-03T08:12:00Z","rules":[{"kind":"device","match":"ios","target_url":"https://apps.apple.com/app/x"}]}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}]},"patch":{"operationId":"codes.update","summary":"Upravit kód","description":"Změna cíle se zapíše do historie (rollback níže). Pošlete jen pole, která měníte. active=false kód pozastaví.","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":1234,"slug":"a7k2m","short_url":"https://kvrt.net/a7k2m","label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","active":true,"expires_at":null,"group_id":null,"password_protected":false,"utm":{"source":"kverton","medium":"qr","campaign":null},"safety_state":"clear","created_at":"2026-09-01T10:00:00Z","last_scan_at":"2026-09-03T08:12:00Z"}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"target_url":"https://eshop.cz/menu-zima","label":"Zimní menu","active":true,"expires_at":null,"password":"-","utm":{"campaign":"zima"},"rules":[{"kind":"country","match":"SK","target_url":"https://eshop.sk/menu"}]}}}}},"delete":{"operationId":"codes.delete","summary":"Smazat kód","description":"Nevratné — vytištěný kód přestane fungovat. Zvažte spíš active=false.","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"deleted":true}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}]}},"/codes/{id}/stats":{"get":{"operationId":"codes.stats","summary":"Statistika skenů","description":"Po dnech (podle historie tarifu), země, regiony, města, jazyky. Bez IP adres — ty neukládáme.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"total":166,"last_24h":12,"days":[{"day":"2026-09-02","visits":11,"impressions":13}],"countries":[{"key":"CZ","count":106}],"cities":[{"key":"Praha","count":61}],"langs":[{"key":"cs","count":120}]}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}]}},"/codes/{id}/history":{"get":{"operationId":"codes.history","summary":"Historie cílů","description":"Verze cíle, nejnovější první.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":501,"target_url":"https://eshop.cz/menu-podzim","changed_at":"2026-09-01T10:00:00Z"}]}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}]}},"/codes/{id}/rollback":{"post":{"operationId":"codes.rollback","summary":"Vrátit starší cíl","description":"Návrat na verzi z historie; sám se zapíše jako nová verze.","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":1234,"slug":"a7k2m","short_url":"https://kvrt.net/a7k2m","label":"Podzimní menu","target_url":"https://eshop.cz/menu-podzim","active":true,"expires_at":null,"group_id":null,"password_protected":false,"utm":{"source":"kverton","medium":"qr","campaign":null},"safety_state":"clear","created_at":"2026-09-01T10:00:00Z","last_scan_at":"2026-09-03T08:12:00Z"}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID kódu"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"history_id":501}}}}}},"/groups":{"get":{"operationId":"groups.list","summary":"Skupiny kódů","description":"Skupiny týmu s počty kódů.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":3,"name":"Akce","codes":12}]}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}}}},"/render":{"post":{"operationId":"render","summary":"Vykreslit QR jako SVG","description":"Obsah → SVG (vektor, čistý vzhled, klidová zóna). Pro dynamický kód pošlete jeho short_url. Formáty: qr, datamatrix, azteccode, rmqr.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"svg":"<svg …>","size":29}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"content":"https://kvrt.net/a7k2m","format":"qr","ecl":"M","module_color":"#302B23","background":"#FFFFFF"}}}}}},"/webhooks":{"get":{"operationId":"webhooks.list","summary":"Webhooky týmu","description":"Adresy, události, stav posledního doručení.","security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":7,"url":"https://example.cz/hooks/kverton","events":["scan","code.updated"],"active":true,"last_status":200}]}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}}},"post":{"operationId":"webhooks.create","summary":"Přidat webhook","description":"Jen https. Tajemství (secret) se vrátí jednou — ověřujte jím podpis X-Kverton-Signature (sha256=HMAC-SHA256 těla).","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":7,"secret":"3f9c…"}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"url":"https://example.cz/hooks/kverton","events":["scan","code.updated"]}}}}}},"/webhooks/{id}":{"delete":{"operationId":"webhooks.delete","summary":"Odebrat webhook","description":"Nedoručené události se zahodí.","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"deleted":true}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID webhooku"}]}},"/webhooks/{id}/test":{"post":{"operationId":"webhooks.test","summary":"Zkušební událost","description":"Zařadí událost webhook.test; doručí se do minuty.","security":[{"bearer":[]}],"x-scope":"write","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"queued":true}}}},"401":{"description":"Chybný nebo zneplatněný klíč"},"429":{"description":"Kvóta nebo rate limit"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID webhooku"}]}}}}