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
GET
/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();
GET
/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();
POST
/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();
GET
/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();
PATCH
/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();
DELETE
/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();
GET
/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();
GET
/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();
POST
/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();
GET
/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();
POST
/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();
GET
/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();
POST
/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();
DELETE
/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();
POST
/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: PHP (Composer kverton/kverton-php), JavaScript/TypeScript (npm @kverton/sdk) a MCP server pre AI asistentov (npm @kverton/mcp) — všetko na GitHube pod organizáciou kverton. Pre ostatné jazyky vygeneruje klienta OpenAPI popis (openapi-generator).