# Ako funguje eKasa

> Fiškalizácia na Slovensku v kocke: systém eKasa finančnej správy, pokladničný program eKasa klient, úložisko CHDÚ a čo z toho rieši váš softvér.

Zdroj: https://ekasa.ninedigit.sk/docs/how-it-works

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](https://www.slov-lex.sk/ezbierky/pravne-predpisy/SK/ZZ/2025/384/).

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

```mermaid
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.

**HTTP API:**

```http
POST http://localhost:3010/api/v1/requests/receipts/cash_register
Content-Type: application/json
```

```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 } ]
    }
  }
}
```

**.NET knižnica:**

```csharp
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:

**HTTP API:**

```json
{
  "request": { "data": { "receiptNumber": 2, "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0" } },
  "response": { "data": { "id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A" } },
  "isSuccessful": true
}
```

**.NET knižnica:**

```csharp
// 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í.

```mermaid
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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1)). Preto sa oplatí stav fronty sledovať, ako popisuje článok [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status).

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:

```mermaid
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](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections).

## 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](https://ekasa.ninedigit.sk/docs/environment-setup).

## Kam ďalej

- [Úložisko a zostavy](https://ekasa.ninedigit.sk/docs/storage-and-hardware): Ktoré úložisko CHDÚ zvoliť a ako zapojiť počítač, tablet či terminál.
- [Príprava prostredia](https://ekasa.ninedigit.sk/docs/environment-setup): Integračné prostredie, testovacie úložisko a inštalácia eKasy.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Všetky typy dokladov, položky, platby a výsledok registrácie.

Skratky ako CHDÚ, OKP alebo PKP vysvetľuje [Slovník pojmov](https://ekasa.ninedigit.sk/docs/glossary).
