Ako funguje eKasa

Integrujem cez

Skôr než začnete písať kód, oplatí sa pochopiť, kto sa na vyhotovení dokladu podieľa a za čo zodpovedá. Tento článok to vysvetľuje bez technických podrobností. Tie nájdete v ďalších článkoch.

Fiškalizácia na Slovensku v skratke

Každú tržbu v hotovosti aj kartou musí podnikateľ zaevidovať v online registračnej pokladnici (ORP). Tá každý doklad v momente predaja odošle do systému eKasa Finančnej správy SR. Systém eKasa doklad prijme a pridelí mu unikátny identifikátor (UID), ktorý je na vytlačenom doklade. Pravidlá určuje zákon č. 384/2025 Z. z. o evidencii tržieb.

Len softvér certifikovaný finančnou správou, takzvaný pokladničný program eKasa klient (PPEKK), smie:

  • komunikovať so systémom eKasa,
  • zapisovať do chráneného dátového úložiska (CHDÚ), z ktorého sa údaje nedajú zmazať ani zmeniť,
  • vyhotoviť a vytlačiť pokladničný doklad.

Váš pokladničný softvér preto doklad sám nevyhotovuje, netlačí ani neodosiela do systému eKasa. Robí to za neho certifikovaný program.

Knižnica aj služba: vyberte si technológiu

Certifikovaný program eKasa od Nine Digit vydávame v dvoch podobách:

  • ako .NET knižnicu (NuGet balík), ktorú si pridáte priamo do svojej .NET aplikácie,
  • ako HTTP API službu, ktorá túto knižnicu obaľuje a beží na Windows, macOS, Linuxe aj Androide.

Vďaka API službe nie ste viazaní na .NET: s eKasou komunikujete cez HTTP a JSON z akéhokoľvek programovacieho jazyka a prostredia, napríklad z PHP, Javy, JavaScriptu alebo Pythonu. Obe podoby robia to isté a tento článok platí pre obe.

Kto sa na doklade podieľa

sequenceDiagram
    autonumber
    participant S as Váš softvér
    participant K as eKasa
    participant C as Úložisko CHDÚ
    participant F as Systém eKasa
    participant D as Doklad
    S->>K: údaje o predaji
    K->>C: zápis dokladu
    K->>F: odoslanie dokladu
    F-->>K: unikátny identifikátor
    K->>C: zápis odpovede
    K->>D: tlač, PDF alebo e-mail
    K-->>S: výsledok evidencie

Váš softvér komunikuje len s eKasou: pošle jej údaje o predaji (1) a dostane výsledok evidencie (7). K úložisku, tlačiarni ani k systému eKasa sa priamo nepripája, všetko medzi tým robí eKasa. Do úložiska zapisuje každý krok: odosielaný doklad (2), odpoveď systému eKasa (5) a pri tlači cez úložisko aj tlačový výstup.

Kto Čo robí
Váš softvér (v dokumentácii nadradená aplikácia) Predáva: zostaví položky, ceny, sadzby DPH a platby a pošle doklad eKase. Zobrazí výsledok obsluhe.
eKasa od Nine Digit (PPEKK) Doklad overí, vypočíta DPH, zapíše ho do úložiska, odošle do systému eKasa a vyhotoví ho v papierovej alebo elektronickej podobe.
Úložisko CHDÚ Uchováva údaje podnikateľa (identifikačné a autentifikačné údaje) a záznam každej odoslanej dátovej správy.
Systém eKasa (Finančná správa SR) Prijme doklad a pridelí mu unikátny identifikátor.

Váš softvér teda nemusí riešiť komunikáciu s finančnou správou, podpisovanie, zápis do úložiska ani rozloženie tlače. Stačí mu poslať eKase údaje o predaji a spracovať odpoveď.

Čo sa stane, keď pošlete doklad

Takto vyzerá zjednodušená požiadavka: predaj dvoch kusov tovaru so zľavou, zaplatený kartou.

POST http://localhost:3010/api/v1/requests/receipts/cash_register
Content-Type: application/json
{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        { "type": "positive", "name": "Coca Cola", "quantity": { "amount": 2, "unit": "ks" }, "unitPrice": 1.99, "price": 3.98, "vatRate": 23 },
        { "type": "discount", "name": "Vernostná zľava", "quantity": { "amount": 1 }, "unitPrice": -1.00, "price": -1.00, "vatRate": 23 }
      ],
      "payments": [ { "name": "Platobná karta", "amount": 2.98 } ]
    }
  }
}
var items = new ReceiptItems
{
    new ReceiptItem(ReceiptItemType.Positive, "Coca Cola", 1.99m, new Quantity(2, "ks"), 23m),
    new ReceiptItem(ReceiptItemType.Discount, "Vernostná zľava", -1.00m, 1, 23m)
};

var receipt = new CashRegisterReceipt("88812345678900001", items)
{
    Payments = new ReceiptPayments { new ReceiptPayment("Platobná karta", 2.98m) }
};

RegisterReceiptResult result = await client.RegisterReceiptAsync(
    new RegisterCashRegisterReceiptRequest(receipt),
    RegisterReceiptPrintContext.CreatePos(),
    cancellationToken);

eKasa najprv overí údaje (povinné polia, súčty, pravidlá finančnej správy), vypočíta obraty v jednotlivých sadzbách DPH a overovací kód podnikateľa. Potom postupuje podľa krokov v diagrame vyššie: zapíše doklad do úložiska, odošle ho do systému eKasa, zapíše odpoveď, vyhotoví doklad a vráti vášmu softvéru výsledok.

Pri elektronickom doklade môže eKasa iba pripraviť PDF a jeho doručenie zákazníkovi, napríklad e-mailom alebo v aplikácii, nechať na váš softvér. Vyhotovenie a tlač dokladu však ostávajú vždy na eKase.

Vo výsledku vás zaujímajú najmä tri polia:

{
  "request": { "data": { "receiptNumber": 2, "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0" } },
  "response": { "data": { "id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A" } },
  "isSuccessful": true
}
// unikátny identifikátor, napr. O-7DBCDA8A56EE426DBCDA8A56EE426D1A
// (null, kým doklad nie je zaevidovaný online)
EKasaReceiptId? id = result.Response?.Data.Id;

// overovací kód podnikateľa, napr. 04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0
OKP okp = result.Request.Data.OKP;

// true, null alebo false
bool? isSuccessful = result.IsSuccessful;
  • response.data.id (v .NET Response.Data.Id) je unikátny identifikátor dokladu pridelený systémom eKasa,
  • request.data.okp (v .NET Request.Data.OKP) je overovací kód podnikateľa (OKP), ktorý eKasa vypočíta ešte pred odoslaním,
  • isSuccessful hovorí, ako registrácia dopadla (pozri nižšie).

Keď nie je internet

Ak systém eKasa nie je dostupný, predaj sa nezastaví. eKasa doklad zaregistruje v offline režime:

  • doklad vždy vytlačí na papier, aj keď ste žiadali PDF alebo e-mail,
  • namiesto unikátneho identifikátora je na doklade overovací kód podnikateľa (OKP),
  • dátovú správu si uloží do fronty neodoslaných správ a odošle ju sama, hneď ako sa spojenie obnoví.
sequenceDiagram
    participant S as Váš softvér
    participant K as eKasa
    participant F as Systém eKasa
    S->>K: doklad
    K-xF: odoslanie zlyhá (bez internetu)
    Note over K: vytlačí doklad s OKP,<br/>dátovú správu uloží do fronty
    K-->>S: isSuccessful: null
    Note over K,F: spojenie sa obnoví
    K->>F: dátová správa z fronty
    F-->>K: unikátny identifikátor

Podnikateľ musí zabezpečiť, aby sa každá dátová správa dostala do systému eKasa do 96 hodín od prvého pokusu o jej odoslanie (§ 3 ods. 1 zákona č. 384/2025 Z. z.). Preto sa oplatí stav fronty sledovať, ako popisuje článok Kontrola stavu systému.

Pole isSuccessful tak môže mať tri hodnoty:

isSuccessful Čo sa stalo Identifikátor dokladu
true doklad je zaregistrovaný online response.data.id
null doklad je zaregistrovaný offline a čaká vo fronte request.data.okp
false systém eKasa doklad odmietol podrobnosti v poli error

Životný cyklus dokladu

Celá cesta dokladu od požiadavky po vyhotovenie, aj s výsledkom, ktorý dostane váš softvér:

stateDiagram-v2
    state "Kontrola údajov" as check
    state "Zápis do CHDÚ" as stored
    state "Odoslanie do systému eKasa" as sent
    state "Zaevidovaný online" as online
    state "Vo fronte (offline)" as queued
    state "Odmietnutý" as rejected
    state "Vyhotovený" as issued
    [*] --> check: váš softvér pošle doklad
    check --> [*]: chyba validácie, nič sa neuloží
    check --> stored
    stored --> sent
    sent --> online: isSuccessful true
    sent --> queued: bez odpovede, isSuccessful null
    sent --> rejected: chyba, isSuccessful false
    online --> issued: papier, PDF alebo e-mail
    queued --> issued: papier s OKP
    queued --> online: fronta odošle správu do 96 h
    rejected --> [*]
    issued --> [*]

Chybné údaje eKasa odmietne ešte pred zápisom do úložiska, váš softvér ich môže opraviť a poslať znova. Doklad zapísaný v CHDÚ už späť vziať nejde: ak bol vystavený omylom, stornujte ho.

Integračné a produkčné prostredie

Finančná správa prevádzkuje systém eKasa v dvoch prostrediach. Integračné slúži na vývoj a testovanie s fiktívnym podnikateľom, tržby v ňom sa nepočítajú. Produkčné je ostré prostredie skutočných podnikateľov. Na začiatku vývoja budete pracovať v integračnom prostredí, často aj bez fyzického úložiska. Ako na to, popisuje Príprava prostredia.

Kam ďalej

Skratky ako CHDÚ, OKP alebo PKP vysvetľuje Slovník pojmov.

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.