Swagger

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

Váš e-shop KROS POST /api/received-orders/batch objednávky · max 100 v dávke POST /api/invoices/batch faktúry · max 100 v dávke GET /api/catalog-items skladové karty · catalogItemChangedTimestamp GET /api/warehouses zoznam skladov
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, alebo pre prvú integráciu použite manuálny token. 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.

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.