Vytvoriť

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

  1. V nastavení tímu (Tímy → tím → API kľúče) založte kľúč. Ukáže sa len raz.
  2. Každá požiadavka nesie hlavičku Authorization: Bearer kv_…
  3. 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 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
sizepng: strana v px, 64–2000 (predvolené 512); svg je vektor bez rozmeru
formatqr · datamatrix · azteccode · rmqr
eclL · M · Q · H
color, bghex 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 (rawurlencode v PHP, encodeURIComponent v 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 content v POST /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
E-mail 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
WhatsApp 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.
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_…'
GET /codes Práva: read

Seznam dynamických kódů

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

ParameterinTyp
groupqueryintegerID skupiny
qquerystringHledání v popisku
pagequeryintegerStránka (od 1)
per_pagequeryintegerVelikost 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_…'
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"}}'
GET /codes/{id} Práva: read

Detail kódu

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

ParameterinTyp
id *pathintegerID 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_…'
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í.

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

Smazat kód

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

ParameterinTyp
id *pathintegerID 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_…'
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.

ParameterinTyp
id *pathintegerID 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_…'
GET /codes/{id}/history Práva: read

Historie cílů

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

ParameterinTyp
id *pathintegerID 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_…'
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.

ParameterinTyp
id *pathintegerID 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}'
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_…'
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"}'
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_…'
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"]}'
DELETE /webhooks/{id} Práva: write

Odebrat webhook

Nedoručené události se zahodí.

ParameterinTyp
id *pathintegerID 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_…'
POST /webhooks/{id}/test Práva: write

Zkušební událost

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

ParameterinTyp
id *pathintegerID 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_…'

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