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 https://kverton.cz/qr.svg · /qr.png bez klíče

Obrázek kódu pro <img>

Statické kódy jsou zdarma — i jako obrázek pro šablony e-mailů, CMS nebo PHP echo, kde není JavaScript ani klíč. Obsah se u nás neukládá; hotový obrázek se cachuje den (ETag).

Parametr
data *obsah kódu, URL-encoded (rawurlencode), do 2000 znaků
sizepng: strana v px, 64–2000 (výchozí 512); svg je vektor bez rozměru
formatqr · datamatrix · azteccode · rmqr
eclL · M · Q · H
color, bghex bez #, např. color=302B23&bg=FFFFFF — kontrast si hlídejte, obrázek se neověřuje dekodérem
<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ázků za minutu z jedné adresy. Pro dynamické kódy, statistiky a webhooky použijte API s klíčem níže.

Jak sestavit data — všechny druhy obsahu

Pravidla

  • Celou hodnotu zakódujte (rawurlencode v PHP, encodeURIComponent v JS). Bez toho & uvnitř obsahu rozdělí parametry a mezera se ztratí — přesně to se stane u bitcoin:…?amount=…&label=….
  • Nové řádky (vCard, EPC, událost) jsou v URL %0A; kódování zakódování zvládne samo, když je v řetězci \n.
  • UTF-8 a diakritika jsou v pořádku — QR to unese, čtečky to přečtou. Kapacita: QR do 2 000 znaků (my omezujeme na 2 000), Data Matrix do 1 500, rMQR do 361.
  • Stejná pravidla platí pro content v POST /api/v1/render (tam bez URL kódování — jde v JSON).
  • Kód z obrázkového endpointu se neověřuje dekodérem (na rozdíl od editoru). Držte kontrast a klidovou zónu; barvy volte tmavé na světlém.
// 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 Pří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
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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;;
jak to vypadá 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
jak to vypadá 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;;
jak to vypadá v URL?data=MECARD%3AN%3ANov%C3%A1k%2CJan%3BTEL%3A%2B420777123456%3BEMAIL%3Ajan%40firma.cz%3BURL%3Ahttps%3A%2F%2Ffirma.cz%3B%3B
E-mail mailto: s volitelnými subject a body (zakódované — mezery %20). mailto:info@firma.cz?subject=Dotaz&body=Dobrý den,
jak to vypadá 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
jak to vypadá 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
jak to vypadá v URL?data=SMSTO%3A%2B420777123456%3AText%20zpr%C3%A1vy
WhatsApp https://wa.me/číslo bez +, volitelně ?text= předvyplněná zpráva. https://wa.me/420777123456?text=Dobrý den
jak to vypadá 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
jak to vypadá 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)
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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
jak to vypadá 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ů.
jak to vypadá 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, korekce, velikost

  • 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.
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