Dokumentácia API

Začnite testovacím kľúčom. Vydáva sa v administrácii po registrácii a je zadarmo — sandbox sa neúčtuje, lebo účtovať niekomu, že skúša, je najspoľahlivejší spôsob, ako ho odnaučiť skúšať. Doklady z neho sa nikdy neodošlú do Peppolu ani Finančnej správe, majú vlastný číselný rad s predponou TEST- a nevstupujú do DPH prehľadov.

# 1. Vystavte doklad. Idempotency-Key je vaše číslo objednávky.
curl -X POST http://127.0.0.1:3100/v1/documents \
  -H "Authorization: Bearer kvi_test_..." \
  -H "Idempotency-Key: objednavka-1042" \
  -H "content-type: application/json" \
  -d '{
    "issueDate": "2027-03-14",
    "taxPointDate": "2027-03-14",
    "dueDate": "2027-03-28",
    "buyer": {
      "name": "Odberateľ s.r.o.",
      "vatNumber": "SK2020317068",
      "address": { "street": "Hlavná 1", "city": "Bratislava",
                   "postalCode": "81101", "countryCode": "SK" }
    },
    "lines": [{
      "name": "Konzultácie", "quantity": "8", "unitCode": "HUR",
      "netUnitPrice": "75.00", "vat": { "category": "S", "rate": "23" }
    }]
  }'

# 2. Vystavenie mu pridelí číslo. Až tu doklad prestáva byť meniteľný.
curl -X POST http://127.0.0.1:3100/v1/documents/{id}/issue \
  -H "Authorization: Bearer kvi_test_..." \
  -H "Idempotency-Key: objednavka-1042-issue"

Tri veci, ktoré si v ručne písanom klientovi treba ustrážiť: idempotency kľúč musí prežiť opakovanie, vetviť sa treba podľa stabilného kódu chyby a nie podľa jej textu, a podpis webhooku sa overuje nad surovým telom. Presne to za vás urobia knižnice nižšie, keď vyjdú.

Každá z nich existuje preto, že v ručne písaných klientoch sa opakovali tie isté tri chyby: chýbajúci idempotency kľúč pri opakovaní, vetvenie podľa textu chyby namiesto kódu, a overovanie podpisu webhooku nad znovuzloženým JSON-om namiesto surového tela.

Konektor na Shoptet máme napísaný, doplnok v ich katalógu ešte nie. Keď ktorákoľvek z týchto vecí vyjde, objaví sa v zozname zmien — nie v tichosti.

Authorization: Bearer kvi_… pre ostrý kľúč, kvi_test_… pre sandbox. Kľúč vidí len to, na čo bol vydaný; pri chýbajúcom rozsahu príde 403 insufficient_scope a v správe je uvedené, ktorý rozsah chýba.

Povolený je konkrétny rozsah, skupinový zástupný znak (documents:*) aj *. Pre e-shop zvyčajne stačí documents:*, customers:* a lookup:read.

@kvitos/mcp pripojí vášho asistenta — Claude, Cursor — k vašim dokladom. Beží na vašom počítači s vaším kľúčom; nič z toho nehostíme. Odpovedá na otázky, ktoré si aj tak kladiete: kto mi dlhuje, prečo tá faktúra neodišla, nie je tento náklad zapísaný dvakrát.

Faktúru nevystaví a návrh, ktorý pripraví, potvrdzuje človek — kľúč to nedokáže, nech má akékoľvek rozsahy.

Návod na pripojenie asistenta

• Ten istý kľúč a to isté telo → uložená odpoveď, označená hlavičkou Idempotency-Replayed: true.
• Ten istý kľúč, iné telo → 422 idempotency_key_reused. To je znovupoužitý kľúč, nie opakovanie.
• Ten istý kľúč, kým prvá požiadavka beží → 409, skúste o chvíľu.
• Prvá požiadavka spadla na 5xx → neuloží sa nič, opakovanie je naozaj opakovanie.
• Uložený výsledok je k dispozícii 24 hodín.

Najlepší kľúč je niečo prirodzené — číslo objednávky. Vygenerovaný náhodný kľúč ochráni pred prerušeným spojením, nie pred vaším vlastným dvojitým volaním.

{
  "error": {
    "code": "insufficient_scope",
    "message": "API kľúč nemá rozsah documents:write."
  }
}

Rozhodujte sa podľa code, nie podľa textu — text je slovenská veta pre človeka a môže sa zmeniť. Pri chybe validácie pribudne pole issues s konkrétnymi poľami.

Je to na našej strane? Aktuálny stav doručovania, hlásenia a fronty je na kvitos.sk/stav — bez prihlásenia, a strojovo na GET /v1/status.

Každá odpoveď nesie RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset. Pri prekročení príde 429 s Retry-After v sekundách. Rýchlosť určuje plán zákazníka.

Mesačný počet dokladov je iná vec než rýchlosť: pri jeho vyčerpaní príde 402 quota_exceeded. Opakovanie nepomôže — pomôže vyšší plán alebo ďalšie obdobie. Aktuálny stav vráti GET /v1/subscription. Testovacie doklady sa do limitu nepočítajú, takže sandbox funguje aj vtedy, keď je ostrá kvóta vyčerpaná.

Udalosti: document.issued, document.paid, document.credited, payment.matched, payment.unmatched, delivery.delivered, delivery.failed, inbound.received, tax.reported, tax.rejected, ping.

import { parseWebhook } from "@kvitos/sdk";

app.post("/webhooks/kvitos",
  express.raw({ type: "application/json" }),   // surové telo!
  (req, res) => {
    const event = parseWebhook(
      process.env.KVITOS_WEBHOOK_SECRET,
      req.body.toString("utf8"),
      req.get("kvitos-signature"),
    );

    if (event.event === "document.paid") {
      // Uvoľnite objednávku.
    }

    res.sendStatus(200);   // Odpovedzte rýchlo, prácu si zaraďte do fronty.
  });

Doručenie sa opakuje s odstupmi 30 s → 2 min → 10 min → 1 h → 6 h → 24 h. Hlavička kvitos-delivery je stále tá istá, takže podľa nej rozpoznáte opakovanie tej istej udalosti. Endpoint, ktorý dlhodobo neodpovedá, vypneme a napíšeme dôvod. Čo sme poslali a s akou odpoveďou vidíte v administrácii v logu doručení.

Ten istý číselník vracia GET /v1/webhooks/events aj s ukážkovým telom každej udalosti — vrátane obálky id, event a occurredAt. Nástroj ako Zapier či Make si z neho vyskladá zoznam spúšťačov a polia na mapovanie. Prihlásenie na to netreba.

Skúšobné doručenie si vypýtate cez POST /v1/webhooks/:id/test s telom {"event": "document.paid"}. Na rozdiel od ping ním overíte aj vetvenie podľa event a čítanie polí z data. Telo je ukážkové — identifikátory v ňom neukazujú na žiadny skutočný doklad.

Na priebežné dosynchronizovanie použite updatedSince — vráti, čo sa od daného okamihu zmenilo, od najstaršieho. Za zmenu sa počíta aj úhrada a doručenie: vystavený doklad sa už nemení, ale práve to, či je uhradený, sa spravidla pýtate.

GET http://127.0.0.1:3100/v1/documents?updatedSince=2027-03-01T00:00:00Z&limit=100

# Ďalšiu stránku berte cez nextCursor z odpovede, nie cez offset —
# cursor zostane správny, aj keď medzitým pribudnú nové doklady.
GET http://127.0.0.1:3100/v1/documents?updatedSince=...&cursor=eyJ...

Filtre: status, kind, customerId, number, issuedFrom, issuedTo, mode.

GET /v1/exports/overview.csv vráti riadok na doklad: čísla, dátumy, odberateľa, sumy, uhradenú časť a zostatok. Nie je to dávka na import do účtovného programu — na to sú exporty — ale plochá tabuľka pre človeka, ktorý si nad ňou robí vlastné súčty.

# Bodkočiarka je predvolená kvôli Excelu so slovenským nastavením.
curl -H "Authorization: Bearer $KVITOS_API_KEY" \
  "http://127.0.0.1:3100/v1/exports/overview.csv?from=2027-01-01&to=2027-12-31"

# Čiarka pre nástroj, ktorý bodkočiarku nečaká:
#   ...&delimiter=comma
# Sandbox namiesto ostrých dokladov:
#   ...&mode=test

Zostatok je stĺpec, nie vzorec. Sumy chodia ako text presne v tvare, v akom sú u nás — tabuľka si ich naformátuje sama a nič sa po ceste nezaokrúhli. Koncepty v prehľade nie sú.

POST /v1/documents/:id/checkout vytvorí platbu na faktúru a vráti adresu, kam pošlete platiteľa. Keď peniaze dorazia, brána nám pošle podpísané oznámenie, my zapíšeme úhradu a vydáme payment.matched, prípadne aj document.paid.

Brána sa nastavuje v administrácii v Nastaveniach: poskytovateľ a identifikátor vášho obchodníckeho účtu. Oznámenia o platbách chodia na POST /v1/webhooks/payments/:tenantId a každé sa overuje skôr, než sa z neho stane úhrada — neoverené doručenie zahadzujeme.

POST /v1/exports vráti dávku vo formáte, ktorý účtovník naimportuje: CSV s riadkom na každú sadzbu, KROS OMEGA a ALFA plus, POHODA, Money S3, ISDOC alebo UBL. Zoznam dostupných formátov vráti GET /v1/exports v poli adapters.

Formát označený verified: false je zostavený podľa zverejnenej štruktúry výrobcu, ale zatiaľ nebol overený importom do reálnej inštalácie. Pred prvým ostrým použitím ho nechajte skúsiť účtovníkovi na jednej dávke.

KROS Fakturácia má vlastné REST API — doklady doň vieme zapísať priamo, bez sťahovania súboru. Nastavuje sa v administrácii v Exportoch.

Zmena, ktorá by rozbila existujúcu integráciu, znamená /v2 — a /v1 pri nej beží ďalej ešte 12 mesiacov. Integráciu e-shopu spravuje ten, kto ju písal, a to často nie je niekto, kto je na projekte stále.

Zastaraný nie je zatiaľ žiadny endpoint. Keď nejaký bude, objaví sa tu aj s označením zastarané v referencii — a bude odpovedať ďalej, kým neuplynie lehota.

Ten istý zoznam strojovo: GET http://127.0.0.1:3100/v1/changelog — bez kľúča. Váš systém tak vie svojmu prevádzkovateľovi povedať, že sa niečo pohlo, bez toho, aby to niekto musel čítať u nás.