POS → KROS

Recept na napojenie pokladničného systému (POS) na KROS API: ktoré endpointy volať, v akom poradí a na aké prekážky si dať pozor pri predaji, úhradách a synchronizácii skladu.

Čo tento scenár rieši

Skladové karty a sklady smerujú z KROSu do pokladne, aby predavač vždy videl aktuálny sortiment a ceny. Opačným smerom sa predaje z pokladne vracajú do KROSu ako skladové výdajky, a denné tržby aj úhrady faktúr priamo na pokladni sa zapisujú späť do KROSu ako platby.

Tok dát

Tok dát medzi pokladnicou a KROSom: KROS posiela zoznam skladov cez GET /api/warehouses a skladové karty cez GET /api/catalog-items (filtrované podľa catalogItemChangedTimestamp) do pokladnice; pokladnica posiela predaje cez POST /api/movements/issues/single (prípadne cez POST /api/delivery-notes/batch) a úhrady cez POST /api/payments/batch späť do KROSu.

Krok za krokom

Autorizácia

Ak doplnok beží vnútri KROS aplikácie, získajte token cez Token Broker. Ak beží mimo nej — samostatná pokladnica alebo externý POS systém — použite Integration Consent.
Sklady a karty do pokladne

Zoznam skladov stiahnete cez GET /api/warehouses. Skladové karty potom cez GET /api/catalog-items s parametrom catalogItemChangedTimestamp, aby ste pri ďalšej synchronizácii stiahli len to, čo sa od poslednej zmenilo.
Predaje späť do KROSu

Každý predaj pošlite cez POST /api/movements/issues/single ako skladovú výdajku. Ak predaje evidujete radšej ako dodacie listy, použite namiesto toho POST /api/delivery-notes/batch.
Úhrada faktúry na pokladni

Faktúru, ktorú zákazník prišiel uhradiť, načítate cez GET /api/invoices. Úhradu potom zapíšete cez POST /api/payments/batch.
Bankové a hotovostné účty

Zoznam existujúcich účtov získate cez GET /api/payments/accounts. Ak pre pokladňu ešte neexistuje hotovostný účet, založte ho cez POST /api/payments/accounts/cash.
Potvrdenie spracovania

API odpovie 202 Accepted s poľom requestId — to znamená len prijaté, nie spracované. Skutočný výsledok príde na váš webhook.

Odporúčané endpointy

Metóda	Cesta	Prečo
GET	`/api/warehouses`	Vráti zoznam skladov, na ktoré sa dá naviazať skladová karta.
GET	`/api/catalog-items`	Vráti skladové karty; s `catalogItemChangedTimestamp` len tie, čo sa zmenili od posledného sync-u.
POST	`/api/movements/issues/single`	Zapíše jeden predaj ako skladovú výdajku.
POST	`/api/delivery-notes/batch`	Alternatíva k skladovej výdajke — zapíše predaje ako dodacie listy, dávkovo po 100 kusoch.
GET	`/api/invoices`	Načíta faktúru, ktorú zákazník prišiel uhradiť na pokladni.
POST	`/api/payments/batch`	Zapíše úhrady a tržby, dávkovo po 100 dokladoch.
GET	`/api/payments/accounts`	Vráti bankové a hotovostné účty, na ktoré sa dá naviazať platba.
POST	`/api/payments/accounts/cash`	Založí hotovostný účet pre pokladňu, ak ešte neexistuje.

Na čo si dať pozor

Platbu posielajte s accountId

Ak k platbe v POST /api/payments/batch priložíte accountId, KROS založí finančnú transakciu a odošle sa webhook finančnej transakcie. Bez accountId sa odošle len webhook úhrady dokladu. Platby bez accountId sú podporované kvôli spätnej kompatibilite, ale prichádzate tak o prepojenie na modul Financie. Nová integrácia by mala vždy posielať accountId — inak sa tržby a úhrady z pokladne v module Financie jednoducho neobjavia.

Párovanie platby podľa variabilného symbolu

Keď POST /api/payments/batch páruje platbu podľa variabilného symbolu a nájde viac vyhovujúcich dokladov, rozhoduje suma a najstarší dátum dokladu. Zálohové faktúry majú pritom pred bežnými faktúrami prednosť — ak variabilný symbol sedí na zálohovú aj bežnú faktúru rovnako, platba sa priradí k zálohovej.

itemCode a warehouseCode

itemCode prepája položku dokladu so skladovou kartou. Bez neho sa párovanie spolieha na zhodu názvu položky, čo je krehšie. itemCode platí len pre skladové karty — warehouseCode je iné pole a slúži na priradenie položky ku konkrétnemu skladu.

Limit dávky 100 dokladov

Dávkové endpointy — POST /api/delivery-notes/batch aj POST /api/payments/batch — prijmú maximálne 100 dokladov v jednej požiadavke. Väčšiu dávku rozdeľte na viac volaní.