Č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

Rozsah dát medzi vašou aplikáciou a KROSom: do KROSu smerujú faktúry, zálohové faktúry, objednávky a dodacie listy, úhrady a tržby a skladové pohyby; z KROSu sa vracajú skladové karty so zostatkami a cenovými hladinami a stav dokladov s úhradami, PDF a prílohami — plus notifikácia webhookom pri každej zmene.

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

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ť.
eFaktúru pripravujeme. Rozsah dát pre elektronickú fakturáciu doplníme, keď API o túto funkčnosť rozšírime — 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.