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 .NETResponse.Data.Id) je unikátny identifikátor dokladu pridelený systémom eKasa,request.data.okp(v .NETRequest.Data.OKP) je overovací kód podnikateľa (OKP), ktorý eKasa vypočíta ešte pred odoslaním,isSuccessfulhovorí, 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.