Vytvořit

REST API v1

Kverton API

Dynamické kódy, statistiky, vykreslení a webhooky z vašeho systému. REST, JSON, klíč v hlavičce. Statické kódy zůstávají zdarma v prohlížeči — API je pro to, co bez našeho serveru nejde.

Začínáme

  1. V nastavení týmu (Týmy → tým → API klíče) založte klíč. Ukáže se jen jednou.
  2. Každý požadavek nese hlavičku Authorization: Bearer kv_…
  3. Základní adresa: https://kverton.cz/api/v1
Formát
JSON dovnitř i ven (Content-Type: application/json), UTF-8, časy v ISO 8601 (UTC). Verze v cestě (/v1) — nekompatibilní změna dostane novou.
Chyby
{"error":{"code":"quota","message":"…"}} · 401 · 403 · 404 · 422 · 429 · 500
Limity
Denní kvóta podle tarifu (na tým; v hlavičkách X-RateLimit-Quota a X-RateLimit-Remaining) a 120 volání za minutu na klíč. Při překročení 429.
OpenAPI
/api/v1/openapi.json — strojově čitelný popis pro generátory klientů
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á.

Odpověď

{
    "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ázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/me' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
GET /codes Práva: read

Seznam dynamických kódů

Stránkovaný seznam. Filtr podle skupiny a textu v popisku.

ParametrinTyp
groupqueryintegerID skupiny
qquerystringHledání v popisku
pagequeryintegerStránka (od 1)
per_pagequeryintegerVelikost stránky (1–200, výchozí 50)

Odpověď

{
    "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ázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/codes' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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).

Tělo požadavku

{
    "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"
    }
}

Odpověď

{
    "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ázky: 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"}}'
GET /codes/{id} Práva: read

Detail kódu

Jeden kód včetně pravidel přesměrování.

ParametrinTyp
id *pathintegerID kódu

Odpověď

{
    "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ázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/codes/1234' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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í.

ParametrinTyp
id *pathintegerID kódu

Tělo požadavku

{
    "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"
        }
    ]
}

Odpověď

{
    "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ázky: 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"}]}'
DELETE /codes/{id} Práva: write

Smazat kód

Nevratné — vytištěný kód přestane fungovat. Zvažte spíš active=false.

ParametrinTyp
id *pathintegerID kódu

Odpověď

{
    "deleted": true
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X DELETE 'https://kverton.cz/api/v1/codes/1234' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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.

ParametrinTyp
id *pathintegerID kódu

Odpověď

{
    "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ázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/codes/1234/stats' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
GET /codes/{id}/history Práva: read

Historie cílů

Verze cíle, nejnovější první.

ParametrinTyp
id *pathintegerID kódu

Odpověď

{
    "data": [
        {
            "id": 501,
            "target_url": "https://eshop.cz/menu-podzim",
            "changed_at": "2026-09-01T10:00:00Z"
        }
    ]
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/codes/1234/history' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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.

ParametrinTyp
id *pathintegerID kódu

Tělo požadavku

{
    "history_id": 501
}

Odpověď

{
    "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ázky: 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}'
GET /groups Práva: read

Skupiny kódů

Skupiny týmu s počty kódů.

Odpověď

{
    "data": [
        {
            "id": 3,
            "name": "Akce",
            "codes": 12
        }
    ]
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/groups' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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.

Tělo požadavku

{
    "content": "https://kvrt.net/a7k2m",
    "format": "qr",
    "ecl": "M",
    "module_color": "#302B23",
    "background": "#FFFFFF"
}

Odpověď

{
    "svg": "<svg …>",
    "size": 29
}
Ukázky: 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"}'
GET /webhooks Práva: read

Webhooky týmu

Adresy, události, stav posledního doručení.

Odpověď

{
    "data": [
        {
            "id": 7,
            "url": "https://example.cz/hooks/kverton",
            "events": [
                "scan",
                "code.updated"
            ],
            "active": true,
            "last_status": 200
        }
    ]
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X GET 'https://kverton.cz/api/v1/webhooks' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
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).

Tělo požadavku

{
    "url": "https://example.cz/hooks/kverton",
    "events": [
        "scan",
        "code.updated"
    ]
}

Odpověď

{
    "id": 7,
    "secret": "3f9c…"
}
Ukázky: 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"]}'
DELETE /webhooks/{id} Práva: write

Odebrat webhook

Nedoručené události se zahodí.

ParametrinTyp
id *pathintegerID webhooku

Odpověď

{
    "deleted": true
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X DELETE 'https://kverton.cz/api/v1/webhooks/1234' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'
POST /webhooks/{id}/test Práva: write

Zkušební událost

Zařadí událost webhook.test; doručí se do minuty.

ParametrinTyp
id *pathintegerID webhooku

Odpověď

{
    "queued": true
}
Ukázky: curl · PHP · JavaScript · Java 
curl -X POST 'https://kverton.cz/api/v1/webhooks/1234/test' \
  -H 'Authorization: Bearer kv_XXXXXXXX_…'

Webhooky

Při události pošleme POST s JSON tělem na vaši https adresu. Podpis těla ověřte tajemstvím webhooku (vrátí se jednou při 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čení platí při odpovědi 2xx. Jinak opakujeme po 1 min, 5 min, 30 min, 2 h a 12 h; po 20 selháních v řadě se 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; }

Knihovny

Oficiální tenké knihovny s MIT licencí — otevřený kód na GitHubu pod organizací kverton. Každá metoda je jeden koncový bod API; chyby jako výjimky; ověření podpisu webhooků v ceně.

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 nebo 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ální fetch; plně 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 další — 13 nástrojů nad API.

Jiný jazyk? Klienta vygeneruje OpenAPI popis (openapi-generator): /api/v1/openapi.json