Čo API umožňuje
Rozsah dát, ktoré si vaša aplikácia a KROS cez API vymieňajú: čo sa dá do KROSu zapísať, čo z neho čítať a čo API nepokrýva. Slúži na posúdenie, či je zamýšľaný scenár realizovateľný, ešte pred technickým návrhom — bez volaní a bez kódu.
Ako to funguje v jednej vete
Doklady a skladové pohyby vznikajú vo vašej aplikácii a cez API vstupujú do KROS Fakturácie a KROS Skladu. Opačným smerom si z KROSu čítate aktuálny sortiment, skladové zostatky a stav dokladov, ktoré ste poslali — vrátane úhrad a PDF na tlač. Vaša aplikácia zostáva miestom, kde beží obchod; KROS zostáva miestom, kde má firma doklady, sklad a podklady pre účtovníctvo.
Tok dát
Čo si vymieňate
Toto je celý rozsah dát, ktorý dnešné API pokrýva. Rozhodujúci je stĺpec Smer: oba smery znamená, že dáta viete do KROSu zapísať aj z neho čítať, len čítanie znamená, že si ich viete z KROSu prevziať, ale nie tam zakladať.
| Oblasť | Smer | Čo to znamená v praxi |
|---|---|---|
| Vydané faktúry | oba smery | Faktúru vystavenú vo vašom systéme pošlete do KROSu a späť si prečítate jej číslo, sumy, rozpis DPH a stav úhrady. Vrátane dobropisov, vrubopisov a faktúr na úhradu. |
| Zálohové (proforma) faktúry | oba smery | Rovnaký rozsah ako pri vydaných faktúrach. Odpočet zálohy sa dá na neskoršej faktúre uviesť sumou. |
| Prijaté objednávky | oba smery | Objednávka z e-shopu alebo z vášho systému vstúpi do KROSu s vlastným aj externým číslom, takže sa dá spätne dohľadať v oboch systémoch. |
| Dodacie listy | oba smery | Dodací list s väzbou na číslo objednávky a faktúry — pre firmy, ktoré expedujú skôr, než fakturujú. |
| Prijaté doklady a výdavky | len čítanie | Nákladové doklady si viete prečítať vrátane stavu úhrady a účtovných údajov. Zapisovať ich cez API nateraz nie je možné. |
| Úhrady, tržby a účty | oba smery | Platby posielate do KROSu s variabilným symbolom, referenciou platby a menou; KROS ich spáruje s dokladom. Založiť sa dá bankový účet, pokladnica aj platobná brána. |
| Skladové karty a zostatky | len čítanie | Sortiment, kódy, EAN, ceny a zostatky po skladoch si vaša aplikácia stiahne. Karty sa zakladajú v KROSe, nie cez API. |
| Skladové pohyby | oba smery | Príjem a výdaj zo skladu zapisujete cez API — a KROS z nich sám prepočíta zostatok. Zostatok sa teda nikdy nenastavuje priamo. |
| PDF dokladov a prílohy | len čítanie | Ku každému dokladu si viete stiahnuť PDF na tlač alebo odkaz na náhľad a prevziať prílohy, ktoré k nemu niekto pripojil v KROSe. |
| Nastavenia firmy | len čítanie | Číselné rady a tagy (vrátane ich kategórií), aby doklady z vašej aplikácie dostali číslovanie a členenie, ktoré firma v KROSe reálne používa. |
Čo všetko je na doklade
Doklad, ktorý si systémy vymenia, nie je „len suma a dátum“. Prenesie sa ten istý rozsah údajov, aký vidí používateľ v KROSe:
- Odberateľ: názov firmy, IČO, DIČ, IČ DPH, fakturačná aj poštová adresa, kontaktná osoba, e-mail a telefón.
- Položky: názov, popis, množstvo, merná jednotka, cena, sadzba DPH, zľava, kód položky, EAN a kód skladu, z ktorého sa vydáva.
- Sumy a DPH: celkové sumy s DPH a bez DPH, rozpis podľa sadzieb, zľava na doklad, odpočet zálohy, mena a kurz.
- Dátumy: vystavenie, dodanie, splatnosť, prijatie objednávky.
- Platba: spôsob úhrady, variabilný symbol, bankový účet a typ platiteľa DPH (vrátane §7/7a a osobitnej úpravy DPH podľa §68d).
- Texty: úvodný a záverečný text, poznámka pre tlač, interná poznámka, povinné texty (napríklad prenos daňovej povinnosti) a zápis v obchodnom registri.
- Členenie: číselný rad, tagy (napríklad stredisko), vlastné polia a účtovné údaje — syntetický a analytický účet.
- Jazyk dokladu: slovenčina, angličtina alebo nemčina, takže doklad pre zahraničného odberateľa vyjde v jeho jazyku.
Čo API vie o sklade
Skladová časť je pre e-shopy a pokladnice zvyčajne dôležitejšia než fakturácia. Ku každej karte sa dá prečítať:
- názov, popis, kód, EAN, merná jednotka a hmotnosť (použiteľná na výpočet poštovného),
- nákupná cena a sadzba DPH,
- všetky cenové hladiny — teda aj ceny pre konkrétne skupiny odberateľov,
- zostatok celkovo aj samostatne za každý sklad a priemerná skladová cena,
- príznak pre e-shop, ktorým si firma v KROSe označí, čo sa má na webe vôbec objaviť,
- čas poslednej zmeny karty — aby sa pri každej synchronizácii prenášalo len to, čo sa naozaj zmenilo.
Čo sa dozviete o poslanom doklade
Prenos dát nie je jednosmerný. Ku každému dokladu, ktorý ste do KROSu poslali, si viete prečítať, čo sa s ním ďalej stalo: či je nezaplatený, čiastočne, úplne alebo preplatený, aká suma zostáva na úhradu, koľko platieb naň prišlo a kedy, či bol odoslaný odberateľovi a či mu bola poslaná upomienka. Sú to údaje, ktoré firma dnes zvyčajne prepisuje medzi dvomi systémami ručne.
Keď ten istý doklad pošlete znova
Doklad je v KROSe jednoznačne určený dvojicou číslo dokladu a číselný rad. Ak doklad s takou kombináciou v KROSe ešte nie je, vznikne nový. Ak už existuje a nie je zamknutý, opakované odoslanie ho prepíše — nevznikne duplicita ani chyba. Opravu, ktorú ste urobili vo svojom systéme, tak do KROSu dostanete jednoducho tým, že doklad pošlete znova s tým istým číslom.
Ktorá z tých dvoch vecí sa stala, sa dozviete z webhooku: každá entita v notifikácii nesie vlastný status — 201 pri novo založenom doklade, 204 pri prepísanom.
Prepis je úplný, nie čiastočný
Doklad sa neaktualizuje po poliach — jeho obsah sa nahradí tým, čo pošlete. Pole, ktoré v opakovanom requeste vynecháte, sa v KROSe vyprázdni, aj keď v ňom predtým hodnota bola. Posielajte preto vždy celý doklad so všetkými položkami, nie iba to, čo ste zmenili.
Prepis sa nevykoná a v notifikácii namiesto neho dostanete problém, keď je pôvodný doklad zamknutý — napríklad exportom do účtovníctva, uzávierkou DPH, odoslaním ako eFaktúra alebo zámkom od používateľa. Rovnako dopadne doklad, ktorý sa nedá jednoznačne určiť, lebo v KROSe existuje viac dokladov s rovnakým číslom a radom, a doklad, ktorý ste poslali dvakrát v jednej dávke. Významy jednotlivých typov problémov nájdete na stránke Webhooky.
Nový doklad naopak vznikne vždy, keď číslo dokladu vôbec nevyplníte — vtedy ho KROS pridelí z číselného radu. A doklad, ktorý bol v KROSe vymazaný, sa opakovaným odoslaním neobnoví; pod tým istým číslom vznikne nový.
Kde prepis platí a kde nie
Neplatí to pre všetky doklady rovnako. Rozhodujúce je, ako endpoint odpovedá: nahrávanie s odpoveďou 202 Accepted, ktorého výsledok príde webhookom, existujúci doklad prepíše. Endpointy, ktoré odpovedajú priamo 201 Created, zakladajú vždy nový doklad.
| Doklad | Endpoint | Opakované odoslanie |
|---|---|---|
| Vydané faktúry | POST /api/invoices, POST /api/invoices/batch |
prepíše existujúci |
| Zálohové faktúry | POST /api/proforma-invoices, POST /api/proforma-invoices/batch |
prepíše existujúci |
| Prijaté objednávky | POST /api/received-orders, POST /api/received-orders/batch |
prepíše existujúci |
| Dodacie listy — dávka | POST /api/delivery-notes/batch |
prepíše existujúci |
| Dodacie listy — jeden doklad | POST /api/delivery-notes/single |
vždy založí nový |
| Skladové pohyby | POST /api/movements/receipts/single, POST /api/movements/issues/single |
vždy založí nový |
| Úhrady | POST /api/payments/batch |
vždy založí novú |
Pri skladových pohyboch opakovanie bezpečné nie je
Ak request na skladový pohyb spadne na timeout a vy ho pošlete znova, vznikne druhý pohyb a tovar sa naskladní alebo vyskladní dvakrát. Dajte preto každému pohybu vlastný externalId a pred opakovaním si cez GET /api/movements/receipts?externalId=… (prípadne /api/movements/issues) overte, či prvý pokus predsa len neprešiel. To isté platí pre POST /api/delivery-notes/single — ak potrebujete opakovanie bez rizika duplicity, použite POST /api/delivery-notes/batch.
Zmeny v reálnom čase
Aby vaša aplikácia nemusela KROS opakovane dopytovať, KROS sám pošle notifikáciu (webhook) na váš server, keď sa niečo zmení: doklad vznikol, zmenil sa alebo bol vymazaný, prišla úhrada dokladu, alebo pohyb v module Financie. Rovnakou cestou prichádza aj potvrdenie, že dávka dokladov, ktorú ste poslali, bola skutočne spracovaná. Podrobnosti sú na stránke Webhooky.
Objem a tempo
Ide o API pre priebežnú synchronizáciu, nie pre jednorazový presun celej databázy:
- 100 dokladov na jednu dávku — v oboch smeroch, pri odosielaní aj pri čítaní.
- 300 požiadaviek za minútu a krátkodobo najviac 10 za sekundu, spoločne na celé napojenie. Ak jedným napojením obsluhujete viac firiem, delia sa o ten istý rozpočet.
- Spracovanie je asynchrónne — KROS dávku najprv prevezme a výsledok pošle až následne na webhook. Aplikácia teda nesmie predpokladať, že doklad je hotový v momente odoslania.
Čo z toho vyplýva pre plánovanie: nočná synchronizácia dvadsaťtisíc skladových kariet naraz nie je scenár, na ktorý je API postavené. Priebežný prenos zmien počas dňa áno. Presné čísla a odporúčaný postup pri prekročení limitu sú v Chybách a limitoch.
Čo cez API nejde
Štyri hranice, ktoré rozhodujú o realizovateľnosti
Sú to najčastejšie nepochopenia. Všetky štyri sa dajú vyriešiť inak, ak sa o nich vie vopred — a všetky štyri sa inak zistia až v priebehu vývoja.
- Doklad sa cez API neupravuje ani nemaže. API doklady zakladá a čítať vie; opravu už existujúceho dokladu urobí používateľ v KROSe.
- Skladová karta cez API nevzniká. Sortiment sa zakladá v KROSe a vaša aplikácia si ho číta. Zostatok mení skladový pohyb, nie zápis čísla.
- Iné produkty KROS nie sú v tomto API. Nepokrýva OMEGU, ALFA plus, OLYMP, ONIX, CENKROS 4 ani oceňovanie nehnuteľností. Integrácia, ktorá potrebuje niektorú z týchto agend, sa cez toto API nedá postaviť.
- Odoslanie eFaktúry cez API pripravujeme. eFaktúru cez API vytvoríte a jej stav v sieti Peppol prečítate, ale odoslať ju odberateľovi treba zatiaľ v aplikácii KROS — pozri eFaktúra.
Čo partner potrebuje na svojej strane
Rozdelenie zodpovednosti:
- zákazník musí mať KROS Fakturáciu alebo KROS Sklad a licenciu na prístup k API,
- partner si vyberie autorizačný model — od jednorazového tokenu až po plne automatické prihlásenie,
- partner potrebuje verejne dostupný endpoint, na ktorý mu KROS bude posielať notifikácie,
- partner musí ošetriť opakované posielanie pri chybách a prekročení limitu.
Vývojová práca je teda na strane partnera. KROS dodáva API, dokumentáciu a — ak integráciu píše AI agent — aj hotový prompt so celou špecifikáciou, ktorý čas prvej integrácie výrazne skracuje.
Ďalší krok
Ak je po tejto stránke jasné, že scenár je realizovateľný, technická časť pokračuje takto: Začíname (predpoklady a formáty) → Autorizácia (ako sa aplikácia dostane k tokenu) → Najčastejšie integrácie (hotové recepty pre e-shop a pokladnicu).
Otázka, na ktorú tu odpoveď nie je? Napíšte na integracie@kros.sk.