eKasa vie veľa, no na začiatok stačí málo. Tento článok rozdeľuje integráciu do štyroch úrovní. Prvá stačí na evidenciu tržieb, každá ďalšia uľahčí obsluhe prácu alebo pokryje ďalšie situácie u podnikateľa.
| Funkcia | Minimálna | Optimálna | Ideálna |
|---|---|---|---|
Ochrana pred duplicitou (externalId) |
áno | áno | áno |
| Registrácia dokladu a vyhodnotenie výsledku | áno | áno | áno |
| Uloženie identifikátora dokladu | áno | áno | áno |
| Kontrola stavu systému | nie | áno | áno |
| Upozornenie na koniec platnosti autentifikačných údajov | nie | áno | áno |
| Upozornenie na zaplnenie úložiska | nie | áno | áno |
| Evidencia paragónov | nie | nie | áno |
| Registrácia polohy (prenosná pokladnica) | nie | nie | áno |
Každá úroveň obsahuje všetko z predchádzajúcej. Voliteľné funkcie, napríklad úhradu faktúry, pridáte k ktorejkoľvek úrovni podľa toho, čo potrebujú vaši zákazníci, prípadne vaša vlastná prevádzka.
Minimálna integrácia
Váš softvér posiela eKase pokladničné doklady a vyhodnocuje výsledok. Nič iné na evidenciu tržieb nepotrebuje.
externalIdpri každom doklade. Je to nevyhnutné: bez neho eKasa nerozozná opakované odoslanie a tržbu zaeviduje dvakrát, keď sa stratí odpoveď. Pozri Ochrana pred duplicitou.- Registrácia dokladu pri predaji, vrátení tovaru aj oprave. Položky, platby a typy položiek popisuje článok Registrácia dokladu.
- Vyhodnotenie výsledku podľa poľa
isSuccessful:true: doklad je zaevidovaný, predaj je hotový,null: doklad je zaevidovaný v offline režime a vytlačený. Pre obsluhu je to tiež úspech, eKasa ho odošle sama,false: systém eKasa doklad odmietol. Zobrazte obsluhe dôvod z poľaerror.
- Uloženie identifikátora dokladu k predaju vo vašom systéme: unikátny identifikátor, a kým ho doklad nemá, overovací kód podnikateľa (OKP). Potrebujete ho pri vrátení tovaru, oprave alebo vyhľadaní dokladu.
- Spracovanie chýb požiadavky, napríklad neplatných údajov alebo nepripravenej tlačiarne, podľa kódu chyby (pozri HTTP API).
Čo sa dá nastaviť jednorazovo, vrátane inicializačného balíka a polohy pokladnice, urobí podnikateľ alebo servisný technik vo webovom rozhraní eKasy.
Pri minimálnej integrácii sa obsluha o probléme dozvie, až keď doklad zlyhá. Neodoslané doklady vo fronte, končiaca platnosť autentifikačných údajov či dochádzajúce miesto v úložisku pritom eKasa vie ohlásiť vopred. Preto odporúčame aspoň optimálnu integráciu.
Optimálna integrácia
K minimálnej integrácii pridajte kontrolu stavu systému. Váš softvér sa eKasy pýta na stav pri spustení a potom pravidelne, napríklad raz za pár minút alebo pred začiatkom zmeny, a upozorní obsluhu skôr, než nastane problém.
GET http://localhost:3010/api/v1/health
Od verzie 9.1 môžete kontroly obmedziť parametrom tag, napríklad ?tag=storage,queue. Bez neho sa vykonajú
všetky.
Odpoveď obsahuje celkový stav a výsledok jednotlivých kontrol (skrátené):
{
"status": "Healthy",
"entries": [
{
"name": "queue",
"status": "Healthy",
"description": "Fronta neodoslaných správ je prázdna."
},
{
"name": "subject",
"status": "Healthy",
"description": "Identifikačné a autentifikačné údaje sú v poriadku."
},
{
"name": "printer",
"status": "Healthy",
"description": "Tlačiareň je pripravená."
},
{
"name": "storage",
"status": "Healthy"
},
{
"name": "network",
"status": "Healthy"
}
]
}
Stav Healthy znamená, že je všetko v poriadku, Degraded upozorňuje na blížiaci sa problém a Unhealthy
na problém, ktorý treba riešiť hneď. Text z description môžete obsluhe rovno zobraziť.
Jednotný stav jedným volaním poskytuje služba eKasy (HTTP API), .NET knižnica ho nemá. Úložisko, tlačiareň, certifikát, frontu aj spojenie overíte jednotlivými volaniami, pozri Kontrola stavu systému.
Na čo si dať pozor najmä:
| Kontrola | Prečo |
|---|---|
| fronta neodoslaných správ | podnikateľ musí každú dátovú správu odoslať do 96 hodín od prvého pokusu o odoslanie (§ 3 ods. 1 zákona č. 384/2025 Z. z.) |
| identifikačné a autentifikačné údaje | autentifikačné údaje platia 2 roky; na koniec platnosti musí pokladnica upozorniť najneskôr 30 dní vopred (§ 5 ods. 3 písm. q) zákona č. 384/2025 Z. z.) |
| tlačiareň | chýbajúci papier alebo otvorený kryt zastaví predaj |
| úložisko | plné úložisko treba vymeniť, obsluha má byť upozornená vopred (nižšie) |
| spojenie so systémom eKasa | bez spojenia sa doklady hromadia vo fronte |
Upozornenie na dochádzajúcu kapacitu úložiska je povinné. Finančná správa na stránke Výrobcovia eKasy uvádza, že úložisko sa zaplní približne za 2 až 6 rokov, potom ho treba vymeniť a pokladnica musí na dochádzajúcu kapacitu upozorniť vopred. Pri integrácii cez HTTP API alebo knižnicu je to úloha vášho softvéru.
Jednotlivé kontroly a ich údaje popisuje Kontrola stavu systému. Pri .NET knižnici voláte zodpovedajúce metódy klienta, ako uvádza ten istý článok.
Ideálna integrácia
Ideálna integrácia pridáva evidenciu paragónov a registráciu polohy.
Evidencia paragónov
Ak pokladnica nefunguje, obsluha vypisuje papierové paragóny a do 10 dní po obnovení prevádzky pokladnice ich musí dodatočne zaevidovať (§ 11 ods. 3 zákona č. 384/2025 Z. z.). Porucha môže postihnúť každého podnikateľa, preto by váš softvér mal vedieť zaevidovať paragón s dátumom a časom jeho vyhotovenia a číslom paragónu. Postup je v článku Typy dokladov.
Registrácia polohy
Prenosná pokladnica, napríklad na trhoch, v taxíku alebo pri predaji z auta, musí mať zaregistrovanú polohu, kde predáva. Polohu treba zaregistrovať pred začiatkom predaja na novom mieste (§ 7 ods. 8 zákona č. 384/2025 Z. z.). Ak váš softvér beží na prenosnej pokladnici, u zákazníka alebo vo vašej vlastnej prevádzke, obsluha musí polohu vedieť zadať priamo v ňom. Pozri Registrácia polohy.
Voliteľné funkcie
Tieto funkcie pridajte podľa toho, čo potrebujú vaši zákazníci alebo vaša vlastná prevádzka:
- Úhrada faktúry: ak podnikateľ prijíma platby faktúr v hotovosti alebo kartou na predajnom mieste, musí ich zaevidovať ako doklad úhrady faktúry, nie ako bežný predaj. Pozri Typy dokladov.
- Vloženie inicializačného balíka z vášho softvéru (identifikačné údaje cez
POST /api/v1/identities, autentifikačné údaje cezPOST /api/v1/certificates). Podnikateľ potom nemusí otvárať webové rozhranie eKasy. - Nastavenia eKasy z vášho softvéru cez
GETaPUT /api/v1/settings. - Nefiškálny doklad: objednávka, účet pred zaplatením alebo iný text na tlačiarni.
- Kópia a vyhľadanie dokladu.
- QR platby bez platobného terminálu.
- Peňažná zásuvka otváraná cez eKasu.