REST API v1
Kverton API
Dynamické kódy, štatistiky, vykreslenie a webhooky z vášho systému. REST, JSON, kľúč v hlavičke. Statické kódy ostávajú zadarmo v prehliadači — API je pre to, čo bez nášho servera nejde.
Začíname
- V nastavení tímu (Tímy → tím → API kľúče) založte kľúč. Ukáže sa len raz.
- Každá požiadavka nesie hlavičku
Authorization: Bearer kv_… - Základná adresa:
https://kverton.cz/api/v1
- Formát
- JSON dnu aj von (Content-Type: application/json), UTF-8, časy v ISO 8601 (UTC). Verzia v ceste (/v1) — nekompatibilná zmena dostane novú.
- Chyby
{"error":{"code":"quota","message":"…"}}· 401 · 403 · 404 · 422 · 429 · 500- Limity
- Denná kvóta podľa tarify (na tím; v hlavičkách X-RateLimit-Quota a X-RateLimit-Remaining) a 120 volaní za minútu na kľúč. Pri prekročení 429.
- OpenAPI
- /api/v1/openapi.json — strojovo čitateľný popis pre generátory klientov
https://kverton.cz/qr.svg · /qr.png
bez kľúča
Obrázok kódu pre <img>
Statické kódy sú zadarmo — aj ako obrázok pre šablóny e-mailov, CMS alebo PHP echo, kde nie je JavaScript ani kľúč. Obsah sa u nás neukladá; hotový obrázok sa cachuje deň (ETag).
| Parameter | |
|---|---|
| data * | obsah kódu, URL-encoded (rawurlencode), do 2000 znakov |
| size | png: strana v px, 64–2000 (predvolené 512); svg je vektor bez rozmeru |
| format | qr · datamatrix · azteccode · rmqr |
| ecl | L · M · Q · H |
| color, bg | hex bez #, napr. color=302B23&bg=FFFFFF — kontrast si strážte, obrázok sa neoveruje dekodérom |
<img width="225" height="225" alt="QR"
src="https://kverton.cz/qr.png?size=225&data=bitcoin:bc1q…?amount=0.01%26label=Invoice">
<?php echo '<img src="https://kverton.cz/qr.svg?data=' . rawurlencode($uri) . '">'; ?>
Limit 60 obrázkov za minútu z jednej adresy. Pre dynamické kódy, štatistiky a webhooky použite API s kľúčom nižšie.
Ako zostaviť data — všetky druhy obsahu
Pravidlá
- Celú hodnotu zakódujte (
rawurlencodev PHP,encodeURIComponentv JS). Bez toho&vnútri obsahu rozdelí parametre a medzera sa stratí. - Nové riadky (vCard, EPC, udalosť) sú v URL
%0A; kódovanie to zvládne samo, keď je v reťazci\n. - UTF-8 a diakritika sú v poriadku. Kapacita: QR do 2 000 znakov, Data Matrix do 1 500, rMQR do 361.
- Rovnaké pravidlá platia pre
contentvPOST /api/v1/render(tam bez URL kódovania — ide v JSON). - Kód z obrázkového endpointu sa neoveruje dekodérom. Držte kontrast a pokojovú zónu.
// PHP $data = "SPD*1.0*ACC:CZ6508000000192000145399*AM:450.00*CC:CZK*X-VS:2026041"; echo '<img src="https://kverton.cz/qr.png?size=300&data=' . rawurlencode($data) . '">'; // JavaScript const src = 'https://kverton.cz/qr.svg?data=' + encodeURIComponent(data);
| Druh | Tvar | Príklad |
|---|---|---|
| Odkaz | Absolutní URL včetně https://. Čtečka Kverton u něj prověří přesměrování, Safe Browsing a stáří domény. |
https://example.cz/menu?stul=5
ako to vyzerá v URL?data=https%3A%2F%2Fexample.cz%2Fmenu%3Fstul%3D5 |
| Česká platba (SPD) | Norma Short Payment Descriptor: SPD*1.0* a pole oddělená *: ACC IBAN (volitelně +BIC), AM částka s tečkou, CC měna, X-VS/X-SS/X-KS symboly, MSG zpráva (do 60 znaků), DT splatnost YYYYMMDD, RN název příjemce. Bankovní aplikace v ČR čtou přímo. |
SPD*1.0*ACC:CZ6508000000192000145399*AM:450.00*CC:CZK*X-VS:2026041*MSG:Faktura 2026041*DT:20261015
ako to vyzerá v URL?data=SPD%2A1.0%2AACC%3ACZ6508000000192000145399%2AAM%3A450.00%2ACC%3ACZK%2AX-VS%3A2026041%2AMSG%3AFaktura%202026041%2ADT%3A20261015 |
| Evropská platba (EPC / SEPA) | Norma EPC069-12: přesně 11 řádků — BCD, verze 002, kódování 1, SCT, BIC, název příjemce, IBAN, částka EUR12.50, účel (prázdný), reference (prázdná), zpráva. Řádky nesmí chybět ani prázdné. |
BCD
002
1
SCT
GIBACZPX
Firma s.r.o.
CZ6508000000192000145399
EUR12.50
Faktura 41
ako to vyzerá v URL?data=BCD%0A002%0A1%0ASCT%0AGIBACZPX%0AFirma%20s.r.o.%0ACZ6508000000192000145399%0AEUR12.50%0A%0A%0AFaktura%2041 |
| Slovenská platba (Pay by square) | Obsah je komprimovaný binární payload — ručně se nesestaví. Použijte generátor na kverton.sk nebo API (POST /codes ho nedělá; statický kód z formuláře Slovenská platba). |
— |
| Wi-Fi | WIFI:T:WPA;S:název;P:heslo;H:false;; — T WPA/WEP/nopass, H:true skrytá síť. V názvu a hesle escapujte \; \, \: \\. Na konci dva středníky. |
WIFI:T:WPA;S:Kavarna U Lipy;P:tajne-heslo;H:false;;
ako to vyzerá v URL?data=WIFI%3AT%3AWPA%3BS%3AKavarna%20U%20Lipy%3BP%3Atajne-heslo%3BH%3Afalse%3B%3B |
| Vizitka (vCard 3.0) | Nejrozšířenější formát pro kontakty; telefon i iPhone nabídnou uložení. N příjmení;jméno, FN celé jméno, TEL;TYPE=CELL, EMAIL, ORG, URL, ADR. Řádky oddělené novým řádkem. |
BEGIN:VCARD
VERSION:3.0
N:Novák;Jan;;;
FN:Jan Novák
ORG:Firma s.r.o.
TEL;TYPE=CELL:+420777123456
EMAIL:jan@firma.cz
URL:https://firma.cz
END:VCARD
ako to vyzerá v URL?data=BEGIN%3AVCARD%0AVERSION%3A3.0%0AN%3ANov%C3%A1k%3BJan%3B%3B%3B%0AFN%3AJan%20Nov%C3%A1k%0AORG%3AFirma%20s.r.o.%0ATEL%3BTYPE%3DCELL%3A%2B420777123456%0AEMAIL%3Ajan%40firma.cz%0AURL%3Ahttps%3A%2F%2Ffirma.cz%0AEND%3AVCARD |
| Vizitka (MeCard) | Úspornější než vCard — vejde se do menšího kódu. Pole N (Příjmení,Jméno), TEL, EMAIL, URL, ADR, NOTE; na konci ;;. |
MECARD:N:Novák,Jan;TEL:+420777123456;EMAIL:jan@firma.cz;URL:https://firma.cz;;
ako to vyzerá v URL?data=MECARD%3AN%3ANov%C3%A1k%2CJan%3BTEL%3A%2B420777123456%3BEMAIL%3Ajan%40firma.cz%3BURL%3Ahttps%3A%2F%2Ffirma.cz%3B%3B |
mailto: s volitelnými subject a body (zakódované — mezery %20). |
mailto:info@firma.cz?subject=Dotaz&body=Dobrý den,
ako to vyzerá v URL?data=mailto%3Ainfo%40firma.cz%3Fsubject%3DDotaz%26body%3DDobr%C3%BD%20den%2C |
|
| Telefon | tel: s číslem v mezinárodním tvaru (+420…), bez mezer. |
tel:+420777123456
ako to vyzerá v URL?data=tel%3A%2B420777123456 |
| SMS | SMSTO:číslo:text — nejkompatibilnější tvar (Android i iPhone). Alternativa sms:číslo?body=text. |
SMSTO:+420777123456:Text zprávy
ako to vyzerá v URL?data=SMSTO%3A%2B420777123456%3AText%20zpr%C3%A1vy |
https://wa.me/číslo bez +, volitelně ?text= předvyplněná zpráva. |
https://wa.me/420777123456?text=Dobrý den
ako to vyzerá v URL?data=https%3A%2F%2Fwa.me%2F420777123456%3Ftext%3DDobr%C3%BD%20den |
|
| Telegram | https://t.me/uživatel nebo odkaz na skupinu. |
https://t.me/uzivatel
ako to vyzerá v URL?data=https%3A%2F%2Ft.me%2Fuzivatel |
| Poloha | geo:lat,lng; ?q=lat,lng(Popisek) přidá špendlík s názvem. Otevírá mapovou aplikaci. |
geo:50.0755,14.4378?q=50.0755,14.4378(Kavárna U Lípy)
ako to vyzerá v URL?data=geo%3A50.0755%2C14.4378%3Fq%3D50.0755%2C14.4378%28Kav%C3%A1rna%20U%20L%C3%ADpy%29 |
| Událost do kalendáře | BEGIN:VEVENT…END:VEVENT (iCalendar): SUMMARY, DTSTART/DTEND v UTC (Z) nebo s TZID, LOCATION, DESCRIPTION. Obal VCALENDAR doplní čtečka. |
BEGIN:VEVENT
SUMMARY:Schůzka
DTSTART:20260930T090000Z
DTEND:20260930T100000Z
LOCATION:Praha
END:VEVENT
ako to vyzerá v URL?data=BEGIN%3AVEVENT%0ASUMMARY%3ASch%C5%AFzka%0ADTSTART%3A20260930T090000Z%0ADTEND%3A20260930T100000Z%0ALOCATION%3APraha%0AEND%3AVEVENT |
| Dvoufaktorový klíč (TOTP) | otpauth://totp/Vydavatel:účet?secret=BASE32&issuer=Vydavatel; volitelně digits, period, algorithm. Tajemství je citlivé — kód netiskněte na veřejná místa. |
otpauth://totp/Firma:jan@firma.cz?secret=JBSWY3DPEHPK3PXP&issuer=Firma&digits=6&period=30
ako to vyzerá v URL?data=otpauth%3A%2F%2Ftotp%2FFirma%3Ajan%40firma.cz%3Fsecret%3DJBSWY3DPEHPK3PXP%26issuer%3DFirma%26digits%3D6%26period%3D30 |
| Krypto platba (BIP-21) | bitcoin:adresa?amount=0.01&label=…&message=…; Ethereum ethereum:0x…?value=…. Kvůli & nutně celé zakódovat. |
bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.01&label=Faktura 41
ako to vyzerá v URL?data=bitcoin%3Abc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq%3Famount%3D0.01%26label%3DFaktura%2041 |
| Odkaz na aplikaci | Odkaz do App Store nebo Google Play; jeden kód pro oba obchody vyřeší dynamický kód s pravidlem podle zařízení. |
https://apps.apple.com/app/id123456789 · https://play.google.com/store/apps/details?id=cz.firma.app
ako to vyzerá v URL?data=https%3A%2F%2Fapps.apple.com%2Fapp%2Fid123456789%20%C2%B7%20https%3A%2F%2Fplay.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcz.firma.app |
| Videoschůzka | Odkaz na Google Meet, Teams, Zoom — obyčejná URL. |
https://meet.google.com/abc-defg-hij
ako to vyzerá v URL?data=https%3A%2F%2Fmeet.google.com%2Fabc-defg-hij |
| GS1 Digital Linkformat=datamatrix | Norma pro obaly: https://id.gs1.org/01/GTIN/10/šarže/17/expirace(YYMMDD)/21/sériové. Na obalech se tiskne jako Data Matrix (format=datamatrix). |
https://id.gs1.org/01/09506000134352/10/ABC123/17/261231
ako to vyzerá v URL?data=https%3A%2F%2Fid.gs1.org%2F01%2F09506000134352%2F10%2FABC123%2F17%2F261231 |
| Prostý text | Cokoli, co se má jen zobrazit. Čtečka nabídne kopírování. |
Libovolný text, včetně diakritiky a nových řádků.
ako to vyzerá v URL?data=Libovoln%C3%BD%20text%2C%20v%C4%8Detn%C4%9B%20diakritiky%20a%20nov%C3%BDch%20%C5%99%C3%A1dk%C5%AF. |
Formát symbolu, korekcia, veľkosť
- QR (výchozí) — univerzální; všechny telefony, platby, wifi.
- Data Matrix — nejmenší plocha na znak; obaly, štítky, elektronika, GS1. Telefony ho čtou, ale bankovní aplikace ne.
- Aztec — bez klidové zóny, hodí se na jízdenky a vstupenky do těsných rámečků.
- rMQR — obdélníkový QR pro úzké lišty (do 361 znaků); starší čtečky ho neznají, Kverton ano.
- ecl: L 7 % · M 15 % (výchozí) · Q 25 % · H 30 % poškozených modulů se opraví. Tisk na papír: M; venkovní nebo s logem: Q/H (kód je větší).
- Velikost tisku: modul ≥ 0,5 mm (běžná QR verze 3 tedy ≥ 2 cm), skenování z 1 m ≥ 5 cm. PNG žádejte aspoň 300 px na 3 cm tisku, jinak vektorové SVG.
/me
Práva: read
Tým, tarif a kvóta
Komu klíč patří, jaký tarif tým má a kolik volání dnes zbývá.
Odpoveď
{
"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
}
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/me' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/me');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/me', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/me"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes
Práva: read
Seznam dynamických kódů
Stránkovaný seznam. Filtr podle skupiny a textu v popisku.
| Parameter | in | Typ | |
|---|---|---|---|
| group | query | integer | ID skupiny |
| q | query | string | Hledání v popisku |
| page | query | integer | Stránka (od 1) |
| per_page | query | integer | Velikost stránky (1–200, výchozí 50) |
Odpoveď
{
"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
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/codes' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes
Práva: write
Založit dynamický kód
Vrátí kód včetně krátké adresy. Kód vytiskněte jako QR s obsahem short_url (SVG umí /render).
Telo požiadavky
{
"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"
}
}Odpoveď
{
"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"
}Ukážky: curl · PHP · JavaScript · Java
curl -X POST 'https://kverton.cz/api/v1/codes' \
-H 'Authorization: Bearer kv_XXXXXXXX_…' \
-H 'Content-Type: application/json' \
-d '{"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"}}'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(array (
'label' => 'Podzimní menu',
'target_url' => 'https://eshop.cz/menu-podzim',
'expires_at' => '2026-12-31',
'group_id' => NULL,
'password' => NULL,
'utm' =>
array (
'source' => 'kverton',
'medium' => 'qr',
'campaign' => 'podzim',
),
)),
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes', {
method: 'POST',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
body: JSON.stringify({"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"}}),
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"label\":\"Podzimn\u00ed 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\"}}"))
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}
Práva: read
Detail kódu
Jeden kód včetně pravidel přesměrování.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Odpoveď
{
"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"
}
]
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/codes/1234' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}
Práva: write
Upravit kód
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í.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Telo požiadavky
{
"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"
}
]
}Odpoveď
{
"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"
}Ukážky: curl · PHP · JavaScript · Java
curl -X PATCH 'https://kverton.cz/api/v1/codes/1234' \
-H 'Authorization: Bearer kv_XXXXXXXX_…' \
-H 'Content-Type: application/json' \
-d '{"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"}]}'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(array (
'target_url' => 'https://eshop.cz/menu-zima',
'label' => 'Zimní menu',
'active' => true,
'expires_at' => NULL,
'password' => '-',
'utm' =>
array (
'campaign' => 'zima',
),
'rules' =>
array (
0 =>
array (
'kind' => 'country',
'match' => 'SK',
'target_url' => 'https://eshop.sk/menu',
),
),
)),
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234', {
method: 'PATCH',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
body: JSON.stringify({"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"}]}),
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("PATCH", HttpRequest.BodyPublishers.ofString("{\"target_url\":\"https:\/\/eshop.cz\/menu-zima\",\"label\":\"Zimn\u00ed menu\",\"active\":true,\"expires_at\":null,\"password\":\"-\",\"utm\":{\"campaign\":\"zima\"},\"rules\":[{\"kind\":\"country\",\"match\":\"SK\",\"target_url\":\"https:\/\/eshop.sk\/menu\"}]}"))
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}
Práva: write
Smazat kód
Nevratné — vytištěný kód přestane fungovat. Zvažte spíš active=false.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Odpoveď
{
"deleted": true
}Ukážky: curl · PHP · JavaScript · Java
curl -X DELETE 'https://kverton.cz/api/v1/codes/1234' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234', {
method: 'DELETE',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("DELETE", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}/stats
Práva: read
Statistika skenů
Po dnech (podle historie tarifu), země, regiony, města, jazyky. Bez IP adres — ty neukládáme.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Odpoveď
{
"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
}
]
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/codes/1234/stats' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234/stats');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234/stats', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234/stats"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}/history
Práva: read
Historie cílů
Verze cíle, nejnovější první.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Odpoveď
{
"data": [
{
"id": 501,
"target_url": "https://eshop.cz/menu-podzim",
"changed_at": "2026-09-01T10:00:00Z"
}
]
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/codes/1234/history' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234/history');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234/history', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234/history"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/codes/{id}/rollback
Práva: write
Vrátit starší cíl
Návrat na verzi z historie; sám se zapíše jako nová verze.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID kódu |
Telo požiadavky
{
"history_id": 501
}Odpoveď
{
"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"
}Ukážky: curl · PHP · JavaScript · Java
curl -X POST 'https://kverton.cz/api/v1/codes/1234/rollback' \
-H 'Authorization: Bearer kv_XXXXXXXX_…' \
-H 'Content-Type: application/json' \
-d '{"history_id":501}'
<?php
$ch = curl_init('https://kverton.cz/api/v1/codes/1234/rollback');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(array (
'history_id' => 501,
)),
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/codes/1234/rollback', {
method: 'POST',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
body: JSON.stringify({"history_id":501}),
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/codes/1234/rollback"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"history_id\":501}"))
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/groups
Práva: read
Skupiny kódů
Skupiny týmu s počty kódů.
Odpoveď
{
"data": [
{
"id": 3,
"name": "Akce",
"codes": 12
}
]
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/groups' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/groups');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/groups', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/groups"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/render
Práva: read
Vykreslit QR jako SVG
Obsah → SVG (vektor, čistý vzhled, klidová zóna). Pro dynamický kód pošlete jeho short_url. Formáty: qr, datamatrix, azteccode, rmqr.
Telo požiadavky
{
"content": "https://kvrt.net/a7k2m",
"format": "qr",
"ecl": "M",
"module_color": "#302B23",
"background": "#FFFFFF"
}Odpoveď
{
"svg": "<svg …>",
"size": 29
}Ukážky: curl · PHP · JavaScript · Java
curl -X POST 'https://kverton.cz/api/v1/render' \
-H 'Authorization: Bearer kv_XXXXXXXX_…' \
-H 'Content-Type: application/json' \
-d '{"content":"https://kvrt.net/a7k2m","format":"qr","ecl":"M","module_color":"#302B23","background":"#FFFFFF"}'
<?php
$ch = curl_init('https://kverton.cz/api/v1/render');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(array (
'content' => 'https://kvrt.net/a7k2m',
'format' => 'qr',
'ecl' => 'M',
'module_color' => '#302B23',
'background' => '#FFFFFF',
)),
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/render', {
method: 'POST',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
body: JSON.stringify({"content":"https://kvrt.net/a7k2m","format":"qr","ecl":"M","module_color":"#302B23","background":"#FFFFFF"}),
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/render"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"content\":\"https:\/\/kvrt.net\/a7k2m\",\"format\":\"qr\",\"ecl\":\"M\",\"module_color\":\"#302B23\",\"background\":\"#FFFFFF\"}"))
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/webhooks
Práva: read
Webhooky týmu
Adresy, události, stav posledního doručení.
Odpoveď
{
"data": [
{
"id": 7,
"url": "https://example.cz/hooks/kverton",
"events": [
"scan",
"code.updated"
],
"active": true,
"last_status": 200
}
]
}Ukážky: curl · PHP · JavaScript · Java
curl -X GET 'https://kverton.cz/api/v1/webhooks' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/webhooks');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/webhooks', {
method: 'GET',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/webhooks"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/webhooks
Práva: write
Přidat webhook
Jen https. Tajemství (secret) se vrátí jednou — ověřujte jím podpis X-Kverton-Signature (sha256=HMAC-SHA256 těla).
Telo požiadavky
{
"url": "https://example.cz/hooks/kverton",
"events": [
"scan",
"code.updated"
]
}Odpoveď
{
"id": 7,
"secret": "3f9c…"
}Ukážky: curl · PHP · JavaScript · Java
curl -X POST 'https://kverton.cz/api/v1/webhooks' \
-H 'Authorization: Bearer kv_XXXXXXXX_…' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.cz/hooks/kverton","events":["scan","code.updated"]}'
<?php
$ch = curl_init('https://kverton.cz/api/v1/webhooks');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(array (
'url' => 'https://example.cz/hooks/kverton',
'events' =>
array (
0 => 'scan',
1 => 'code.updated',
),
)),
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/webhooks', {
method: 'POST',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
body: JSON.stringify({"url":"https://example.cz/hooks/kverton","events":["scan","code.updated"]}),
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/webhooks"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"url\":\"https:\/\/example.cz\/hooks\/kverton\",\"events\":[\"scan\",\"code.updated\"]}"))
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/webhooks/{id}
Práva: write
Odebrat webhook
Nedoručené události se zahodí.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID webhooku |
Odpoveď
{
"deleted": true
}Ukážky: curl · PHP · JavaScript · Java
curl -X DELETE 'https://kverton.cz/api/v1/webhooks/1234' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/webhooks/1234');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/webhooks/1234', {
method: 'DELETE',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/webhooks/1234"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("DELETE", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
/webhooks/{id}/test
Práva: write
Zkušební událost
Zařadí událost webhook.test; doručí se do minuty.
| Parameter | in | Typ | |
|---|---|---|---|
| id * | path | integer | ID webhooku |
Odpoveď
{
"queued": true
}Ukážky: curl · PHP · JavaScript · Java
curl -X POST 'https://kverton.cz/api/v1/webhooks/1234/test' \ -H 'Authorization: Bearer kv_XXXXXXXX_…'
<?php
$ch = curl_init('https://kverton.cz/api/v1/webhooks/1234/test');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer kv_XXXXXXXX_…', 'Content-Type: application/json'],
]);
$data = json_decode((string) curl_exec($ch), true);
const res = await fetch('https://kverton.cz/api/v1/webhooks/1234/test', {
method: 'POST',
headers: { Authorization: 'Bearer kv_XXXXXXXX_…', 'Content-Type': 'application/json' },
});
const data = await res.json();
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create("https://kverton.cz/api/v1/webhooks/1234/test"))
.header("Authorization", "Bearer kv_XXXXXXXX_…")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
String json = res.body();
Webhooky
Pri udalosti pošleme POST s JSON telom na vašu https adresu. Podpis tela overte tajomstvom webhooku (vráti sa raz pri založení).
POST https://example.cz/hooks/kverton Content-Type: application/json X-Kverton-Event: scan X-Kverton-Delivery: 8812 X-Kverton-Signature: sha256=<HMAC-SHA256(secret, body)>
scan — Někdo načetl dynamický kód (bez IP adresy; země a jazyk podle GeoIP).
{
"event": "scan",
"created_at": "2026-09-03T08:12:00Z",
"data": {
"code_id": 1234,
"slug": "a7k2m",
"country": "CZ",
"lang": "cs",
"kind": "visit"
}
}
code.created — Vznikl dynamický kód.
{
"event": "code.created",
"created_at": "2026-09-03T08:12:00Z",
"data": {
"code_id": 1234,
"slug": "a7k2m",
"target_url": "https://eshop.cz/menu"
}
}
code.updated — Změnil se cíl kódu (i rollbackem).
{
"event": "code.updated",
"created_at": "2026-09-03T08:12:00Z",
"data": {
"code_id": 1234,
"target_url": "https://eshop.cz/menu-zima"
}
}
code.deleted — Kód byl smazán.
{
"event": "code.deleted",
"created_at": "2026-09-03T08:12:00Z",
"data": {
"code_id": 1234
}
}
Doručenie platí pri odpovedi 2xx. Inak opakujeme po 1 min, 5 min, 30 min, 2 h a 12 h; po 20 zlyhaniach za sebou sa webhook vypne a v nastavení tímu to uvidíte.
// PHP: verify the signature
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_KVERTON_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
Knižnice
Oficiálne tenké knižnice s MIT licenciou — otvorený kód na GitHube pod organizáciou kverton. Každá metóda je jeden koncový bod API; chyby ako výnimky; overenie podpisu webhookov v cene.
PHP Composer
composer require kverton/kverton-php
$kverton = new \Kverton\Sdk\Client('kv_…');
$code = $kverton->createCode([
'label' => 'Menu',
'target_url' => 'https://example.cz/menu',
]);
echo $code['short_url'];
github.com/kverton/kverton-php · Packagist
PHP 8.1+, bez závislostí (curl alebo streamy).
JavaScript / TypeScript npm
npm install @kverton/sdk
import { KvertonClient } from '@kverton/sdk';
const kverton = new KvertonClient('kv_…');
const code = await kverton.createCode({
label: 'Menu',
target_url: 'https://example.cz/menu',
});
console.log(code.short_url);
github.com/kverton/kverton-js · npm
Node 18+, Deno, Bun, edge — globálny fetch; plne typované.
MCP AI asistenti
npx -y @kverton/mcp
{
"mcpServers": {
"kverton": {
"command": "npx",
"args": ["-y", "@kverton/mcp"],
"env": { "KVERTON_API_KEY": "kv_…" }
}
}
}
github.com/kverton/kverton-mcp · MCP →
Claude, ChatGPT, Cursor a ďalší — 13 nástrojov nad API.
Iný jazyk? Klienta vygeneruje OpenAPI popis (openapi-generator): /api/v1/openapi.json