Rozsah integrácie

Integrujem cez

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.

  1. externalId pri 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.
  2. Registrácia dokladu pri predaji, vrátení tovaru aj oprave. Položky, platby a typy položiek popisuje článok Registrácia dokladu.
  3. 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ľa error.
  4. 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.
  5. 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 cez POST /api/v1/certificates). Podnikateľ potom nemusí otvárať webové rozhranie eKasy.
  • Nastavenia eKasy z vášho softvéru cez GET a PUT /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.

Kam ďalej

Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.