# KROS API — kompletná dokumentácia pre integrátorov Zdroj: https://api.krosdoplnky.sk Tento súbor je generovaný z HTML stránok webu. Neupravuj ho ručne. Endpointy nie sú v tomto súbore. Stiahni si k nemu aj OpenAPI špecifikácie: - https://api.krosdoplnky.sk/ai/kros-openapi.json - https://api.krosdoplnky.sk/ai/kros-webhooks-openapi.json ============================================================================== # KROS API pre integrátorov Zdroj: https://api.krosdoplnky.sk/index.html ============================================================================== # KROS API pre integrátorov KROS OpenAPI umožňuje externej aplikácii čítať a zapisovať faktúry, zálohové faktúry, prijaté objednávky, dodacie listy, výdavky, úhrady a skladové dáta v KROS Fakturácii a KROS Sklade. Integráciu píše AI agent? Pošlite mu jeden prompt. Pripravili sme jeden prompt, ktorý agentovi povie presne, čo si má stiahnuť a naštudovať, aby vedel napísať funkčnú integráciu. [Otvoriť stránku pre AI agenta](ai.html). ## Čo API umožňuje Ak ešte len zvažujete, či má napojenie zmysel, začnite prehľadom rozsahu dát: čo sa dá do KROSu zapísať, čo z neho čítať a čo API nepokrýva — bez volaní a bez kódu. [Čo API umožňuje — rozsah vymieňaných dát](co-umoznuje.html) ## Ako sa dostanete k tokenu Každé volanie KROS API potrebuje token. Sú tri modely, ako sa k nemu vaša aplikácia dostane — manuálny token, Integration Consent a Token Broker. Porovnanie, rozhodovací diagram aj to, čo si pri každom modeli musíte postaviť, nájdete na jednom mieste. [Autorizácia — ktorý model si vybrať](autorizacia/index.html) · [Začíname](zaciname.html) · [Najčastejšie integrácie](integracie/index.html) ## Kde nájdete endpointy Kompletný zoznam endpointov a ich schémy nájdete v Swagger UI alebo v prehľade skupín endpointov s odkazmi na lokálne kópie OpenAPI špecifikácií. [Swagger UI (api-economy.kros.sk)](https://api-economy.kros.sk/swagger/index.html) · [API reference](api-reference.html) ============================================================================== # Čo API umožňuje Zdroj: https://api.krosdoplnky.sk/co-umoznuje.html ============================================================================== # Č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 > Diagram: 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](webhooky.html). ## 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](chyby-a-limity.html). ## Č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](integracie/efaktura.html). ## Č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](autorizacia/index.html) — 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](ai.html), 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](zaciname.html) (predpoklady a formáty) → [Autorizácia](autorizacia/index.html) (ako sa aplikácia dostane k tokenu) → [Najčastejšie integrácie](integracie/index.html) (hotové recepty pre e-shop a pokladnicu). Otázka, na ktorú tu odpoveď nie je? Napíšte na [integracie@kros.sk](mailto:integracie@kros.sk). ============================================================================== # Naučiť AI agenta Zdroj: https://api.krosdoplnky.sk/ai.html ============================================================================== # Naučiť AI agenta Skopírujte jeden prompt nižšie a vložte ho do Claude Code alebo iného AI agenta — agent si sám stiahne dokumentáciu aj OpenAPI špecifikácie, aby rozumel KROS API. Až potom mu zadáte, čo má postaviť alebo rozšíriť. ## Prompt **Všeobecný** variant agenta iba naučí KROS API a potom sa zastaví — nič nedopĺňate a hodí sa aj vtedy, keď integráciu už máte a chcete ju len rozšíriť. **E-shop** a **POS** idú ďalej: majú predvyplnený smer dát, ukazujú na overený scenár napojenia a agent po nich navrhne postup. V tých dvoch dopíšte polia označené ``. ### Prompt pre vášho AI agenta Agent v každom variante najprv stiahne a prečíta zdroje. Kód nezačne písať, kým mu to nepovolíte. Všeobecný E-shop POS ``` Naštuduj si KROS OpenAPI (fakturácia a sklad, Slovensko). Zatiaľ nič neimplementuj — potrebujem, aby si najprv rozumel tomu, ako to API funguje. Stiahni a prečítaj CELÉ tieto zdroje: 1. https://api.krosdoplnky.sk/ai/llms-full.txt Celá dokumentácia KROS API v jednom súbore — autorizačné modely, scenáre integrácií, webhooky, chybové kódy, limity. 2. https://api.krosdoplnky.sk/ai/kros-openapi.json OpenAPI 3.0 špecifikácia endpointov. 3. https://api.krosdoplnky.sk/ai/kros-webhooks-openapi.json OpenAPI 3.0 špecifikácia webhookov, ktoré KROS posiela na tvoj endpoint. Po prečítaní mi krátko zhrň: 1. Aké autorizačné modely KROS API ponúka a čím sa od seba líšia. 2. Aké skupiny endpointov existujú a na čo slúžia. 3. Ako fungujú webhooky a aké sú chybové kódy a limity. Potom sa zastav a čakaj na moje pokyny. Nenavrhuj architektúru, nepíš kód a nemeň nič v projekte, kým ti nepovím, čo presne potrebujem. Nevymýšľaj si názvy polí, endpointov ani hodnôt. Ak niečo nie je v stiahnutých zdrojoch, povedz že to nevieš a spýtaj sa. ``` Skopírovať prompt ``` Budeš implementovať integráciu s KROS OpenAPI (fakturácia a sklad, Slovensko). Najprv stiahni a prečítaj CELÉ tieto zdroje, až potom navrhuj kód: 1. https://api.krosdoplnky.sk/ai/llms-full.txt Celá dokumentácia KROS API v jednom súbore — autorizačné modely, scenáre integrácií, webhooky, chybové kódy, limity. 2. https://api.krosdoplnky.sk/ai/kros-openapi.json OpenAPI 3.0 špecifikácia endpointov. 3. https://api.krosdoplnky.sk/ai/kros-webhooks-openapi.json OpenAPI 3.0 špecifikácia webhookov, ktoré KROS posiela na tvoj endpoint. 4. https://api.krosdoplnky.sk/md/integracie-eshop.md Overený scenár: objednávky a faktúry z e-shopu do KROSu, skladové karty a zostatky späť — odporúčané endpointy a postup. Kontext môjho zadania: - Produkt, ktorý integrujem: - Smer dát: objednávky a faktúry z e-shopu do KROSu, skladové karty a zostatky späť - Autorizačný model: - Jazyk a framework: Po prečítaní zdrojov: 1. Zhrň mi jedným odstavcom, ktorý autorizačný model si vybral a prečo. 2. Vypíš presný zoznam endpointov, ktoré budeme volať, v poradí. 3. Až po mojom potvrdení začni písať kód. Nevymýšľaj si názvy polí, endpointov ani hodnôt. Ak niečo nie je v stiahnutých zdrojoch, povedz že to nevieš a spýtaj sa. ``` Skopírovať prompt ``` Budeš implementovať integráciu s KROS OpenAPI (fakturácia a sklad, Slovensko). Najprv stiahni a prečítaj CELÉ tieto zdroje, až potom navrhuj kód: 1. https://api.krosdoplnky.sk/ai/llms-full.txt Celá dokumentácia KROS API v jednom súbore — autorizačné modely, scenáre integrácií, webhooky, chybové kódy, limity. 2. https://api.krosdoplnky.sk/ai/kros-openapi.json OpenAPI 3.0 špecifikácia endpointov. 3. https://api.krosdoplnky.sk/ai/kros-webhooks-openapi.json OpenAPI 3.0 špecifikácia webhookov, ktoré KROS posiela na tvoj endpoint. 4. https://api.krosdoplnky.sk/md/integracie-pos.md Overený scenár: skladové karty do pokladne, predaje a tržby späť do KROSu — odporúčané endpointy a postup. Kontext môjho zadania: - Produkt, ktorý integrujem: - Smer dát: skladové karty do pokladne, predaje a tržby späť do KROSu - Autorizačný model: - Jazyk a framework: Po prečítaní zdrojov: 1. Zhrň mi jedným odstavcom, ktorý autorizačný model si vybral a prečo. 2. Vypíš presný zoznam endpointov, ktoré budeme volať, v poradí. 3. Až po mojom potvrdení začni písať kód. Nevymýšľaj si názvy polí, endpointov ani hodnôt. Ak niečo nie je v stiahnutých zdrojoch, povedz že to nevieš a spýtaj sa. ``` Skopírovať prompt ## Čo si agent stiahne Prompt odkazuje na štyri súbory uložené priamo na tomto webe. Nič z toho nie je tajné — môžete si každý z nich otvoriť a skontrolovať, čo presne agent dostane. | Súbor | Čo obsahuje | | --- | --- | | [`ai/llms.txt`](ai/llms.txt) | Krátky index dokumentácie s odkazmi na ostatné stránky a špecifikácie — orientačný bod pre agenta. | | [`ai/llms-full.txt`](ai/llms-full.txt) | Celá dokumentácia webu v jednom súbore — autorizačné modely, scenáre integrácií, webhooky, chyby a limity. | | [`ai/kros-openapi.json`](ai/kros-openapi.json) | OpenAPI 3.0 špecifikácia 43 endpointov KROS API. | | [`ai/kros-webhooks-openapi.json`](ai/kros-webhooks-openapi.json) | OpenAPI 3.0 špecifikácia 3 webhookov, ktoré KROS posiela na váš endpoint. | ## Radšej skill než prompt? Stiahnite si [`ai/kros-api-integration-skill.zip`](ai/kros-api-integration-skill.zip) a rozbaľte ho do `.claude/skills/`. Agent tak má celú dokumentáciu k dispozícii offline a natrvalo, bez toho, aby si čokoľvek musel sťahovať. ## Markdown verzia každej stránky Každá stránka tohto webu má svoje dvojča vo formáte Markdown v priečinku `md/`, generované priamo z HTML. Agent tak nikdy nemusí parsovať HTML — začnite napríklad pri [`md/index.md`](md/index.md). Odkiaľ pochádzajú dáta Táto dokumentácia sa generuje priamo z tohto webu, takže nemôže odísť mimo synchronizáciu s tým, čo si prečíta človek. Definície endpointov ale vždy pochádzajú z OpenAPI špecifikácií vyššie — a živý [Swagger](https://api-economy.kros.sk/swagger/index.html) je nad nimi autoritatívny zdroj. ============================================================================== # Začíname Zdroj: https://api.krosdoplnky.sk/zaciname.html ============================================================================== # Začíname Skôr než začnete písať integráciu, prečítajte si túto stránku celú: nájdete tu základnú adresu API, čo potrebujete na strane KROSu, v akom formáte si dáta vymieňate a ako vyzerá prvé overovacie volanie. ## Base URL Všetky požiadavky smerujte na `https://api-economy.kros.sk`. Jednotlivé endpointy nájdete pod cestou `/api/{resource}`. ## Čo potrebujete Na používanie API potrebujete účet v KROS Fakturácii alebo KROS Sklade a licenciu na prístup k API. Podmienky tejto licencie sa líšia podľa produktu KROS — overte si ich preto priamo vo svojom produkte KROS, alebo sa opýtajte na [integracie@kros.sk](mailto:integracie@kros.sk). ## Formáty dát API prijíma aj vracia dáta vo formáte JSON, v kódovaní UTF-8. Dátumy a časy sú v tvare ISO 8601, napríklad `2022-12-07T08:56:08.693Z`. Pri hromadnom spracovaní platí limit **100 dokladov na jednu požiadavku**, a to v oboch smeroch — pri odosielaní aj pri čítaní dát. Stránkovanie výsledkov riadia parametre `top` a `skip`. ## Prvé volanie Spojenie aj platnosť tokenu overíte volaním `GET /api/auth/check`. ``` curl https://api-economy.kros.sk/api/auth/check \ -H "Authorization: Bearer " ``` ## Čo toto API nepokrýva Nepokryté produkty a agendy Cez toto API nie sú dostupné dáta ani funkcie produktov OMEGA, ALFA plus, OLYMP, ONIX a CENKROS 4, ani oceňovanie nehnuteľností. Ak vaša integrácia potrebuje niektorú z týchto oblastí, nie je s týmto API realizovateľná — napíšte nám radšej vopred na [integracie@kros.sk](mailto:integracie@kros.sk), než začnete plánovať prácu, ktorá sa cez toto API urobiť nedá. ## Ďalší krok Ďalej pokračujte výberom autorizačného modelu: [Autorizácia — ktorý model si vybrať](autorizacia/index.html). ============================================================================== # Autorizácia — ktorý model si vybrať Zdroj: https://api.krosdoplnky.sk/autorizacia/index.html ============================================================================== # Autorizácia — ktorý model si vybrať KROS API ponúka tri spôsoby, ako sa vaša aplikácia dostane k tokenu pre volania voči KROS Fakturácii a KROS Skladu. Líšia sa v tom, kto prepojenie nastavuje, čo si musíte sami postaviť a či na to potrebujete dohodu s KROSom. Táto stránka vám pomôže vybrať si jeden z nich. ## Porovnanie | Model | Kto nastavuje prepojenie | Čo musíte postaviť | Self-service | Vhodné pre | | --- | --- | --- | --- | --- | | Manuálny token | používateľ v KROSe, token skopíruje k vám | pole na vloženie tokenu | áno | prvá integrácia, interný nástroj | | Integration Consent | používateľ potvrdí súhlas v KROSe | consent URL + príjem tokenu (post alebo poll) | áno, **bez registrácie u KROSu** | partnerský produkt s vlastným onboardingom | | Token Broker partner | jedno kliknutie v KROS aplikácii | tri HTTP endpointy + overenie JWT | nie, treba dohodu s KROSom | doplnok bežiaci vnútri KROS aplikácie | ## Rozhodovací diagram > Diagram: Tri otázky, ktoré vedú k jednému z modelov: ak doplnok beží vnútri KROS aplikácie, ide o Token Broker; inak, ak má používateľ prepojenie povoliť sám bez kopírovania tokenu, ide o Integration Consent (post pre server, poll pre mobil, SPA či CLI); ak ani jedno, zostáva manuálny token. ## Čo majú modely spoločné - Každý model končí tokenom, ktorý používate ako `Authorization: Bearer `. - Jeden token pokrýva KROS Fakturáciu aj KROS Sklad súčasne. - Všetky tri modely dokážu prijímať webhooky. Podrobnosti k jednotlivým modelom: [Manuálny token](manualny-token.html) · [Integration Consent](integration-consent.html) · [Token Broker](token-broker.html). ============================================================================== # Manuálny token Zdroj: https://api.krosdoplnky.sk/autorizacia/manualny-token.html ============================================================================== # Manuálny token Najjednoduchší z troch autorizačných modelov: používateľ si token vygeneruje priamo v KROS Fakturácii alebo KROS Sklade a ručne ho vloží do vašej aplikácie. Nepotrebujete naň žiadnu dohodu s KROSom ani žiadny ďalší endpoint — stačí pole na vloženie tokenu. ## Ako to funguje Celý model má tri kroky: používateľ token vygeneruje, skopíruje ho k vám a vaša aplikácia ho odvtedy posiela s každým volaním API. > Diagram: Tri kroky manuálneho tokenu: používateľ si ho vygeneruje v KROSe, skopíruje a vloží do vašej aplikácie, ktorá ho odvtedy posiela s každým volaním KROS API. ## Kde si používateľ vygeneruje token 1. Otvorí nastavenia firmy V KROS Fakturácii alebo KROS Sklade otvorí nastavenia firmy a prejde do sekcie **API prepojenia**. 2. Vyplní Názov prepojenia Pole **Názov prepojenia** je povinné — slúži na to, aby používateľ v zozname prepojení rozpoznal, ku ktorej aplikácii token patrí, napríklad `E-shop mojeshop.sk`. 3. Voliteľne vyplní URL pre príjem notifikácií Pole **URL pre príjem notifikácií** je voliteľné — je to adresa vášho webhook endpointu, na ktorý má KROS posielať eventy. 4. Voliteľne vyplní Autorizačný kľúč Pole **Autorizačný kľúč** je tiež voliteľné — použije sa na overenie podpisu prichádzajúcich webhookov. 5. Uloží a skopíruje vygenerovaný token Po uložení KROS token vygeneruje a zobrazí ho na obrazovke. Používateľ ho skopíruje a vloží do vašej aplikácie. Token sa zobrazí len raz KROS token zobrazí iba v okamihu vygenerovania. Neskôr sa už nedá znova zobraziť ani vyhľadať — dá sa len **resetovať**, čím sa starý token zneplatní a vygeneruje sa nový. Toto je najčastejší dôvod, prečo sa partneri obracajú na podporu — ak si používateľ token nezapíše hneď pri vytvorení, musí prepojenie resetovať a vygenerovať token znova. ## Ako token použiť Token posielate v hlavičke `Authorization: Bearer ` pri každom volaní API. Spojenie aj platnosť tokenu si overíte volaním `GET /api/auth/check`. ``` curl https://api-economy.kros.sk/api/auth/check \ -H "Authorization: Bearer " ``` ## Platnosť pre Fakturáciu aj Sklad Token vygenerovaný v KROS Fakturácii aj token vygenerovaný v KROS Sklade je platný pre volania voči obom aplikáciám naraz. Nie je preto potrebné generovať samostatný token pre Fakturáciu a samostatný pre Sklad — jeden token stačí pre obe. ## Obmedzenia tohto modelu Používateľ musí token nájsť, skopírovať a vložiť ručne, čo pre prvú integráciu alebo interný nástroj stačí. Pre partnerský produkt s vlastným samoobslužným onboardingom to však neškáluje — každý nový zákazník by musel prechádzať rovnakým ručným krokom a vy by ste nemali istotu, že to spraví správne. Ak potrebujete samoobslužné napojenie bez ručného kopírovania tokenu, použite [Integration Consent](integration-consent.html). ============================================================================== # Integration Consent Zdroj: https://api.krosdoplnky.sk/autorizacia/integration-consent.html ============================================================================== # Integration Consent Samoobslužný autorizačný model: postavíte URL s parametrami vašej aplikácie, používateľ ju otvorí, v KROSe schváli prepojenie a vy dostanete tokeny — buď priamym POST-om do vášho servera, alebo si ich vyzdvihnete pollingom. Žiadna dohoda s KROSom vopred nie je potrebná. Registrácia vopred nie je potrebná Integration Consent si nevyžaduje žiadnu predchádzajúcu registráciu ani dohodu s KROSom — ktokoľvek si vie zostaviť consent URL podľa parametrov nižšie a rovno ju použiť. To je iné než dostať doplnok **zaradený do obchodu doplnkov v KROS aplikácii** — to je samostatný krok, ktorý si vyžaduje kontaktovať KROS. Pozri [Obchod doplnkov](../doplnky-store.html). Platí pre Fakturáciu aj Sklad Integration Consent funguje rovnako pre **KROS Fakturáciu** aj **KROS Sklad** — používateľ pri schvaľovaní vyberá firmu, nie produkt. ## Consent URL Základ URL je `https://firma.kros.sk/integration-consent`, ku ktorému pridáte nasledujúce parametre v query stringu. | Parameter | Povinný | Hodnota | | --- | --- | --- | | `plugin_name` | áno | názov aplikácie zobrazený používateľovi | | `integrator_name` | áno | obchodné meno vašej firmy | | `version` | áno | `1` | | `response_mode` | áno | `post` alebo `poll` | | `state` | áno | kryptograficky bezpečný náhodný reťazec, **minimálne 32 znakov** | | `redirect_url` | pri `post` | URL, na ktorú KROS pošle POST s tokenmi | | `company_mode` | nie | `single` (default) alebo `multiple` | | `webhook` | nie | HTTPS URL na príjem notifikácií | | `webhook_secret` | nie | kľúč na verifikáciu webhookov; ak sa neuvedie, KROS ho vygeneruje | ``` https://firma.kros.sk/integration-consent ?plugin_name=MyEcommerceApp &integrator_name=Acme%20Corporation &version=1 &response_mode=post &redirect_url=https%3A%2F%2Fmyapp.com%2Fkros%2Fcallback &company_mode=multiple &state=random-state-id-12345 ``` ## Post mode Po schválení prepojenia KROS pošle z prehliadača používateľa priamy HTTP POST na váš `redirect_url`, s telom vo formáte `application/x-www-form-urlencoded`. > Diagram: Postupnosť post mode: 1) používateľ otvorí consent URL a v KROSe schváli prepojenie, 2) KROS pripraví automaticky odosielaný POST formulár s tokenmi, 3) prehliadač používateľa odošle POST na `redirect_url` s poľami `data[n][…]` a `state`, 4) váš server prijme POST, overí `state` a uloží tokeny. Telo POST požiadavky vyzerá takto: ``` data[0][companyId]=123 data[0][token]=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... data[0][companyName]=Acme Corp data[0][webhookSecret]=aG9zZXJhbmRvbXNlY3JldA== data[1][companyId]=456 data[1][token]=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... data[1][companyName]=Tech Inc data[1][webhookSecret]=YW5vdGhlcnNlY3JldA== state=random-state-id-12345 ``` `state` je v post mode voliteľný, ale odporúčaný — pošlite ho v consent URL a po prijatí POST-u porovnajte, či sa vrátená hodnota zhoduje s tou, ktorú ste poslali. Post mode je vhodný pre **serverové webové aplikácie**, ktoré majú verejne dostupný endpoint na prijatie POST-u. Tvar tela je **rovnaký v oboch režimoch** `company_mode`. Aj pri `single` prídu dáta indexované — dostanete jednu položku `data[0][…]`. Neindexované polia `companyId`, `token` v koreni tela KROS neposiela nikdy, takže na svojej strane vystačíte s jednou vetvou kódu, ktorá prejde pole `data[…]` bez ohľadu na režim. Pole `data[n][webhookSecret]` je v tele len vtedy, keď prepojenie má webhook; `companyId`, `token` a `companyName` prídu vždy. `state` sa pridá do tela iba vtedy, ak ste ho poslali v consent URL. POST odošle prehliadač používateľa sám, s krátkym odpočtom po schválení. Ak sa automatické odoslanie nespustí (napr. používateľ stránku medzitým opustí), má na obrazovke tlačidlo na návrat, ktoré ten istý POST odošle ručne — váš endpoint preto musí zvládnuť aj to, že tá istá požiadavka príde s odstupom niekoľkých sekúnd či minút. ## Poll mode Po schválení prepojenia KROS tokeny neposiela nikam sám — uloží ich na svojej strane, naviazané na váš `state`, a to na **15 minút**. Počas tohto okna si ich vyzdvihnete volaním poll endpointu. > Diagram: Postupnosť poll mode: 1) používateľ otvorí consent URL s `response_mode=poll` a v KROSe schváli prepojenie, 2) váš server volá `POST /api/integration-subscription/poll` so svojím `state`, 3) KROS odpovie stavom `Pending`, `Approved`, `Denied` alebo `Expired`, 4) kým je stav `Pending`, server volanie opakuje — KROS uchováva tokeny 15 minút. ``` POST /api/integration-subscription/poll HTTP/1.1 Host: api-economy.kros.sk Content-Type: application/json { "state": "a7s9f8j2k1l0m3n4b5v6c7x8z9q1w2e3r4t5y6u7i8o9p0" } ``` Odpoveď: ```json { "data": { "status": "Approved", "companies": [ { "companyId": 123, "companyName": "Acme Corp", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "webHookSecret": "aG9zZXJhbmRvbXNlY3JldA==" } ] } } ``` | `status` | Význam a čo spraviť ďalej | | --- | --- | | `Pending` | Používateľ ešte prepojenie neschválil — pokračujte v pollovaní. | | `Approved` | Tokeny sú pripravené v poli `companies` — uložte si ich a pollovanie ukončite. | | `Denied` | Hodnota je súčasťou kontraktu, ale poll endpoint ju dnes **nevracia** — ošetrite ju ako terminálny stav (pollovanie ukončite), nestavajte však na nej detekciu zamietnutia. | | `Expired` | 15-minútové okno na vyzdvihnutie tokenov uplynulo — ak používateľ ešte chce prepojenie schváliť, začnite znova novou consent URL s novým `state`. | **Zamietnutie neviete odlíšiť od čakania.** Ak používateľ prepojenie neschváli, KROS si pod vaším `state` nič neuloží a poll endpoint bude naďalej vracať `Pending` — rovnako ako keby používateľ obrazovku ešte len mal otvorenú. Pollovanie preto ukončite vlastným časovým limitom (rozumné je držať sa 15-minútového okna) a po jeho uplynutí považujte pokus za neúspešný. Na rozdiel od post mode je `state` v poll mode **povinný** — je to kľúč, pod ktorým si tokeny vyzdvihnete, takže bez neho poll endpoint nemá čo hľadať. Poll mode je vhodný pre **mobilné aplikácie, SPA, CLI nástroje a background joby**, teda klientov bez verejne dostupného servera na prijatie POST-u. `webhookSecret` vs. `webHookSecret` Názov poľa sa medzi režimami líši veľkosťou jedného písmena, čo partnerom často spôsobí zbytočné hľadanie chyby: post mode posiela pole `webhookSecret` (malé `h`), zatiaľ čo poll odpoveď vracia `webHookSecret` (veľké `H`). Overte si presný názov poľa v tom režime, ktorý používate. ## Životnosť a revokácia tokenu Token získaný cez Integration Consent **nemá časovú expiráciu**. Neobnovuje sa a nerotuje — platí, kým prepojenie v KROSe existuje. Nepotrebujete teda refresh token ani plánované preberanie nového tokenu; potrebujete ale ošetriť, že token môže kedykoľvek prestať platiť rozhodnutím používateľa. Prepojenia vytvorené cez consent sa používateľovi zobrazia v nastaveniach firmy v sekcii **API prepojenia**, v tom istom zozname ako [manuálne vytvorené prepojenia](manualny-token.html). Tam ich vie aj zrušiť: - **Zmazanie prepojenia** — token prestane platiť a API na ďalšie volania odpovie `401 Unauthorized`. - **Reset (vygenerovanie nového tokenu)** pre to isté prepojenie — nový token nahradí starý a **predchádzajúci prestane platiť**. Pre jedno prepojenie je vždy platný práve jeden token. Zmena sa nemusí prejaviť v tej istej sekunde — autorizácia tokenu je na strane API krátko cachovaná, takže rátajte s rádovo minútovým oneskorením, kým zrušený token začne vracať `401`. Opakovaný súhlas vytvorí ďalšie prepojenie, staré nezruší Keď používateľ prejde procesom súhlasu pre tú istú firmu znova, vznikne **nové samostatné prepojenie s novým tokenom** — pôvodné zostáva v platnosti a v zozname prepojení. Tokeny teda platia súbežne, kým jeden z nich používateľ nezmaže. Ak posielate používateľa cez consent opakovane (napríklad pri preinštalovaní doplnku), starý token si na svojej strane zahoďte a počítajte s tým, že v KROSe uvidí viac prepojení s rovnakým názvom. ## Ďalší krok Nastavte si príjem udalostí na [Webhookoch](../webhooky.html), alebo pokračujte na [Najčastejšie integrácie](../integracie/index.html). ============================================================================== # Token Broker — automatické prihlásenie Zdroj: https://api.krosdoplnky.sk/autorizacia/token-broker.html ============================================================================== > **Vyžaduje partnerský prístup** — celá stránka je dnes verejná, neskôr bude za prihlásením. # Token Broker — automatické prihlásenie Token Broker je model pre doplnky, ktoré bežia priamo vnútri KROS platformy: používateľ klikne raz v obchode doplnkov a je automaticky prihlásený vo vašom doplnku, jeho firmy sa prepoja a doplnok dostane access token na KROS OpenAPI. Ide o server-to-server protokol s podpísaným JWT, jednorazovým launch code a zdieľaným API kľúčom — nie o samoobslužný model, ktorý by ste si mohli nasadiť sami. Vyžaduje dohodu s KROSom Token Broker nie je samoobslužný model — aby ste doplnok mohli zaradiť do obchodu doplnkov a napojiť ho na tento protokol, potrebujete dohodu s KROSom (pridelenie `pluginId`, API kľúča a JWKS URL prebieha mimo tejto dokumentácie). Ozvite sa na [integracie@kros.sk](mailto:integracie@kros.sk). ## Čo to rieši V obchode doplnkov v KROS aplikácii klikne používateľ na jedno tlačidlo a tromi vecami naraz: je automaticky prihlásený vo vašom doplnku bez zadávania hesla, jeho firma (alebo firmy) v KROSe sa prepoja s doplnkom, a doplnok dostane access token na KROS OpenAPI, ktorým môže volať KROS v mene tejto firmy. Prehliadač používateľa **nikdy nevidí** tento access token na KROS OpenAPI — prenáša sa výhradne server-to-server, medzi KROS Gatewayom a vaším doplnkom. Prehliadač nesie iba jednorazový, krátko platný `code`, ktorým sa na konci toku vytvorí prihlásená relácia. ## Roly a hranice KROS vlastní celý front-end tok a podpisovanie tokenov. **Vy implementujete iba stranu doplnku — tri HTTP endpointy.** | Komponent | Vlastník | Zodpovednosť | | --- | --- | --- | | KROS Frontend | KROS | tlačidlo v obchode doplnkov, zavolá launch, spracuje presmerovanie | | KROS Gateway + Token Broker | KROS | podpis RS256 JWT, JWKS endpoint, orchestrácia výmeny tokenov, rate limiting | | Access token provider | KROS | vydá access token na KROS OpenAPI pre dvojicu (firma, doplnok) | | Váš doplnok | Partner | tri HTTP endpointy (`token-exchange`, `token-delivery`, `callback`); overí API kľúč a podpis JWT; založí alebo prihlási používateľa; bezpečne uloží access token | | KROS OpenAPI | KROS | dátové API, ktoré doplnok volá získaným access tokenom | ## Celý tok Kompletná sekvencia od kliknutia až po prihlásenú reláciu vo vašom doplnku: > Diagram: Dvanásť krokov toku: 1) KROS Gateway podpíše RS256 JWT s claimami `sub`, `plugin_id` a `tenant_ids`; 2) zavolá `POST /api/auth/token-exchange` na vašom doplnku s hlavičkou `X-Plugin-Api-Key` a telom `{ token }`; 3) doplnok overí API kľúč konštantným časom; 4) overí podpis JWT cez JWKS (len RS256); 5) vygeneruje jednorazový launch code (64 znakov, TTL 30 s) a vráti `{ launchCode, requestAccessToken }`; 6) ak `requestAccessToken` je `true`, Gateway zavolá `POST /api/auth/token-delivery`; 7) doplnok bezpečne uloží `accessToken` pre každú firmu a vráti `200 OK`; 8) Gateway presmeruje prehliadač (302) na `{BaseUrl}/auth/callback?code=…`; 9) prehliadač zavolá `GET /auth/callback?code=…` priamo na doplnku; 10) doplnok overí a atomicky skonzumuje code (ochrana proti opakovanému použitiu); 11) vytvorí cookie reláciu; 12) odpovie `Set-Cookie` a presmeruje na dashboard doplnku. ## Endpointy, ktoré implementujete Tieto tri cesty sú **fixné konštanty protokolu, nie sú konfigurovateľné**. KROS ich skladá ako `{BaseUrl}/api/auth/token-exchange`, `{BaseUrl}/api/auth/token-delivery` a `{BaseUrl}/auth/callback`, kde `BaseUrl` je HTTPS adresa vášho doplnku dohodnutá s KROSom. | Metóda | Cesta | Auth | Popis | | --- | --- | --- | --- | | POST | `/api/auth/token-exchange` | `X-Plugin-Api-Key` | prijme JWT, vráti launch code | | POST | `/api/auth/token-delivery` | `X-Plugin-Api-Key` | prijme access token(y) | | GET | `/auth/callback?code=…` | anonymné (presmerovanie prehliadača) | overí code, vytvorí reláciu | ### POST /api/auth/token-exchange ``` X-Plugin-Api-Key: VLOZ_SEM_API_KEY Content-Type: application/json ``` ```json { "token": "" } ``` Identita používateľa a firmy **nie sú samostatné polia tela požiadavky** — sú to claimy v samotnom JWT (nižšie). 1. Overte `X-Plugin-Api-Key` porovnaním s konštantným časom — inak `401`. 2. Overte JWT: podpis cez JWKS, `iss`, `aud`, `exp`, algoritmus obmedzený len na RS256, `plugin_id` zodpovedá vášmu — inak `401`. 3. Prečítajte `sub` a `tenant_ids`. 4. Vygenerujte jednorazový launch code (64 znakov, TTL 30 s) a uložte ho spolu s `(userId, tenantIds, pluginId)`. 5. Rozhodnite, či potrebujete access token (`requestAccessToken`) — typicky `true`, ak ho pre danú firmu ešte nemáte. ```json { "launchCode": "<64-znakový kód>", "requestAccessToken": true } ``` `400` = chýba `token`. `401` = zlý API kľúč alebo neplatný podpis JWT. ### JWT claimy | Claim | Hodnota | Poznámka | | --- | --- | --- | | `iss` | `plugin-broker` | presná fixná hodnota | | `aud` | `plugin` | presná fixná hodnota | | `sub` | ID používateľa | jedna varianta gateway posiela e-mail, druhá posiela numerické ID — pozri [Dve varianty gateway](#dve-varianty-gateway) | | `plugin_id` | napr. `fiskalpro` | musí sa zhodovať s vaším prideleným `pluginId` | | `tenant_ids` | JSON pole stringov, napr. `["123456","789012"]` | firmy, pre ktoré launch nesie oprávnenie; `[]` = iba prihlásenie bez tenantov | | `jti` | GUID | unikátne ID tokenu | | `iat`, `nbf`, `exp` | čas | platnosť 15 minút (default); povolený clock skew 30 s | Algoritmus obmedzte výhradne na RS256 JWT knižnice bežne dovolia overiť podpis podľa algoritmu, ktorý si token sám deklaruje v hlavičke — to je klasická zraniteľnosť JWT (útočník si nastaví `alg` na niečo slabšie alebo na `none`). Pri validácii tokenu z Token Brokera preto explicitne obmedzte prijímaný algoritmus na **RS256** a nikdy nedôverujte hodnote `alg` z hlavičky prichádzajúceho tokenu. `tenant_ids` — pole, plurál Claim sa volá `tenant_ids` a je to **JSON pole stringov**. Singulárny `tenant_id` v protokole neexistuje. Zámena za singulár je zdokumentovaný zdroj chýb u partnerov — kód, ktorý číta `tenant_id`, dostane `undefined` a launch pre viacero firiem potichu prestane fungovať. ### POST /api/auth/token-delivery Zavolá sa **iba ak** ste v odpovedi na token-exchange vrátili `requestAccessToken: true`. ``` X-Plugin-Api-Key: VLOZ_SEM_API_KEY Content-Type: application/json ``` ```json { "userId": "user@example.com", "tokens": [ { "tenantId": "123456", "name": "Moja Firma s.r.o.", "accessToken": "" }, { "tenantId": "789012", "name": "Druhá Firma a.s.", "accessToken": "" } ], "pluginId": "fiskalpro" } ``` 1. Overte `X-Plugin-Api-Key`. 2. Overte, že `pluginId` zodpovedá vášmu — inak `400`. 3. Prázdne pole `tokens` → vráťte `200` ako no-op. 4. Pre každý záznam bezpečne uložte `accessToken` pod kľúčom `(userId, tenantId, pluginId)`; záznamy s prázdnym `tenantId` alebo `accessToken` preskočte. 5. Vráťte `200`. `accessToken` je nepriehľadný secret `accessToken` slúži na volanie KROS OpenAPI v mene danej firmy a je to **opaque secret** — nikdy ho neloguj­te a nikdy ho nevystavujte do prehliadača. Ukladajte ho rovnako bezpečne, ako by ste ukladali heslo alebo API kľúč. ### GET /auth/callback?code=… Sem KROS na konci launchu presmeruje **prehliadač** používateľa. 1. Overte a **atomicky skonzumujte** `code` — je single-use, to je jeho jediná ochrana proti replay útoku. Neplatný, expirovaný alebo už použitý kód → `400`. 2. Z uloženého záznamu (`userId`, `tenantIds`, `pluginId`) vytvorte reláciu (napr. prihlásením s cookie). 3. Presmerujte na hlavnú obrazovku doplnku (`302`). ## Bezpečnosť - **Konštantný čas pri porovnaní API kľúča.** Bežné porovnanie reťazcov (`==`) sa spravidla zastaví na prvom nezhodnom znaku, čím cez čas odpovede prezradí kľúč po jednotlivých bajtoch. Použite funkciu na porovnanie s konštantným časom vo vašom jazyku (napr. `CryptographicOperations.FixedTimeEquals` v .NET, `crypto.timingSafeEqual` v Node.js, `hmac.compare_digest` v Pythone). - **RS256-only validácia JWT cez JWKS**, s rotáciou kľúča podľa `kid` — presne preto existuje JWKS endpoint namiesto natvrdo zadaného verejného kľúča. - **Launch code**: kryptograficky náhodný, 64 znakov, single-use, TTL 30 s. Pri distribuovanom nasadení (viac inštancií doplnku) použite úložisko s atomickým „získaj a zmaž" (napr. Redis), aby dve inštancie nemohli ten istý kód skonzumovať dvakrát súčasne. - **HTTPS všade** — v produkcii povinné, HTTP iba lokálne pri vývoji. - **Rate limiting** na oboch auth endpointoch — presné limity pre tento povrch nemáme potvrdené, pozri poznámku v [Chyby a limity](../chyby-a-limity.html). - **Žiadne tajomstvá do logov** — access tokeny, telá JWT ani API kľúč sa nelogujú. Chybové hlášky smerom von držte generické, detaily len na strane servera. ## Čo dodá KROS a čo dodáte vy KROS vám dodá: | Údaj | Príklad | | --- | --- | | `pluginId` | `fiskalpro` | | JWKS URL | `https://api-esw.kros.sk/plugins/.well-known/jwks.json` | | API kľúč (`X-Plugin-Api-Key`) | `VLOZ_SEM_API_KEY` — doručí sa bezpečným kanálom, nikdy e-mailom v čistom texte | | Očakávané `iss` / `aud` | `plugin-broker` / `plugin` (fixné) | | Base URL KROS OpenAPI a spôsob autentifikácie access tokenom | dodá KROS pri onboardingu | | Prostredia | test/staging/produkčné hostname | Vy dodáte KROS: | Pole | Príklad | Popis | | --- | --- | --- | | Name | `FiskalPro` | zobrazovaný názov doplnku | | Description | `Elektronická fakturácia` | krátky popis | | BaseUrl | `https://fiskalpro.example.com` | HTTPS base URL doplnku | | ApiKey | `VLOZ_SEM_API_KEY` | hodnota pre hlavičku `X-Plugin-Api-Key` | | TokenExchangeTimeoutSeconds | `10` | 1–300 | | TokenDeliveryTimeoutSeconds | `10` | 1–300 | ## Chybové stavy | Situácia | Kto | HTTP | Dôsledok | | --- | --- | --- | --- | | Doplnok nie je na strane KROS zaregistrovaný | KROS Gateway | `404` | launch zlyhá | | Podpisovací kľúč nie je nakonfigurovaný | KROS Gateway | `503` | launch zlyhá | | Nepovolený tenant v launch požiadavke | KROS Gateway | `403` | launch zlyhá | | Timeout na `token-exchange` | KROS Gateway | `504` | launch zlyhá | | Transportná/JSON chyba alebo prázdny `launchCode` z `token-exchange` | KROS Gateway | `502` | launch zlyhá | | `token-delivery` zlyhalo | KROS Gateway | `502` | launch zlyhá (ak bol access token vyžiadaný) | | Zlý `X-Plugin-Api-Key` | váš doplnok | `401` | launch zlyhá | | Neplatný podpis JWT alebo nezhoda `plugin_id` | váš doplnok | `401` | launch zlyhá | | Neplatný, expirovaný alebo už použitý `code` | váš doplnok | `400` | callback zlyhá | | Rate limit | oba | `429` | požiadavka odmietnutá | Ak provider vráti pre všetky firmy prázdne tokeny, `token-delivery` sa preskočí a launch napriek tomu pokračuje — používateľ sa prihlási bez aktívneho pripojenia na KROS OpenAPI. Váš doplnok musí tento stav zvládnuť gracefully, nie ho vyhodnotiť ako chybu launchu. ## Implementačný checklist - Dohodnuté s KROSom: `pluginId`, `BaseUrl`, API kľúč, JWKS URL, prostredia, spôsob volania KROS OpenAPI. - `POST /api/auth/token-exchange`: overuje `X-Plugin-Api-Key`; overuje JWT cez JWKS (RS256, `iss=plugin-broker`, `aud=plugin`, `exp`, `plugin_id`). - Čítanie `sub` a `tenant_ids` (JSON pole); idempotentné „nájdi alebo vytvor" pre používateľa a firmy. - Generovanie single-use launch code (64 znakov, TTL 30 s), vrátenie `{ launchCode, requestAccessToken }`. - `POST /api/auth/token-delivery`: overuje API kľúč a `pluginId`; bezpečne ukladá `accessToken` per firma. - `GET /auth/callback?code=…`: atomicky skonzumuje code, vytvorí cookie reláciu, presmeruje. - Volanie KROS OpenAPI uloženým access tokenom (per firma). - HTTPS všade; tajomstvá sa nelogujú; rate limiting na auth endpointoch. - Graceful spracovanie: 0 firiem, prázdny token pre firmu, `429`, opakovaný launch s inou firmou (nová cookie relácia nahradí starú). ## Dve varianty gateway Protokol, ktorý doplnok implementuje, je **identický bez ohľadu na to, ktorá KROS gateway launch spúšťa** — líšia sa len tým, akú hodnotu nesie claim `sub`, a tým, ako presne používateľ launch spustil: - Jedna varianta je produkčné zapojenie do KROS Fakturácie: `sub` nesie **e-mail** používateľa, tenanti sú firmy s príslušnou licenciou a access token zodpovedá licenčnému oprávneniu na KROS OpenAPI danej firmy. - Druhá varianta je samostatná (štandalón) brána s vlastným prihlásením: `sub` nesie **numerické ID** z tohto prihlásenia. Váš doplnok sa nemusí starať, ktorá z nich launch spustila — vidí vždy len `token-exchange`, `token-delivery`, `callback` a JWKS endpoint, so zhodným tvarom požiadaviek a odpovedí. ## Nie ste v .NET? Protokol je zámerne jazykovo nezávislý — je postavený na JSON, JWT a JWKS, teda na formátoch a štandardoch, ktoré má knižnicu takmer každý ekosystém. Ak váš doplnok nie je v .NET, nepotrebujete žiadnu konkrétnu knižnicu ani balík — implementujte priamo tri kontrakty popísané vyššie (`token-exchange`, `token-delivery`, `callback`) pomocou bežnej JWT knižnice vo vašom jazyku, ktorá vie overiť RS256 podpis cez JWKS. ============================================================================== # Najčastejšie integrácie Zdroj: https://api.krosdoplnky.sk/integracie/index.html ============================================================================== # Najčastejšie integrácie Táto sekcia obsahuje kompletné recepty pre dva najčastejšie scenáre napojenia na KROS API: ktoré endpointy v akom poradí volať a na aké prekážky si dať pozor. Tretí scenár — eFaktúra — pripravujeme. ## Scenáre ### E-shop → KROS Objednávky a faktúry smerujú z e-shopu do KROSu, skladové karty a zostatky sa vracajú späť do e-shopu. **Vhodné pre**E-shopy a redakčné systémy, ktoré chcú fakturovať cez KROS a zobrazovať aktuálne skladové zostatky. [E-shop → KROS →](eshop.html) ### POS → KROS Skladové karty a sklady smerujú z KROSu do pokladne, predaje a tržby sa vracajú späť do KROSu. **Vhodné pre**Pokladničné (POS) systémy, ktoré potrebujú aktuálny sortiment a chcú reportovať tržby do KROSu. [POS → KROS →](pos.html) ### eFaktúra pripravujeme Scenár zatiaľ nie je zdokumentovaný — postup doplníme, keď KROS API rozšírime o funkčnosť potrebnú pre eFaktúru. **Vhodné pre**Systémy, ktoré budú s KROSom vymieňať elektronické faktúry. [eFaktúra →](efaktura.html) ============================================================================== # E-shop → KROS Zdroj: https://api.krosdoplnky.sk/integracie/eshop.html ============================================================================== # E-shop → KROS Recept na napojenie e-shopu alebo redakčného systému na KROS API: ktoré endpointy volať, v akom poradí a na aké prekážky si dať pozor pri fakturácii a synchronizácii skladu. ## Čo tento scenár rieši Objednávky a faktúry smerujú z e-shopu do KROSu — vytvoríte ich raz vo svojom systéme a KROS ich prevezme na spracovanie a fakturáciu. Opačným smerom, z KROSu do e-shopu, sa vracajú skladové karty a ich zostatky, aby e-shop vždy zobrazoval aktuálnu dostupnosť tovaru. ## Tok dát > Diagram: Tok dát medzi e-shopom a KROSom: e-shop posiela objednávky cez `POST /api/received-orders/batch` a faktúry cez `POST /api/invoices/batch` do KROSu; KROS posiela skladové karty cez `GET /api/catalog-items` (filtrované podľa `catalogItemChangedTimestamp`) a zoznam skladov cez `GET /api/warehouses` späť do e-shopu. ## Krok za krokom 1. Autorizácia Získajte prístupový token cez [Integration Consent](../autorizacia/integration-consent.html), alebo pre prvú integráciu použite [manuálny token](../autorizacia/manualny-token.html). Spojenie a platnosť tokenu overte volaním GET `/api/auth/check`. 2. Zistite číselné rady Zavolajte GET `/api/numberingSequences`. Kód číselného radu potrebujete skôr, než budete chcieť sami riadiť číslovanie dokladov. 3. Prenos objednávok Nové objednávky pošlite cez POST `/api/received-orders/batch`, maximálne 100 objednávok v jednej dávke. 4. Prenos faktúr Vystavené faktúry pošlite cez POST `/api/invoices/batch`, maximálne 100 faktúr v jednej dávke. 5. Skladové karty do e-shopu Skladové karty stiahnete cez GET `/api/catalog-items` s parametrom `catalogItemChangedTimestamp`, aby ste stiahli len to, čo sa zmenilo od posledného sync-u. Zoznam skladov získate cez GET `/api/warehouses`. 6. 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](../webhooky.html). ## Odporúčané endpointy | Metóda | Cesta | Prečo | | --- | --- | --- | | GET | `/api/auth/check` | Overí platnosť tokenu pred prvým volaním. | | GET | `/api/numberingSequences` | Vráti kód číselného radu, ktorý potrebujete na riadenie čísla dokladu. | | POST | `/api/received-orders/batch` | Prenesie objednávky z e-shopu do KROSu, dávkovo po 100 kusoch. | | POST | `/api/invoices/batch` | Prenesie faktúry z e-shopu do KROSu, dávkovo po 100 kusoch. | | GET | `/api/catalog-items` | Vráti skladové karty; s `catalogItemChangedTimestamp` len tie, čo sa zmenili od posledného sync-u. | | GET | `/api/warehouses` | Vráti zoznam skladov, na ktoré sa dá naviazať skladová karta. | ## Na čo si dať pozor ### POST vytvára aj aktualizuje Rovnaký POST endpoint doklad vytvorí aj aktualizuje — nie je to len na vytvorenie. K aktualizácii dôjde vtedy, keď dvojica `documentNumber` a kód číselného radu už v databáze existuje. Odoslanie toho istého dokladu druhýkrát s rovnakým číslom preto doklad prepíše, nevytvorí jeho duplicitnú kópiu. ### Partneri sa vytvárajú automaticky Partner (odberateľ/dodávateľ) sa vytvorí automaticky priamo z dokladu, ktorý pošlete. Deduplikácia sa líši podľa typu partnera: fyzické osoby sa párujú podľa **mena a e-mailu**, právnické osoby podľa **IČO, DIČ a IČ DPH**. Nekonzistentné údaje o partnerovi preto spôsobujú duplicity konkrétne pri fyzických osobách — malá odchýlka v mene alebo e-maile založí nového partnera namiesto priradenia k existujúcemu. ### itemCode prepája položku so skladovou kartou `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. ### variableSymbol má tri režimy `variableSymbol` môžete poslať v jednom z troch tvarov: explicitnú hodnotu, ktorú chcete použiť; vynechaný, pričom sa vygeneruje automaticky z čísla dokladu s odstránenými neplatnými znakmi; alebo prázdny reťazec, ak variabilný symbol nepoužívate. ### documentNumber prázdne alebo vynechané spustí automatické číslovanie Ak `documentNumber` necháte prázdne alebo ho vynecháte, KROS doklad očísluje sám podľa číselného radu. Hodnotu posielajte iba vtedy, keď chcete číslo dokladu riadiť sami. ### 409 Conflict — okno 120 sekúnd Identickú požiadavku nemôžete zopakovať do **120 sekúnd** od predchádzajúceho úspešného spracovania — KROS odpovie `409 Conflict`. Retry logika musí toto okno rešpektovať, inak bude opakovane zlyhávať. Kódy chýb a odporúčanú retry stratégiu nájdete na stránke [Chyby a limity](../chyby-a-limity.html). ============================================================================== # POS → KROS Zdroj: https://api.krosdoplnky.sk/integracie/pos.html ============================================================================== # 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 > Diagram: 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 1. Autorizácia Ak doplnok beží vnútri KROS aplikácie, získajte token cez [Token Broker](../autorizacia/token-broker.html). Ak beží mimo nej — samostatná pokladnica alebo externý POS systém — použite [Integration Consent](../autorizacia/integration-consent.html). 2. 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. 3. 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`. 4. Ú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`. 5. 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`. 6. 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](../webhooky.html). ## 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í. ============================================================================== # eFaktúra Zdroj: https://api.krosdoplnky.sk/integracie/efaktura.html ============================================================================== # eFaktúra Napojenie na eFaktúru **pripravujeme**. Túto stránku dopĺňame až vtedy, keď KROS API rozšírime o potrebnú funkčnosť — dovtedy tu zámerne nie sú žiadne endpointy ani sekvencie volaní. Pripravujeme Kým eFaktúru do API nedoplníme, nestavajte na tejto stránke návrh integrácie a neodhadujte tvar volaní podľa ostatných scenárov. Akonáhle bude funkčnosť k dispozícii, nájdete tu kompletný postup a stránka prestane byť označená ako *pripravujeme*. ## Čo tu neskôr pribudne Obsah bude mať rovnakú štruktúru ako ostatné scenáre v tejto sekcii: - ktorý autorizačný model pre eFaktúru použiť, - sekvenciu volaní v poradí, v akom ich má integrácia vykonať, - zoznam dotknutých endpointov a ich vstupov a výstupov, - ošetrenie chybových stavov a odporúčaný retry postup. ## Medzitým Ak už teraz viete, čo od eFaktúry v API potrebujete, napíšte nám na [integracie@kros.sk](mailto:integracie@kros.sk) — konkrétne požiadavky od integrátorov zohľadníme pri návrhu. Overené scenáre, ktoré fungujú dnes, nájdete v [Najčastejších integráciách](index.html). ============================================================================== # Webhooky Zdroj: https://api.krosdoplnky.sk/webhooky.html ============================================================================== # Webhooky KROS vie o udalostiach vo Fakturácii a Financiách informovať váš server v reálnom čase — namiesto toho, aby ste dáta museli pravidelne dopytovať. Táto stránka popisuje tri eventy, ktoré KROS posiela, ako overiť, že notifikácia naozaj prišla z KROSu, a ako čítať telo notifikácie vrátane čiastočných zlyhaní. ## Tri eventy KROS posiela tri typy notifikácií. Výber správneho — a rozlíšenie doklad vs. Financie — je dôležitý: zámena je dôvod, prečo partneri dostávajú eventy, ktoré nečakali, alebo im naopak chýbajú tie, ktoré potrebujú. | Event | Kedy sa pošle | | --- | --- | | Document webhook | doklad vo Fakturácii bol vytvorený, zmenený alebo vymazaný. | | Payment webhook (doklad) | platba **dokladu** bola vytvorená, zmenená alebo vymazaná; netýka sa zmien v module Financie. | | Payment webhook (Financie) | platba v module **Financie** bola vytvorená, zmenená alebo vymazaná; nezahŕňa platby dokladov, ktoré nie sú viazané na bankový účet, platobnú bránu ani pokladnicu. | ## Kde sa webhook nastavuje Adresu svojho endpointu zadáte jedným z dvoch spôsobov: buď priamo v KROS UI v sekcii **API prepojenia**, do poľa **URL pre príjem notifikácií** (pozri [Manuálny token](autorizacia/manualny-token.html)), alebo cez parameter `webhook` consent URL, ak používate self-service autorizáciu (pozri [Integration Consent](autorizacia/integration-consent.html)). ## Verifikácia podpisu Kľúč aj telo sa kóduje ako UTF-16LE, nie UTF-8 Toto je najčastejšia príčina zlyhania integrácie. Podpis v hlavičke `X-Kros-Signature-256` je HMAC-SHA256 nad telom požiadavky, kde sa **aj telo, aj tajný kľúč kódujú ako UTF-16LE** — nie ako UTF-8, ktoré je prirodzeným (a nesprávnym) predpokladom. Výsledný hash sa zapíše ako Base64. Odporúčaná dĺžka kľúča je 256 bitov. Ak kľúč alebo telo zakódujete ako UTF-8, výpočet prebehne bez chyby, ale vypočítaný podpis sa nikdy nebude zhodovať s tým, čo poslal KROS — chyba sa navonok neprejaví inak než tichým zlyhaním verifikácie. Štyri funkčne rovnaké implementácie nižšie počítajú ten istý hash bajt po bajte. C# a PHP sú prevzaté priamo zo špecifikácie `KROS Webhooks`; JavaScript (Node) a Python sú napísané tak, aby dávali identický výsledok — kódovanie UTF-16LE zabezpečuje `Buffer.from(s, 'utf16le')` v Node a `s.encode('utf-16-le')` v Pythone. C# PHP JavaScript Python ```csharp private string? GenerateHash(string payload, string webHookSecret) { var hash = new HMACSHA256(Encoding.Unicode.GetBytes(webHookSecret)); return Convert.ToBase64String(hash.ComputeHash(Encoding.Unicode.GetBytes(payload))); } // Overenie prijatého webhooku — konštantný čas, nie ==: var expected = GenerateHash(requestBody, webHookSecret); var received = request.Headers["X-Kros-Signature-256"]; var isValid = CryptographicOperations.FixedTimeEquals( Convert.FromBase64String(expected), Convert.FromBase64String(received)); ``` ```php function generateHash($data, $key) { $keyEncoded = mb_convert_encoding($key, "UTF-16LE"); $dataEncoded = mb_convert_encoding($data, "UTF-16LE"); return base64_encode(hash_hmac("sha256", $dataEncoded, $keyEncoded, true)); } // Overenie prijatého webhooku — konštantný čas, nie ==: $expected = generateHash($requestBody, $webHookSecret); $received = $_SERVER['HTTP_X_KROS_SIGNATURE_256'] ?? ''; $isValid = hash_equals($expected, $received); ``` ```javascript const crypto = require('crypto'); function generateHash(payload, webHookSecret) { const key = Buffer.from(webHookSecret, 'utf16le'); const data = Buffer.from(payload, 'utf16le'); return crypto.createHmac('sha256', key).update(data).digest('base64'); } // Overenie prijatého webhooku — konštantný čas, nie ==: const expected = generateHash(requestBody, webHookSecret); const received = req.headers['x-kros-signature-256'] || ''; const isValid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); ``` ```python import base64 import hashlib import hmac def generate_hash(payload: str, web_hook_secret: str) -> str: key = web_hook_secret.encode("utf-16-le") data = payload.encode("utf-16-le") digest = hmac.new(key, data, hashlib.sha256).digest() return base64.b64encode(digest).decode("ascii") # Overenie prijatého webhooku — konštantný čas, nie ==: expected = generate_hash(request_body, web_hook_secret) received = request.headers.get("X-Kros-Signature-256", "") is_valid = hmac.compare_digest(expected, received) ``` Vo všetkých štyroch jazykoch sa porovnanie robí konštantno-časovou funkciou (`CryptographicOperations.FixedTimeEquals`, `hash_equals`, `crypto.timingSafeEqual`, `hmac.compare_digest`), nikdy operátorom `==` ani `===`. Naivné porovnanie reťazcov sa zastaví pri prvom nezhodnom znaku, a rozdiel v čase odpovede tak útočníkovi prezradí podpis bajt po bajte, kým ho neuhádne celý. ## Telo notifikácie Príklad úspešne spracovanej dávky: ```json { "companyId": 119919, "entityType": 2, "results": { "entities": [{ "index": 0, "source": 1, "operation": 2, "status": 201, "data": { "documentType": 2, "documentId": 926523, "variableSymbol": "4444555", "sumOfPayment": 1 }, "problems": null }], "relatedEntities": [] }, "status": 200, "requestId": "50304274-197c-40e9-8804-84e23e28efa2" } ``` `207` znamená čiastočné zlyhanie Vrchný `status` **200** znamená, že spracovanie prebehlo úplne v poriadku. **`207` znamená čiastočné zlyhanie** — niektoré položky v dávke sa nespracovali a podrobnosti nájdete v poli `problems` príslušnej entity. Webhook handler, ktorý kontroluje iba to, že `status` je `200`, tieto čiastočné zlyhania potichu zahodí. Pole `requestId` vám umožní priradiť túto notifikáciu k pôvodnému nahratiu — je to tá istá hodnota, akú ste dostali v odpovedi `202 Accepted` pri nahrávaní dokladu. ## Typy problémov | Typ | Význam | | --- | --- | | `resource-locked` | „Resource is locked by non-editable lock, therefore the resource cannot be edited.“ | | `id-conflict` | zdroj sa nepodarilo jednoznačne identifikovať na úpravu. | | `duplicate-document-number` | rovnaké číslo dokladu a rad sa v dávke vyskytuje viac ako raz. | ## Tok > Diagram: Tok webhooku: nahratie dokladu, `202 Accepted` s `requestId`, asynchrónne spracovanie v KROSe, POST notifikácia na váš endpoint, overenie podpisu a priradenie výsledku k pôvodnému nahratiu podľa `requestId`. ## Špecifikácia Webhooky majú **vlastnú** OpenAPI špecifikáciu, oddelenú od špecifikácie endpointov: - [`app-webhooks-swagger.json`](https://api-economy.kros.sk/app-webhooks-swagger.json) — živá špecifikácia webhookov (autoritatívna) - [Lokálna kópia](ai/kros-webhooks-openapi.json) — tá istá špecifikácia uložená na tomto webe, s dátumom stiahnutia - [Swagger UI](https://api-economy.kros.sk/swagger/index.html) — otvorí sa na špecifikácii endpointov; webhooky si prepnete v rozbaľovacom zozname vpravo hore ============================================================================== # Chyby a limity Zdroj: https://api.krosdoplnky.sk/chyby-a-limity.html ============================================================================== # Chyby a limity Prehľad HTTP kódov, ktoré KROS API vracia, štruktúry chybových odpovedí, rate limitov a odporúčanej retry stratégie — aby ste vedeli spoľahlivo rozlíšiť, ktorý request má zmysel opakovať a ktorý nie. ## HTTP kódy Nasledujúca tabuľka zhŕňa kódy, s ktorými sa pri volaní KROS API stretnete najčastejšie. | Kód | Význam | | --- | --- | | `202 Accepted` | dáta prijaté na spracovanie; spracovanie beží asynchrónne; odpoveď obsahuje `requestId` | | `400 Bad Request` | neplatné alebo chýbajúce dáta; detaily v tele odpovede | | `401 Unauthorized` | neplatný alebo chýbajúci autorizačný token | | `402 Payment Required` | nedostatočná alebo expirovaná licencia | | `405 Method Not Allowed` | endpoint nie je podporovaný alebo je vo vývoji | | `409 Conflict` | identický request sa nedá poslať znova do 120 sekúnd od úspešného | | `429 Too Many Requests` | prekročený rate limit | ## 202 Accepted `202 Accepted` znamená, že dáta boli **prijaté** na spracovanie — nie že spracovanie **uspelo**. Skutočný výsledok príde neskôr formou webhooku. Telo odpovede obsahuje `requestId`, podľa ktorého notifikáciu spárujete s pôvodným nahratím: ```json { "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` `202` neznamená úspech Toto je bežná a nákladná chyba: integrácia, ktorá pri prijatí `202 Accepted` označí doklad za úspešne spracovaný, si výsledok domýšľa. Skutočný výsledok spracovania — vrátane prípadného čiastočného zlyhania — sa dozviete až z [webhooku](webhooky.html), ktorý nesie rovnaké `requestId`. ## 400 Bad Request Telo odpovede obsahuje zoznam konkrétnych problémov, ktoré request zamietli: ```json { "isValid": false, "errors": [{ "documentIndex": 0, "propertyPath": "items[0].amount", "errorMessage": "Unexpected character encountered while parsing value: a." }] } ``` `documentIndex` určuje pozíciu dokladu **v rámci vašej dávky** — podľa neho request namapujete späť na konkrétny doklad, ktorý ste posielali. `propertyPath` ukazuje na konkrétne pole, ktoré chybu spôsobilo. Bez tohto rozlíšenia sa chyba nedá priradiť k dokladu, ktorý ju vyvolal, najmä pri dávke s viacerými dokladmi naraz. ## Rate limity Limity sa líšia podľa toho, ktorý povrch voláte. Dátové API má vlastný rozpočet requestov, spúšťacie endpointy [Token Brokera](autorizacia/token-broker.html) vlastný — čísla sa preto nedajú spriemerovať ani nahradiť jednou „bezpečnejšou“ hodnotou. ### Dátové API | Okno | Limit | | --- | --- | | 1 sekunda | **10** requestov | | 1 minúta | **300** requestov | Obe okná platia súčasne. Desať requestov za sekundu je strop krátkej špičky, nie tempo, ktoré sa dá držať — udržateľná priepustnosť je **5 requestov za sekundu** (300 za minútu). Ak by ste posielali plných desať requestov za sekundu nepretržite, minútový rozpočet vyčerpáte po pol minúte a zvyšok minúty dostanete `429`. Rozpočet sa počíta **na integračný token**, teda na vaše napojenie ako celok — nie na IP adresu a nie na firmu. Ak jedným tokenom obsluhujete viac firiem, delia sa o ten istý rozpočet: dávkové synchronizácie preto rozložte v čase a nespúšťajte ich pre všetky firmy naraz. Do limitu vstupujú iba requesty, ktoré prešli autorizáciou — request s neplatným tokenom skončí na `401` skôr, než sa započíta. Stav rozpočtu nemusíte odhadovať, API ho posiela v hlavičkách: | Hlavička | Kedy príde | Význam | | --- | --- | --- | | `x-rate-limit-limit` | pri úspešnej odpovedi | okno, ktorého sa zostatok týka | | `x-rate-limit-remaining` | pri úspešnej odpovedi | koľko requestov v tomto okne ešte máte | | `x-rate-limit-reset` | pri úspešnej odpovedi | čas resetu okna v sekundách UTC epoch | | `retry-after` | pri `429` | počet sekúnd, po ktorých má zmysel skúsiť znova | Limit je strop, nie garantovaná priepustnosť Ak vám občas prejde viac requestov, než tabuľka uvádza, neberte to ako vyšší limit — plánujte podľa čísel vyššie a spracovanie `429` s odstupom majte v integrácii vždy, aj keď ste na limit zatiaľ nenarazili. ### Token Broker Spúšťací (launch) flow doplnku má vlastné, oveľa nižšie limity — chránia prihlasovanie, nie prenos dát: | Povrch | Limit | | --- | --- | | spustenie doplnku na strane KROS Gatewaya | **10** requestov za minútu na IP adresu | | prevzatie launchu na strane vášho doplnku | **20** requestov za minútu na IP adresu | Prekročenie vráti `429`. Druhé číslo je hodnota, ktorú KROS partnerom odporúča a ktorú má nastavené referenčné riešenie na strane doplnku — ak si spracovanie launchu píšete sami, limit si riadite vy. Pri bežnej práci používateľa sa ani jeden z týchto limitov nedosiahne; narazíte na ne prakticky len pri automatizovanom testovaní, ktoré spúšťa launch v slučke. ## Retry stratégia - Na `429 Too Many Requests` počkajte toľko sekúnd, koľko uvádza hlavička `retry-after`; ak v odpovedi nie je, opakujte s exponenciálnym odstupom (exponential backoff). Rovnaký odstup použite na `5xx` chyby. - Na `409 Conflict` neopakujte request skôr, než uplynie 120-sekundové okno od pôvodného úspešného requestu. - `400 Bad Request`, `401 Unauthorized` a `402 Payment Required` **nikdy** neopakujte — bez zmeny na vašej strane (opravy dát, tokenu alebo licencie) nemôžu uspieť ani na ďalší pokus. - Namiesto slepého opakovania requestu si výsledok radšej overte podľa `requestId` — najmä pri `202 Accepted`, kde reálny výsledok príde webhookom. ## Batch limity Dávka smie obsahovať najviac **100 dokladov** na jeden request, rovnako pri nahrávaní aj pri čítaní. Väčšie množstvo rozdeľte na viac requestov a výsledok každého z nich sledujte samostatne podľa jeho vlastného `requestId`. ============================================================================== # Obchod doplnkov Zdroj: https://api.krosdoplnky.sk/doplnky-store.html ============================================================================== > **Vyžaduje partnerský prístup** — celá stránka je dnes verejná, neskôr bude za prihlásením. # Obchod doplnkov Obchod doplnkov je zoznam doplnkov ponúkaných priamo v KROS aplikácii, odkiaľ si ich zákazník jedným klikom nainštaluje. Zaradenie doplnku do tohto zoznamu nie je samoobslužné — vyžaduje dohodu s KROSom a manifest, ktorý opisuje váš doplnok strojovo čitateľným spôsobom. Vyžaduje dohodu s KROSom Táto stránka opisuje kontrakt `manifest.json` a pravidlá nahrávania doplnku, ktoré potrebuje partner so schváleným prístupom do obchodu doplnkov. Samotné zaradenie doplnku do zoznamu nie je samoobslužné (pozri nižšie) — vybavuje sa cez [integracie@kros.sk](mailto:integracie@kros.sk). ## Ako sa doplnok dostane do obchodu Na rozdiel od [Integration Consent](autorizacia/integration-consent.html), ktorý si napojíte úplne samoobslužne bez akejkoľvek registrácie, zaradenie doplnku **do obchodu doplnkov** samoobslužné nie je. Napíšte na [integracie@kros.sk](mailto:integracie@kros.sk) a uveďte: - názov doplnku, - čo doplnok robí, - na ktorý KROS produkt sa napája (napr. KROS Fakturácia, KROS Sklad), - spôsob autentifikácie (`token-broker` alebo `manual` — pozri nižšie), - HTTPS base URL doplnku. Na základe toho KROS pridelí `pluginId`/`partnerId` a dohodne technické detaily zvoleného spôsobu autentifikácie. Až potom má zmysel pripravovať `manifest.json` a balík na nahratie. ## manifest.json `manifest.json` je jediný zdroj pravdy o tom, ako sa doplnok volá, čo robí, kto je jeho partner a ako sa doň prihlasuje. Má štyri povinné najvyššie objekty: | Objekt | Polia | | --- | --- | | `plugin` | `id`, `partnerId`, `name`, `version`, `changelog`, `requiresReconfiguration` | | `display` | `shortDescription` (10 – 150 znakov), `detail.description` (markdown, 50 – 20 000 znakov), `categories` (1 – 3 položky), `tags` (najviac 10) | | `partner` | `name`, `website`, `privacyPolicyUrl`, `contact` (aspoň jeden kanál), `license` | | `authentication` | jeden z dvoch spôsobov — pozri nižšie | `plugin.id` je stabilný identifikátor doplnku, jeho stredný segment sa musí zhodovať s `plugin.partnerId`. `plugin.changelog` je pri prvej verzii `null`, pri každej ďalšej verzii je povinný. `partner.contact` musí niesť aspoň jeden kontaktný kanál — e-mail, support URL alebo vyplnené `website`. ## Dva spôsoby autentifikácie v manifeste Pole `authentication.method` je presne jedno z dvoch: - **`token-broker`** — doplnok sa otvára **vnútri** KROS aplikácie a používateľ je doň automaticky prihlásený. Vyžaduje `tokenBroker.baseUrl` (HTTPS) a zdieľaný API kľúč. Celý protokol je popísaný na stránke [Token Broker partner](autorizacia/token-broker.html). - **`manual`** — používateľa presmerujete do **externého okna** mimo KROS aplikácie. Vyžaduje `manual.redirectUrl`; nejde o inštaláciu v zmysle Token Brokera a nenesie žiadny token. Príklad manifestu so spôsobom `token-broker` (skrátené o nepovinné polia): ```json { "manifestVersion": "1.0.0", "plugin": { "id": "sk.partner-id.doplnok-id", "partnerId": "partner-id", "name": "Názov doplnku", "version": "1.0.0", "changelog": null, "requiresReconfiguration": false }, "display": { "shortDescription": "Krátky popis doplnku (10 – 150 znakov).", "categories": ["accounting"], "tags": ["priklad", "doplnok"], "detail": { "description": "## Názov doplnku\n\nMarkdown popis, 50 – 20000 znakov." } }, "partner": { "name": "Partner s.r.o.", "website": "https://partner.example.com", "privacyPolicyUrl": "https://partner.example.com/privacy", "contact": { "emails": ["support@partner.example.com"] }, "license": { "type": "proprietary", "url": "https://partner.example.com/eula" } }, "authentication": { "method": "token-broker", "tokenBroker": { "baseUrl": "https://doplnok.partner.example.com", "apiKeySecretRef": "Plugins:sk.partner-id.doplnok-id:ApiKey", "apiKey": "VLOZ_SEM_API_KEY" } } } ``` API kľúč je zdieľané tajomstvo Hodnota `authentication.tokenBroker.apiKey` je zdieľaný secret medzi KROSom a vaším doplnkom. Musí k vám prísť **bezpečným kanálom** (nikdy e-mailom v čistom texte) a **nesmie sa nikdy commitnúť do repozitára** — ani do príkladov, ani do konfigurácie, ktorá sa verzuje spolu s kódom. V manifeste, ktorý nahrávate, drží miesto placeholder ako vyššie; skutočnú hodnotu vkladajte až v mieste, kde beží doplnok (secret store, premenné prostredia). ## Balík Endpoint na nahratie doplnku prijíma **`.zip` archív**, ktorý má v koreňovom adresári súbor `manifest.json` (a spravidla ikonu doplnku). Samotný `manifest.json` bez zabalenia do `.zip` sa nahrať **nedá**. `categories` je špecifické pre nasadenie Zoznam hodnôt povolených v `display.categories` nie je univerzálny naprieč všetkými nasadeniami KROS platformy — konkrétne nasadenie môže mať inú podmnožinu (alebo inú sadu) kategórií. Pred vyplnením manifestu si zoznam hodnôt overte proti cieľovému nasadeniu, ktorému doplnok posielate; nespoliehajte sa na to, že hodnota, ktorá fungovala inde, bude prijatá aj tu. ============================================================================== # API reference Zdroj: https://api.krosdoplnky.sk/api-reference.html ============================================================================== # API reference Táto stránka je mapa, nie referencia. Tento web dokumentuje autorizačné a integračné scenáre — konkrétny, vždy aktuálny zoznam endpointov, ich parametrov a návratových tvarov nájdete v Swaggeri, ktorý sa generuje priamo z bežiaceho API. ## Swagger Interaktívna dokumentácia beží na [https://api-economy.kros.sk/swagger/index.html](https://api-economy.kros.sk/swagger/index.html). Tlačidlo **Authorize** vpravo hore umožňuje vložiť váš token a endpointy si priamo v prehliadači vyskúšať naživo. V rozbaľovacom zozname špecifikácií v hornej časti stránky si vyberiete aj špecifikáciu webhookov. ## OpenAPI špecifikácie Obe špecifikácie máme aj ako lokálnu kópiu priloženú k tomuto webu (pozri [Pre AI agentov](ai.html)) — pre priame strojové spracovanie použite tie, pre vždy aktuálny stav použite live URL. | Špecifikácia | Live URL | Lokálna kópia | | --- | --- | --- | | KROS OpenAPI (endpointy) | [`https://api-economy.kros.sk/swagger/Api%20endpoints/swagger.json`](https://api-economy.kros.sk/swagger/Api%20endpoints/swagger.json) | [`ai/kros-openapi.json`](ai/kros-openapi.json) | | KROS Webhooks | [`https://api-economy.kros.sk/app-webhooks-swagger.json`](https://api-economy.kros.sk/app-webhooks-swagger.json) | [`ai/kros-webhooks-openapi.json`](ai/kros-webhooks-openapi.json) | ## Skupiny endpointov Endpointy KROS OpenAPI sú rozdelené do desiatich skupín: | Skupina | Popis | | --- | --- | | Auth | autentifikácia a získanie tokenu pre volania ostatných skupín | | Invoices | vydané faktúry — nahrávanie, čítanie, stav spracovania | | Proforma Invoices | zálohové (proforma) faktúry | | Received Orders | prijaté objednávky, typicky z e-shopu | | Delivery Notes | dodacie listy k vydaným dokladom | | Expenses | prijaté náklady a výdavkové doklady | | Payments | úhrady k dokladom a ich spárovanie | | Warehouses | skladové karty, zostatky a pohyby na sklade | | Attachments | prílohy pripojené k dokladom | | Settings | nastavenia firmy a číselníky relevantné pre integráciu | ## Vygenerovanie klienta Ak potrebujete typovaného klienta vo vašom jazyku, vložte ktorúkoľvek z vyššie uvedených špecifikácií do [https://editor.swagger.io/](https://editor.swagger.io/) a použite *Generate Client* pre zvolený jazyk. ## Pre AI agentov Ak namiesto ručného prehľadávania Swaggeru chcete, aby si integráciu napísal AI agent, pozrite si stránku [Naučiť AI agenta](ai.html) — obsahuje hotový prompt aj odkazy na strojovo spracovateľný balík tohto webu vrátane oboch špecifikácií vyššie.