# Nine Digit eKasa – dokumentácia pre integrátorov
> Celá dokumentácia eKasy (HTTP API a .NET knižnica) v jednom súbore pre AI asistentov.
# Dokumentácia pre integrátorov
> Ako napojiť pokladničný softvér na eKasu od Nine Digit cez HTTP API alebo .NET knižnicu: príprava prostredia, registrácia dokladov a ďalšie funkcie.
Zdroj: https://ekasa.ninedigit.sk/docs
Nine Digit eKasa je pokladničný program eKasa klient (PPEKK) certifikovaný Finančnou správou SR.
Váš pokladničný softvér mu pošle doklad a eKasa sa postará o zvyšok: zaregistruje ho v systéme eKasa,
uloží do chráneného dátového úložiska (CHDÚ) a vytlačí ho.
Táto dokumentácia je pre programátorov, ktorí eKasu napájajú na vlastný softvér, či už ho ponúkajú ďalším
podnikateľom, alebo ho vyvíjajú pre vlastnú prevádzku. Prevedie vás od prípravy
prostredia cez prvý zaregistrovaný doklad až po ďalšie funkcie, ako sú QR platby alebo tlač nefiškálnych dokladov.
## Dva spôsoby integrácie
- **HTTP API**: eKasa beží ako služba na počítači (Windows, macOS, Linux) alebo v zariadení s Androidom
a váš softvér s ňou komunikuje cez HTTP a JSON, v akomkoľvek programovacom jazyku.
- **.NET knižnica**: eKasa je súčasťou vašej aplikácie ako NuGet balík (.NET Standard 2.0, .NET 6, .NET 9 a .NET 10).
Postup pre jednotlivé funkcie je v oboch prípadoch rovnaký, líši sa len spôsob volania. V článkoch si ho
vyberiete prepínačom **Integrujem cez** vpravo hore (na mobile pod nadpisom).
## Ako postupovať
- [Pochopte, ako eKasa funguje](https://ekasa.ninedigit.sk/docs/how-it-works): Kto sa podieľa na doklade, čo rieši eKasa a čo váš softvér.
- [Vyberte spôsob integrácie](https://ekasa.ninedigit.sk/docs/integration-options): HTTP API pre akýkoľvek jazyk alebo .NET knižnica priamo vo vašej aplikácii.
- [Pripravte si prostredie](https://ekasa.ninedigit.sk/docs/environment-setup): Integračné prostredie, testovacie úložisko a inštalácia eKasy.
- [Zaregistrujte prvý doklad](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a odpoveď systému eKasa.
- [Kontrolujte stav systému](https://ekasa.ninedigit.sk/docs/status): Úložisko, autentifikačné údaje, tlačiareň a spojenie so systémom eKasa.
## Ďalšie funkcie
- [QR platby](https://ekasa.ninedigit.sk/docs/qr-payments): Bezhotovostná platba cez QR kód s potvrdením úhrady.
- [Nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt): Objednávkové bony, štatistiky a iné texty na tlačiarni eKasy.
- [Registrácia polohy](https://ekasa.ninedigit.sk/docs/location-registration): Pre prenosné pokladnice, ktoré menia miesto predaja.
## Pomoc
- [Časté otázky](https://ekasa.ninedigit.sk/docs/faq): Odpovede na otázky, ktoré od integrátorov dostávame najčastejšie.
- [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes): Význam chýb, ktoré vracia HTTP API.
- [História zmien](https://ekasa.ninedigit.sk/historia-zmien): Čo prinášajú jednotlivé verzie a čo zmeniť pri prechode na novú.
---
# 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, 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).
---
# Úložisko CHDÚ a hardvérové zostavy
> Ktoré chránené dátové úložisko (CHDÚ) zvoliť, na ktorých systémoch funguje a ako vyzerá zostava s počítačom, Android tabletom a platobným terminálom.
Zdroj: https://ekasa.ninedigit.sk/docs/storage-and-hardware
Každá online registračná pokladnica potrebuje chránené dátové úložisko (CHDÚ). Ktoré zvolíte, závisí od toho,
kde bude predaj prebiehať: na počítači, na vlastnom zariadení s Androidom alebo na platobnom termináli.
Na vývoj žiadny hardvér nepotrebujete.
## Modely úložiska
| Úložisko | Čo to je | Kde sa používa |
|---|---|---|
| **CHDU Lite** | Externé zariadenie pripojené k počítaču alebo tabletu. Pripája sa k nemu aj tlačiareň. | počítač (Windows, macOS, Linux), Android tablet alebo kiosk |
| **SwissBit** | MicroSD karta vo vnútri platobného terminálu, zvonku ju nevidno. | len certifikované platobné terminály |
| **CHDU-SK** | Predchodca CHDU Lite. Podporujú ho aj najnovšie verzie eKasy. | rovnako ako CHDU Lite |
| **In-Memory** | Simulované úložisko v aplikácii, bez hardvéru. Doklady „tlačí“ do PDF. | vývoj a testovanie v integračnom prostredí, na všetkých platformách |
[Obrázok: CHDU Lite: čierne zariadenie s káblom, vo verzii s 25-pinovým a 9-pinovým konektorom pre tlačiareň]
CHDU Lite (verzia s 25-pinovým a 9-pinovým konektorom)
[Obrázok: Karta microSD SwissBit, ktorá sa vkladá do platobného terminálu]
SwissBit, microSD karta do platobného terminálu (foto: Swissbit AG)
Úložisko SwissBit je certifikované len pre konkrétne modely platobných terminálov: **Sunmi P3 MIX, Sunmi P3h Dual,
Ingenico DX4000, Ingenico DX8000 a PAX A920Pro**. Na vlastnom Android tablete, kiosku či inom zariadení ho preto použiť
nemožno, pre takéto zariadenia je určené CHDU Lite.
## Kompatibilita
| | CHDU Lite | CHDU-SK | SwissBit | In-Memory |
|---|:---:|:---:|:---:|:---:|
| Windows | áno | áno | nie | áno |
| macOS | áno | áno | nie | áno |
| Linux | áno | áno | nie | áno |
| Android tablet alebo kiosk | áno | áno | nie | áno |
| Certifikovaný platobný terminál | nie | nie | áno | áno |
## Ktoré úložisko zvoliť
```mermaid
flowchart TD
A{Vývoj alebo ostrá prevádzka?} -->|vývoj a testovanie| D[In-Memory bez hardvéru]
A -->|ostrá prevádzka| E{Na akom zariadení?}
E -->|platobný terminál| B[SwissBit microSD v termináli]
E -->|počítač, vlastný tablet alebo kiosk| C[CHDU Lite]
```
- **Platobný terminál:** ideálne SwissBit. Úložisko je ukryté v termináli a predavač pracuje len s jedným zariadením.
- **Počítač, tablet, kiosk:** CHDU Lite.
- **Vývoj:** začnite s In-Memory. Pred nasadením odporúčame integráciu vyskúšať aj so skutočným úložiskom,
napríklad kvôli papierovej tlači.
## Zostavy
### Počítač
eKasa beží ako služba na počítači s Windows, macOS alebo Linuxom (alebo ako súčasť vašej .NET aplikácie).
CHDU Lite sa k počítaču pripája USB káblom a **tlačiareň sa pripája k úložisku**, nie priamo k počítaču.
Tlač tak vždy ide cez CHDÚ. Staršie CHDU-SK sa zapája rovnako.
**Váš softvér**: na počítači, v sieti alebo v cloude
→ HTTP
**eKasa**: služba na počítači
→ USB
**CHDU Lite**: úložisko
→ sériový kábel
**Tlačiareň**: na doklady
Tlačiareň musí mať sériové rozhranie (9- alebo 25-pinový konektor), podporovať príkazy ESC/POS a slovenskú
diakritiku. Tieto požiadavky spĺňa väčšina tlačiarní na doklady.
Váš softvér môže bežať na tom istom počítači, inde v lokálnej sieti alebo v cloude či prehliadači. Ako sa k eKase
pripojiť v jednotlivých prípadoch, popisuje [Pripojenie a zabezpečenie](https://ekasa.ninedigit.sk/docs/security).
#### Ovládač USB vo Windows
Úložisko sa v počítači ohlási ako sériový port. Vo Windows ho v Správcovi zariadení (Device Manager) nájdete
v skupine **Porty (COM a LPT)**. Ovládač Windows zvyčajne nainštaluje sám, inštalátory eKasy ho neobsahujú.
Ak sa úložisko ako COM port nezobrazí, nainštalujte ovládač výrobcu čipu:
- **CHDU-SK** používa prevodník Silicon Labs CP210x: ovládač
[USB to UART Bridge VCP Drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
- **CHDU Lite** sa ohlási ako virtuálny COM port STM32. Vo Windows 10 a 11 používa vstavaný ovládač Windows,
ovládač výrobcu [STSW-STM32102](https://www.st.com/en/development-tools/stsw-stm32102.html) je podľa
STMicroelectronics určený len pre staršie verzie Windows (7, 8.x).
### Android tablet alebo kiosk
eKasa beží ako aplikácia v zariadení s Androidom. Úložisko (CHDU Lite alebo CHDU-SK) sa k nemu pripája USB káblom
a tlačiareň k úložisku, presne ako pri počítači: zariadenie – CHDÚ – tlačiareň.
**Váš softvér**: v zariadení alebo v sieti
→ HTTP
**eKasa**: aplikácia pre Android
→ USB
**CHDU Lite**: úložisko
→ sériový kábel
**Tlačiareň**: na doklady
### Platobný terminál
Platobný terminál je iný: má vstavanú tlačiareň a slot na microSD kartu, do ktorého sa vkladá úložisko SwissBit.
eKasa beží ako aplikácia priamo v termináli a doklad sa tlačí na jeho vstavanej tlačiarni.
**Váš softvér**: v termináli alebo v sieti
→ HTTP
**eKasa**: aplikácia v termináli
→ vo vnútri
**SwissBit**: microSD v termináli
→ tlač
**Vstavaná tlačiareň**: alebo USB tlačiareň
Namiesto vstavanej tlačiarne môžete k terminálu pripojiť **externú tlačiareň cez USB**. Musí podporovať príkazy
ESC/POS a voči terminálu sa ohlásiť ako tlačiareň (USB trieda tlačiarne).
## Kam ďalej
- [Príprava prostredia](https://ekasa.ninedigit.sk/docs/environment-setup): Integračné prostredie, In-Memory úložisko a inštalácia eKasy.
- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Požiadavky a inštalácia služby na počítači.
- [Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info): Šírka riadku a pripojenie tlačiarne, ktorú eKasa používa.
---
# Možnosti integrácie
> HTTP API alebo .NET knižnica: ako sa líšia, kedy zvoliť ktorú možnosť, podporované platformy a verzie .NET a vzorové projekty.
Zdroj: https://ekasa.ninedigit.sk/docs/integration-options
eKasu môžete do svojho softvéru zapojiť dvoma spôsobmi: cez **HTTP API** alebo ako **.NET knižnicu**. Obe používajú
rovnaký certifikovaný program, takže doklady, tlač aj výsledky sú rovnaké. Líšia sa tým, kde eKasa beží a ako ju voláte.
Odporúčame [HTTP API](#kedy-zvoliť-http-api).
## Porovnanie
| | HTTP API | .NET knižnica |
|---|---|---|
| **Programovací jazyk** | akýkoľvek (PHP, Java, JavaScript, Python, C#…) | .NET (C#, VB.NET, F#) |
| **Platformy** | Windows, macOS, Linux, Android | Windows, macOS, Linux |
| **Kde eKasa beží** | ako samostatná služba (na Androide aplikácia), váš softvér ju volá cez sieť | priamo vo vašej aplikácii |
| **Aktualizácia eKasy** | nainštalujete novú verziu služby, váš softvér meniť netreba | vydáte novú verziu svojej aplikácie s novším NuGet balíkom |
| **Viac aplikácií na jednom mieste** | všetky môžu volať tú istú službu | úložisko CHDÚ smie používať len jeden proces |
| **Softvér v cloude alebo prehliadači** | áno, cez [Expose](https://ekasa.ninedigit.sk/docs/security#expose) zabudované v eKase, VPN alebo inú reverse proxy (pozri [Prístup z internetu](https://ekasa.ninedigit.sk/docs/security#pr%C3%ADstup-z-internetu)) | nie, aplikácia musí bežať pri úložisku |
| **Nastavenia a inicializačný balík** | webové rozhranie služby (WebAdmin) | aplikácia Portos eKasa Servis (Windows) alebo vlastné rozhranie |
## Kedy zvoliť HTTP API
**Odporúčame HTTP API**, aj keď je váš softvér napísaný v .NET. eKasa beží ako samostatná služba vedľa vášho
softvéru, takže:
- **Menej zodpovednosti na vašej strane.** Úložisko CHDÚ, tlač, offline frontu a aktualizácie eKasy spravuje služba,
nie vaša aplikácia.
- **Oddelený beh.** eKasa má vlastné behové prostredie a proces. Pád alebo aktualizácia vašej aplikácie ju neovplyvní
a naopak.
- **Jednoduchšia podpora.** Hranica medzi vaším softvérom a eKasou je jasná: požiadavka a odpoveď. Logy a stav
služby sú vo webovom rozhraní, takže problém rýchlo spoločne určíme.
- **Nezávislé aktualizácie.** eKasu aktualizujete bez novej verzie svojej aplikácie.
- **Všetky platformy a nasadenia.** Funguje na Androide (tablet, kiosk, platobný terminál), pre softvér v cloude,
v prehliadači či na inom zariadení v sieti a pre viac aplikácií na jednom mieste.
Pre PHP je k dispozícii otvorená knižnica klienta HTTP API pod licenciou MIT
([Packagist](https://packagist.org/packages/ninedigit/ekasa-clientphp), [GitHub](https://github.com/ninedigit/ekasa-clientphp)).
Funguje pri lokálnom spojení aj cez Expose.
## Kedy zvoliť .NET knižnicu
Knižnicu zvoľte, ak vyvíjate desktopovú aplikáciu v .NET a samostatnú službu na mieste predaja nainštalovať
a spravovať nemôžete alebo nechcete. eKasa potom beží vo vašom procese a o jej beh, aktualizácie a prístup
k úložisku sa staráte vy.
Knižnicu `NineDigit.eKasa` nájdete na [nuget.org](https://www.nuget.org/packages/NineDigit.eKasa). Je zostavená pre
.NET Standard 2.0, .NET 6, .NET 9 a .NET 10, funguje teda aj v .NET Framework 4.6.1 a novšom (odporúčame 4.7.2).
Knižnica komunikuje s úložiskom CHDÚ výhradne. Vaša aplikácia preto má mať **jednu inštanciu klienta**
počas celého behu a úložisko nesmie súčasne používať žiadny iný proces. Podrobnosti sú v článku
[Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation).
## Vzorové projekty
- [.NET knižnica](https://github.com/ninedigit/ninedigit-ekasa-quickstart): Projekt ninedigit-ekasa-quickstart s ukážkami pre .NET aj .NET Framework.
- [PHP klient](https://github.com/ninedigit/ekasa-clientphp): Knižnica ekasa-clientphp pre HTTP API, lokálne aj cez Expose.
## Kam ďalej
- [Príprava prostredia](https://ekasa.ninedigit.sk/docs/environment-setup): Integračné prostredie, In-Memory úložisko a inštalácia eKasy.
- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Požiadavky, inštalácia služby a prvé volanie.
- [.NET knižnica](https://ekasa.ninedigit.sk/docs/dotnet): Požiadavky, NuGet balíky a vytvorenie klienta.
---
# Príprava prostredia
> Ako rozbehnúť eKasu na vývoj: integračné prostredie, In-Memory úložisko bez hardvéru, test so skutočným úložiskom a tlačiarňou, inicializačný balík a Android.
Zdroj: https://ekasa.ninedigit.sk/docs/environment-setup
Na začiatku vývoja nepotrebujete žiadny hardvér. eKasu nainštalujete, prepnete do integračného prostredia
s úložiskom In-Memory a doklady sa budú „tlačiť“ do PDF. So skutočným úložiskom a tlačiarňou integráciu
vyskúšate až pred nasadením.
## Integračné a produkčné prostredie
Finančná správa prevádzkuje systém eKasa v dvoch prostrediach:
| | Integračné | Produkčné |
|---|---|---|
| **Na čo slúži** | vývoj a testovanie | ostrá prevádzka |
| **Podnikateľ** | fiktívny, so sadou údajov od finančnej správy | skutočný, s údajmi z jeho registrácie pokladnice |
| **Tržby** | nepočítajú sa | evidujú sa |
Celý vývoj prebieha v integračnom prostredí. Do produkčného prostredia sa dostane až pokladnica u podnikateľa.
## Rýchly štart bez hardvéru
### 1. Nainštalujte eKasu
- [HTTP API](https://ekasa.ninedigit.sk/na-prevzatie): Služba pre Windows, macOS a Linux, alebo demo verzia pre Android.
- [.NET knižnica](https://www.nuget.org/packages/NineDigit.eKasa): NuGet balík NineDigit.eKasa pridáte priamo do svojho projektu.
Demo verziu pre Android môžete nainštalovať na ľubovoľné zariadenie s Androidom. Funguje len v integračnom prostredí.
### 2. Zapnite In-Memory úložisko a integračné prostredie
**HTTP API:**
Otvorte webové rozhranie služby. Na počítači so službou je na adrese `http://localhost:3010`, na Androide na adrese
zariadenia s portom 3010. Rozhranie je rovnaké na všetkých platformách. V menu **Systém → Nastavenia**:
1. v záložke **Úložisko** zvoľte **Model úložiska: In-Memory**,
2. v záložke **eKasa klient** zvoľte **Prostredie: Integračné**.
**.NET knižnica:**
Pri knižnici sa služba ani jej webové rozhranie neinštalujú. Model úložiska **In-Memory** a **integračné** prostredie
nastavíte v konfigurácii klienta:
- v aplikácii **Portos eKasa Servis** (Windows), ktorá nastavenia uloží do súboru. Vaša aplikácia ho potom načíta,
ako popisuje [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration),
- alebo priamo v kóde:
```csharp
var configuration = new ClientConfiguration
{
Storage = new StorageConfiguration { StorageModel = StorageModel.InMemory },
EKasaClient = new EKasaClientConfiguration { Environment = EKasaEnvironment.Playground }
};
var client = new Client(configuration);
```
In-Memory úložisko má **inicializačný balík už vložený**, nič ďalšie netreba. K počítaču nepripájate úložisko ani tlačiareň.
Údaje drží len v pamäti, takže reštartom služby alebo vašej aplikácie sa všetky zaregistrované doklady vymažú.
### 3. Pošlite prvý doklad
Zaregistrujte doklad podľa článku [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration). In-Memory úložisko ho namiesto
tlače uloží ako PDF súbor. Rovnako uloží aj [nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt). Predvolený priečinok:
| Systém | Priečinok s PDF |
|---|---|
| Windows | `C:\ProgramData\NineDigit\Portos.eKasa\receipts` |
| macOS, Linux | `/etc/NineDigit/Portos.eKasa/receipts` |
Priečinok zmeníte vo webovom rozhraní v nastaveniach v záložke **Tlač**, časť **Elektronický doklad**, pole
**Výstupný adresár**. Pri .NET knižnici je to vlastnosť `Printers.Pdf.OutputDirectory` v konfigurácii klienta.
Vzhľad PDF je takmer totožný s papierovým dokladom, preto si na ňom overíte aj rozloženie vlastných textov.
Na platobnom termináli s Androidom In-Memory úložisko netlačí do PDF, ale na vstavanú tlačiareň terminálu.
Či doklad prijal systém eKasa, overíte na stránke finančnej správy pre integračné prostredie
[iekasa.financnasprava.sk/opd](https://iekasa.financnasprava.sk/opd/#!/check), napríklad naskenovaním QR kódu z dokladu.
## Test so skutočným úložiskom a tlačiarňou
Pred nasadením integráciu vyskúšajte so skutočným úložiskom CHDÚ a tlačiarňou. Až tak overíte papierovú tlač
a situácie, ktoré In-Memory nenasimuluje, napríklad chýbajúci papier alebo otvorený kryt tlačiarne.
1. **Zapojte hardvér**
Úložisko pripojte k počítaču alebo tabletu a tlačiareň k úložisku, nie priamo k počítaču
(pozri [Úložisko a zostavy](https://ekasa.ninedigit.sk/docs/storage-and-hardware)). Vo Windows sa úložisko musí v Správcovi zariadení
zobraziť ako COM port, inak doinštalujte [ovládač USB](https://ekasa.ninedigit.sk/docs/storage-and-hardware#ovladac-usb).
2. **Zvoľte model úložiska**
Vo webovom rozhraní služby alebo v konfigurácii klienta (.NET) podľa pripojeného CHDÚ.
3. **Vložte inicializačný balík**
Do úložiska vložte integračný inicializačný balík, postup je nižšie.
Ako sa pri ktorom úložisku tlačí:
| Úložisko | Výsledok tlače |
|---|---|
| In-Memory | doklady aj nefiškálne doklady do PDF (na termináli na vstavanú tlačiareň) |
| CHDÚ s inicializačným balíkom | doklady aj nefiškálne doklady na tlačiareň |
| CHDÚ bez inicializačného balíka | len nefiškálne doklady na tlačiareň |
Bez inicializačného balíka teda vytlačíte aspoň [nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt), čo stačí na overenie
pripojenia tlačiarne.
## Inicializačný balík
Inicializačný balík sú údaje podnikateľa, ktoré eKasa potrebuje na registráciu dokladov:
- **identifikačné údaje**: XML súbor s údajmi podnikateľa, napríklad názov, adresa sídla a prevádzky,
- **autentifikačné údaje**: XML súbor s podpisovým certifikátom, ktorým eKasa podpisuje doklady, a heslo k nemu.
Platia 2 roky, potom si ich podnikateľ znova stiahne z eKasa zóny na webe finančnej správy.
Vložením balíka sa úložisko **natrvalo** zviaže s prostredím. Úložisko s integračným balíkom (takzvané
**vývojárske úložisko**) zostane navždy len pre integračné prostredie. Úložisko s produkčným balíkom sa navždy zviaže
s daným podnikateľom a produkčným prostredím.
**Integračný balík** s údajmi fiktívneho podnikateľa si stiahnete ako
[ekasa-integracny-balik.zip](https://ekasa.ninedigit.sk/files/ekasa-integracny-balik.zip). Obsahuje všetky tri sady integračného prostredia
(pozri nižšie), každú ako dva XML súbory. Pre vývojárske úložiská sú všetky funkcie eKasy bezplatné.
Balík vložíte vo webovom rozhraní služby: v menu **Subjekty** kliknite na **Nový subjekt**, pretiahnite do okna oba
XML súbory jednej sady, ako heslo zadajte kód pokladnice a uložte. Pri .NET knižnici použijete aplikáciu Portos eKasa
Servis alebo vlastné rozhranie.
**Produkčný balík** si zabezpečuje sám podnikateľ, teda váš zákazník, alebo vy, ak pokladnicu vyvíjate pre vlastnú
prevádzku. Postup:
1. V osobnej internetovej zóne na portáli finančnej správy podá žiadosť o pridelenie kódu pokladnice eKasa.
2. Daňový úrad pridelí kód pokladnice a v **eKasa zóne** sprístupní inicializačný balík.
3. Podnikateľ si balík stiahne. Výsledkom sú dva XML súbory a heslo, ktoré si zvolí pri sťahovaní.
4. Balík vloží do eKasy pred prvým použitím pokladnice.
Celý postup ukazuje oficiálny videonávod finančnej správy:
[Video: Návod, ako si aktivovať novú eKasu (Finančná správa, 2:13)](https://www.youtube.com/watch?v=6g3hSudohPU)
Krok za krokom s obrázkami ho popisuje aj návod [Nová on-line pokladnica](https://docs.portos.sk/ekasa/nova-on-line-pokladnica)
v dokumentácii Portos. Podrobnosti nájdete na stránkach podpory finančnej správy:
[Pridelenie kódu pokladnici eKasa](https://podpora.financnasprava.sk/579037-Pridelenie-k%C3%B3du-pokladnici-eKasa)
a [eKasa zóna na portáli FS](https://podpora.financnasprava.sk/776739-eKasa--z%C3%B3na-na-port%C3%A1li-FS).
### Kódy pokladníc integračného prostredia
Finančná správa poskytuje pre integračné prostredie tieto sady identifikačných a autentifikačných údajov:
| Sada | Kód pokladnice | DIČ |
|---|---|---|
| č. 1 | `88812345678900001` | `1234567890` |
| č. 2 | `88812345604850001` | `1029867938` |
| č. 3 | `88812345606470001` | `1029867938` |
Heslo k autentifikačným údajom je zhodné s kódom pokladnice.
Úložisko je viazané na jedno DIČ. Do jedného úložiska preto môžete vložiť sadu č. 1, do druhého sadu č. 2 alebo č. 3.
Prostredie (integračné alebo produkčné) eKasa určuje automaticky podľa kódu pokladnice: kódy začínajúce na
`888123456` patria integračnému prostrediu, ostatné produkčnému. Sady č. 2 a 3 rozpoznáva eKasa od verzie 8.0.1,
staršie verzie len sadu č. 1.
## Android: inštalácia a diagnostika
Demo verziu pre Android nainštalujete aj cez [adb](https://developer.android.com/tools/adb) z počítača,
ku ktorému je zariadenie pripojené USB káblom:
```bash
# zoznam pripojených zariadení
adb devices
# inštalácia a odinštalovanie (ID zariadenia zo zoznamu)
adb -s install .apk
adb -s uninstall com.ninedigit.ekasa.android
```
Logy eKasy stiahnete na Androide aj na počítači ako ZIP súbor. Vo webovom rozhraní je to v menu **Systém → Údržba**,
riadok **Súbory denníka**, tlačidlo **Archivovať**. Rovnaký súbor vráti aj API:
```http
GET {server_address}/api/v1/logs
```
Ak hľadáte chybu, priložte tento súbor k otázke na našu podporu. Pri .NET knižnici zapisuje logy vaša aplikácia,
pozri [Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging).
## Kam ďalej
- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Požiadavky, inštalácia služby a prvé volanie.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Pred nasadením](https://ekasa.ninedigit.sk/docs/go-live-checklist): Kontrolný zoznam pred ostrou prevádzkou.
---
# Pred nasadením
> Kontrolný zoznam pred ostrou prevádzkou: prostredie a úložisko, inicializačný balík, tlač, spracovanie výsledku, kontrola stavu, QR platby, poloha a zabezpečenie.
Zdroj: https://ekasa.ninedigit.sk/docs/go-live-checklist
Integráciu ste vyvinuli a otestovali v integračnom prostredí. Kým ju nasadíte u podnikateľa, prejdite si tento
zoznam. Každý bod odkazuje na článok, ktorý ho vysvetľuje.
## Prostredie a úložisko
- **Skutočné úložisko namiesto In-Memory.** V ostrej prevádzke beží eKasa s úložiskom CHDÚ (CHDU Lite, CHDU-SK alebo
SwissBit), In-Memory doklady po reštarte zabudne ([Úložisko a zostavy](https://ekasa.ninedigit.sk/docs/storage-and-hardware)).
- **Produkčný inicializačný balík.** V úložisku sú identifikačné a autentifikačné údaje podnikateľa pre jeho
skutočný kód pokladnice, nie integračná sada `888123456…`
([Inicializačný balík](https://ekasa.ninedigit.sk/docs/environment-setup#inicializa%C4%8Dn%C3%BD-bal%C3%ADk)).
- **Prostredie podľa údajov.** Prostredie nechajte určiť automaticky podľa identifikačných údajov, aby sa produkčná
pokladnica neposielala do integračného prostredia
([Chyba v podpise dátovej správy](https://ekasa.ninedigit.sk/docs/troubleshooting/invalid-signature)).
- **Platný certifikát.** Autentifikačné údaje platia 2 roky. Overte, že certifikát je platný a do konca platnosti
zostáva dosť času ([Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status#bl%C3%AD%C5%BEiaca-sa-exspir%C3%A1cia-certifik%C3%A1tu)).
## Doklad a tlač
- **`externalId` pri každom doklade.** Bez neho sa pri strate odpovede ten istý predaj zaeviduje dvakrát
([Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id)).
- **Test tlače na skutočnej tlačiarni.** Vytlačte doklad aj kópiu, skontrolujte diakritiku a rozloženie vlastných
textov ([Kódovanie a špeciálne znaky](https://ekasa.ninedigit.sk/docs/encoding), [Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info)).
- **Zaokrúhľovanie hotovosti.** Pri platbe v hotovosti posielajte `roundingAmount`
([Platby a zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments)).
- **Storno a vrátenie.** Vyskúšajte storno a vrátenie tovaru s odkazom na pôvodný doklad
([Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections)).
## Spracovanie výsledku
- **Tri výsledky registrácie.** Váš softvér rozlišuje `isSuccessful` `true`, `null` (offline) a `false` (odmietnutý)
a obsluhe ukáže, čo sa stalo ([Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result)).
- **Offline doklad neposielajte znova.** Pri `null` je doklad zaevidovaný a vytlačený, eKasa ho odošle sama
([Ako funguje eKasa](https://ekasa.ninedigit.sk/docs/how-it-works#ke%C4%8F-nie-je-internet)).
- **Chyba tlače.** Pri [`-502: PrintReceiptError`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-502-printreceiptererror) je doklad
zaevidovaný: zákazníkovi vytlačte kópiu, prípadne doklad stornujte a vystavte nový.
- **Časový limit vášho softvéru.** Pri vypršaní limitu doklad zopakujte s rovnakým `externalId`, nie ako nový
([Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id#%C4%8Do-ekasa-vr%C3%A1ti)).
## Kontrola stavu
- **Stav pri štarte a pravidelne.** Váš softvér overuje stav eKasy pri spustení a potom pravidelne a obsluhu
upozorní na problém ([Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status)).
- **Fronta neodoslaných správ.** Dátové správy musia odísť do 96 hodín. Obsluha má vedieť, že niečo čaká vo fronte
([Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status#kontrola-obsahu-fronty-neodoslan%C3%BDch-spr%C3%A1v)).
- **Papier a úložisko.** Dochádzajúci papier a zapĺňajúce sa úložisko ukážte obsluhe včas.
## Ak ich používate
- **QR platby.** V nastaveniach je notifikačný účet podnikateľa a váš softvér tlačí oznámenie o nepotvrdení platby
([QR platby](https://ekasa.ninedigit.sk/docs/qr-payments)).
- **Prenosná pokladnica.** Pred začiatkom predaja zaregistrujte polohu ([Registrácia polohy](https://ekasa.ninedigit.sk/docs/location-registration)).
- **Prístup zo siete.** Ak sa k eKase pripájate z inej stanice alebo z cloudu, zapnite prihlásenie a HTTPS alebo
Expose ([Pripojenie a zabezpečenie](https://ekasa.ninedigit.sk/docs/security)).
## Po nasadení
- **Aktualizácie.** Sledujte [históriu zmien](https://ekasa.ninedigit.sk/historia-zmien) a eKasu aktualizujte, opravy sa týkajú aj komunikácie
so systémom eKasa.
- **Logy pri probléme.** Ak niečo nefunguje, priložte k otázke logy služby ([Riešenie problémov](https://ekasa.ninedigit.sk/docs/troubleshooting)).
---
# Vývoj s AI
> Ako použiť dokumentáciu eKasy s AI asistentmi: stránky v Markdowne, llms.txt a llms-full.txt, špecifikácia OpenAPI a odporúčania pre zadanie.
Zdroj: https://ekasa.ninedigit.sk/docs/build-with-ai
Integráciu s eKasou môžete písať s pomocou AI asistenta, napríklad Claude, ChatGPT, GitHub Copilot alebo Cursor.
Asistent však o eKase vie len to, čo mu dáte. Dokumentácia je preto dostupná aj v čistom texte, ktorý mu jednoducho
vložíte.
## Dokumentácia pre asistenta
| Čo | Adresa | Kedy |
|---|---|---|
| jedna stránka | ikonka kopírovania vedľa prepínača jazyka, alebo adresa s príponou `.md`, napr. [`/docs/receipt-registration.md`](https://ekasa.ninedigit.sk/docs/receipt-registration.md) | otázka na konkrétnu tému |
| prehľad | [`/llms.txt`](https://ekasa.ninedigit.sk/llms.txt) | asistent si sám vyberie, ktoré stránky potrebuje |
| celá dokumentácia | [`/llms-full.txt`](https://ekasa.ninedigit.sk/llms-full.txt) | väčšia úloha, napríklad celá integrácia |
| popis API | `http://localhost:3010/swagger/v1/swagger.json` v nainštalovanej službe | presné názvy polí a typov |
Markdown verzie majú absolútne odkazy, pri variantoch označenie HTTP API alebo .NET knižnica a namiesto obrázkov
ich popis.
1. **Vyberte zdroj**
Pre jednu tému skopírujte stránku, pre celú integráciu priložte `llms-full.txt` alebo jeho adresu.
2. **Pridajte kontext**
Napíšte jazyk a prostredie vášho softvéru a či použijete HTTP API alebo .NET knižnicu.
3. **Overte výsledok**
Kód vyskúšajte v integračnom prostredí s úložiskom In-Memory, nie na ostrej pokladnici.
## Príklad zadania
**HTTP API:**
```text
Pracujem na pokladničnom softvéri v PHP 8.3 pre slovenských podnikateľov. Tržby treba evidovať podľa slovenského zákona č. 384/2025 Z. z. o evidencii tržieb cez Nine Digit eKasu, certifikovaný pokladničný program eKasa klient. Napájam ju cez HTTP API na http://localhost:3010. Dokumentácia Nine Digit eKasy je na https://ekasa.ninedigit.sk/llms-full.txt (ak ju nevieš načítať, priložím ju).
Napíš funkciu, ktorá zaregistruje pokladničný doklad s položkami a platbami z môjho objektu Order, vyhodnotí isSuccessful (true, null, false) a uloží k objednávke unikátny identifikátor alebo OKP. Chyby spracuj podľa poľa code. Drž sa len toho, čo je v dokumentácii.
```
**.NET knižnica:**
```text
Pracujem na pokladničnom softvéri v C# (.NET 8) pre slovenských podnikateľov. Tržby treba evidovať podľa slovenského zákona č. 384/2025 Z. z. o evidencii tržieb cez Nine Digit eKasu, certifikovaný pokladničný program eKasa klient. Používam ju ako .NET knižnicu z NuGet balíka NineDigit.eKasa. Dokumentácia Nine Digit eKasy je na https://ekasa.ninedigit.sk/llms-full.txt (ak ju nevieš načítať, priložím ju).
Napíš metódu, ktorá zaregistruje pokladničný doklad s položkami a platbami z mojej triedy Order cez client.RegisterReceiptAsync, vyhodnotí IsSuccessful (true, null, false) a uloží k objednávke unikátny identifikátor alebo OKP. Klienta vytvor raz pre celú aplikáciu. Drž sa len toho, čo je v dokumentácii.
```
## Na čo pamätať
- **Kontrolujte, čo asistent napíše.** Za zaevidované tržby zodpovedá podnikateľ a za integráciu vy. Overte hlavne
sadzby DPH, zľavy a vyhodnotenie výsledku.
- **Neposielajte asistentovi skutočné údaje** podnikateľa, autentifikačné údaje ani heslá. Na vývoj stačí
integračný inicializačný balík.
- **Dokumentácia sa vyvíja.** Pri novej verzii eKasy dajte asistentovi aktuálny súbor, nie starú kópiu.
## Kam ďalej
- [Príprava prostredia](https://ekasa.ninedigit.sk/docs/environment-setup): Integračné prostredie a In-Memory úložisko na skúšanie.
- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Čo má váš softvér vedieť.
- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Pravidlá komunikácie a referencia API.
---
# HTTP API
> Inštalácia služby eKasa, podporované systémy, prvé volanie a pravidlá komunikácie: JSON, adresy, stavové kódy a chybové odpovede.
Zdroj: https://ekasa.ninedigit.sk/docs/rest-api
Pri HTTP API beží eKasa ako služba na počítači alebo ako aplikácia na Androide. Váš softvér s ňou komunikuje
cez HTTP a JSON, takže na programovacom jazyku nezáleží. API je rovnaké na všetkých platformách.
## Inštalácia
Inštalátory nájdete na stránke [Na prevzatie](https://ekasa.ninedigit.sk/na-prevzatie). Služba sa po inštalácii spustí sama.
| Systém | Verzia | Inštalácia |
|---|---|---|
| Windows | 10 a novší, 32 aj 64-bit | MSI |
| Windows | 7, 8 a 8.1 | MSI pre staršie systémy |
| macOS | 11 Big Sur a novší, Apple Silicon aj Intel | PKG |
| Linux | x64 (Ubuntu, Debian, Fedora, RHEL…) a ARM64 (Raspberry Pi 3+ s Ubuntu Server) | SH |
| Android | tablet alebo kiosk s Androidom 10 a novším | APK súbor |
| Android | platobný terminál | obchod s aplikáciami výrobcu |
Na platobné terminály sa eKasa neinštaluje z APK súboru, ale z obchodu s aplikáciami, ktorý je v termináli:
na zariadeniach Sunmi zo Sunmi Store, na PAX z MAX Store a na iMin z iMin Store. Terminály Ingenico
sa dodávajú s nainštalovanou eKasou.
Aplikácia obsahuje všetko potrebné, .NET netreba inštalovať zvlášť. Na vývoj stačí In-Memory úložisko bez hardvéru,
ako popisuje [Príprava prostredia](https://ekasa.ninedigit.sk/docs/environment-setup).
## Prvé volanie
Služba počúva na porte **3010**. Či beží, overíte napríklad zistením informácií o produkte:
```bash
curl http://localhost:3010/api/v1/product/info
```
Odpoveď (skrátená):
```json
{
"vendorName": "Nine Digit, s. r. o.",
"api": { "name": "Portos eKasa API", "version": "9.0.7" },
"chdu": { "name": "Memory Record Repository", "version": "1.0" },
"operatingSystem": { "platform": "MacOS", "architecture": "Arm64" }
}
```
Na tej istej adrese je aj webové rozhranie služby (`http://localhost:3010`) s nastaveniami, stavom systému
a formulármi na skúšobnú registráciu dokladu.
[Obrázok: Webové rozhranie služby eKasa: stav systému, úložisko a informácie o pokladničnom programe]
## Pravidlá komunikácie
### Adresa
Adresa každej požiadavky sa skladá z adresy zariadenia, portu a cesty s verziou API:
```text
{server_address}/api/v1/{cesta}
```
`{server_address}` je adresa služby s portom, napríklad `http://localhost:3010`, ak váš softvér beží na tom istom
zariadení. Inak je to IP adresa zariadenia v lokálnej sieti, napríklad `http://192.168.1.20:3010`. Rovnaký zápis
`{server_address}` používajú príklady v celej dokumentácii. Pripojenie z inej siete alebo z internetu popisuje [Pripojenie a zabezpečenie](https://ekasa.ninedigit.sk/docs/security).
### Formát
Požiadavky aj odpovede sú v JSON s kódovaním UTF-8 a názvy vlastností sú v tvare camelCase. Do každej požiadavky
s telom pridajte hlavičky:
```text
Content-Type: application/json; charset=utf-8
Accept: application/json
```
Sumy, ceny a množstvá odporúčame posielať ako reťazce (napríklad `"3.00"`), aby sa pri prevode
nestratila presnosť.
### Stavové kódy
| Kód | Význam |
|---|---|
| `200` | Požiadavka je spracovaná. |
| `202` | Doklad je prijatý, ale ešte nie je zaevidovaný v systéme eKasa, alebo ho systém eKasa odmietol. Výsledok je v tele odpovede. |
| `400` | Požiadavka obsahuje neplatné údaje. |
| `401` | Chýbajú prihlasovacie údaje alebo nie sú správne. |
| `403` | Operáciu nemožno vykonať, napríklad pre stav úložiska alebo pri prístupe z internetu. |
| `404` | Záznam sa nenašiel. |
| `500` | Neočakávaná chyba služby. |
Ako vyhodnotiť výsledok registrácie dokladu (`isSuccessful` je `true`, `null` alebo `false`), popisuje
[Ako funguje eKasa](https://ekasa.ninedigit.sk/docs/how-it-works).
### Chybové odpovede
Pri chybe vráti služba objekt podľa štandardu [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details)
doplnený o číselný kód chyby `code`:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#900-validationerror",
"title": "Validácia zlyhala",
"status": 400,
"code": -900,
"errors": {
"Text": ["Pole 'Text' nesmie byť prázdne."]
},
"instance": "/api/v1/printers/print"
}
```
Nezameňte dve čísla v odpovedi:
| Pole | Čo to je | Hodnoty |
|---|---|---|
| `status` | stavový kód HTTP, rovnaký ako v hlavičke odpovede | kladné: `400`, `403`, `500`… |
| `code` | kód chyby eKasy, ktorý presne určuje príčinu | vždy záporné: `-900`, `-100`… |
`code` je vždy záporný, aby sa nedal pomýliť so stavovým kódom HTTP. Jednému stavu zodpovedá viac kódov chyby,
napríklad `403` môže vzniknúť pre stav úložiska aj pre prístup z internetu. Chybu v kóde preto spracujte podľa
`code`. Zoznam kódov je v článku [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes).
- `title` a texty v `errors` sú určené pre človeka a ich znenie sa môže meniť.
- `errors` je len pri chybe validácie (`-900`). Kľúčom je cesta k vlastnosti, napríklad `Items[0].Name`.
## Referencia API
Všetky endpointy s parametrami, dátovými modelmi, odpoveďami a príkladmi sú v [referencii HTTP API](https://ekasa.ninedigit.sk/docs/rest-api/reference).
Špecifikáciu OpenAPI si stiahnete ako [openapi.json](https://ekasa.ninedigit.sk/openapi.json) a môžete z nej vygenerovať klienta pre svoj jazyk.
Nainštalovaná služba má popis svojej verzie aj priamo na adrese `http://localhost:3010/docs`, špecifikáciu na
`http://localhost:3010/swagger/v1/swagger.json`.
## Kam ďalej
- [Pripojenie a zabezpečenie](https://ekasa.ninedigit.sk/docs/security): Lokálna sieť, internet cez Expose, CORS, prihlásenie a HTTPS.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes): Význam kódov v chybových odpovediach.
---
# Pripojenie a zabezpečenie
> Ako sa k službe eKasa pripojiť z toho istého zariadenia, z lokálnej siete a z internetu cez Expose, a ako nastaviť CORS, prihlásenie a HTTPS.
Zdroj: https://ekasa.ninedigit.sk/docs/security
Spôsob pripojenia k eKase závisí od toho, kde beží váš softvér. Najjednoduchšie je to na tom istom zariadení
a v lokálnej sieti predajne. Z internetu sa k eKase dostanete len cez zabezpečené spojenie.
Článok sa týka HTTP API. .NET knižnica beží priamo vo vašej aplikácii a sieťové spojenie nepoužíva.
## Kde beží váš softvér
| Váš softvér | Adresa eKasy | Šifrovanie |
|---|---|---|
| na tom istom zariadení | `http://localhost:3010` | netreba, komunikácia neopustí zariadenie |
| v lokálnej sieti | `https://ekasa.local:4010` (od verzie 9.1.0) | odporúčame HTTPS ([nižšie](#https-v-lokálnej-sieti)) |
| v cloude alebo inej sieti | adresa Expose | vždy HTTPS |
V lokálnej sieti odporúčame od verzie 9.1.0 komunikovať cez **HTTPS** a pripájať sa podľa mena `ekasa.local`.
Spojenie je šifrované, prihlasovacie údaje sa nedajú odpočúvať a meno platí, aj keď sa IP adresa zariadenia zmení.
Staršie verzie podporujú len HTTP na IP adrese zariadenia, napríklad `http://192.168.1.24:3010`. Zariadeniu vtedy
nastavte pevnú IP adresu (napríklad rezerváciou v routri), inak sa môže po reštarte zmeniť a váš softvér ho nenájde.
## Prístup z internetu
Lokálna komunikácia beží cez HTTP bez šifrovania, preto ju eKasa od verzie 9.0.4 nepovolí z internetu.
Požiadavky prijme len z týchto adries:
- z toho istého zariadenia (`127.0.0.1`, `::1`),
- z privátnych sietí `10.0.0.0/8`, `172.16.0.0/12` a `192.168.0.0/16` a z lokálnych adries IPv6,
- cez službu Expose.
Požiadavku z verejnej IP adresy, napríklad cez presmerovaný port na routri, eKasa odmietne so stavom `403`:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-100-generalerror",
"title": "Prístup bol odmietnutý",
"status": 403,
"code": -100,
"detail": "Prístup zo siete internet (volanie z IP adresy inej ako 127.0.0.1 (localhost) alebo privátnych adries …) je z bezpečnostných dôvodov povolené iba cez zabezpečené spojenie medzi koncovými bodmi. …"
}
```
Znenie poľa `detail` sa môže medzi verziami meniť. Rozpoznajte túto situáciu podľa stavu `403` a kódu `-100`.
Verejná IP adresa, dynamický DNS ani presmerovanie portu preto nie sú vhodným spôsobom vzdialeného prístupu.
Ak váš softvér beží mimo lokálnej siete predajne, máte tri možnosti:
1. **Expose** (odporúčame): je zabudované v eKase, netreba inštalovať nič ďalšie ani otvárať porty
a spojenie je šifrované. Prihlasovacie údaje k Expose sa zadávajú priamo v nastaveniach eKasy.
2. **VPN**: vzdialený server dostane adresu z privátnej siete predajne a eKasa ho berie ako lokálneho klienta.
Hodí sa, ak zákazník VPN už používa, treba prepojiť viac zariadení či celé siete alebo sieť spravuje IT tím.
Nastavenie VPN nie je súčasťou eKasy.
3. **Vlastná aplikácia v sieti predajne** (bridge): beží na tom istom zariadení alebo v tej istej sieti ako eKasa,
volá ju lokálne a s vaším serverom komunikuje vlastným spôsobom. Je to individuálne riešenie, ktoré si
navrhujete, zabezpečujete a prevádzkujete sami. Nine Digit takú aplikáciu neposkytuje.
Použiť môžete aj **vlastnú reverse proxy** pred eKasou. Pred nasadením ju však overte: či eKasa požiadavku pustí,
závisí od konfigurácie proxy a spracovania hlavičiek ako `X-Forwarded-For`.
### Expose
Expose pridelí eKase stálu webovú adresu so šifrovaným spojením HTTPS. eKasa si k službe Expose sama otvorí
spojenie, takže na predajni netreba verejnú IP adresu ani nastavovať router. Požiadavky a odpovede sú rovnaké
ako pri lokálnom spojení, mení sa len adresa:
```text
lokálne: POST http://192.168.1.24:3010/api/v1/requests/receipts/cash_register
cez Expose: POST https://moja-kaviaren.expose.ninedigit.sk/v1/requests/receipts/cash_register
```
Cez Expose je dostupné len API, webové rozhranie nie. Ak máte o Expose záujem, [napíšte nám](https://ekasa.ninedigit.sk/?zaujem=expose#kontakt).
## Aplikácia v prehliadači (CORS)
Ak eKasu volá JavaScript priamo z webovej stránky v prehliadači, prehliadač požiadavku pustí, len ak eKasa
povolí doménu stránky. Povolené domény nastavíte vo webovom rozhraní v menu **Systém → Nastavenia**, záložka
**Ostatné**, časť **CORS**:
| Pole | Čo zadať |
|---|---|
| **Povolené domény** | adresa vašej stránky bez cesty, napríklad `https://pokladna.example.sk` |
| **Sprístupnené hlavičky** | hlavičky odpovede, ktoré má váš JavaScript čítať. `Content-Range` a `Content-Disposition` sú sprístupnené vždy. |
| **Prístup z privátnej siete** | **Povolený**, ak stránka z verejnej adresy volá eKasu na lokálnej adrese. eKasa tak odpovie na predbežnú požiadavku Private Network Access, ktorú posielajú staršie verzie prehliadača Chrome. |
Každú doménu zadajte zvlášť. Zástupný znak `*` (všetky domény) nie je z bezpečnostných dôvodov povolený.
### Chrome a prístup k lokálnej sieti
Od verzie 142 prehliadač Chrome predvolene blokuje stránkam z internetu prístup k lokálnej sieti vrátane
`localhost`. Kým ho používateľ nepovolí, volanie eKasy zlyhá s chybou v konzole prehliadača, napríklad:
```text
Access to XMLHttpRequest at 'http://localhost:3010' from origin 'https://www.example.com' has been blocked
by CORS policy: Permission was denied for this request to access the 'unknown' address space.
```
Nejde o chybu nastavenia CORS v eKase. Pri prvom volaní Chrome zobrazí výzvu na povolenie prístupu k lokálnej
sieti. Pokladník ju musí potvrdiť, prípadne prístup povolí neskôr v nastaveniach stránky v Chrome. Na pokladniciach
s vaším softvérom preto s týmto krokom počítajte pri inštalácii.
Stránka načítaná cez HTTPS môže volať `http://localhost`, nie však HTTP adresu iného zariadenia v sieti. Prehliadač
také volanie zablokuje ako nezabezpečený obsah. V tom prípade použite HTTPS (od verzie 9.1.0) alebo Expose.
## Prihlásenie
Predvolene eKasa prihlásenie nevyžaduje. Ak je služba dostupná z lokálnej siete, odporúčame ho zapnúť.
Vo webovom rozhraní v menu **Systém → Nastavenia**, záložka **Ostatné**, časť **Prihlásenie**, zapnite
**Vyžadovať prihlásenie** a pridajte aspoň jedného používateľa.
Potom posielajte v každej požiadavke hlavičku `Authorization` podľa schémy HTTP Basic: slovo `Basic`, medzera
a reťazec `meno:heslo` zakódovaný v Base64. Pre meno `admin` a heslo `admin`:
```text
Authorization: Basic YWRtaW46YWRtaW4=
```
Bez hlavičky alebo s nesprávnymi údajmi vráti eKasa stav `401`.
Prihlásenie môžete nastaviť aj cez API, v nastaveniach `PUT /api/v1/settings`. Heslo posielate v čitateľnej
podobe. eKasa ho uloží a v odpovediach ho už nevráti: namiesto neho je `"password": null`
a `"hasPassword": true`:
```json
{
"authentication": {
"enabled": true,
"users": [
{ "userName": "admin", "password": "admin" }
]
}
}
```
Telo požiadavky obsahuje celé nastavenia. Najprv ich načítajte cez `GET /api/v1/settings`, zmeňte časť
`authentication` a pošlite späť. Ako sa pri tom správajú maskované heslá a príznaky `hasPassword`, popisuje
[Migrácia na verziu 8](https://ekasa.ninedigit.sk/docs/migration/v8#5-zmeny-v-apiv1settings).
Pri HTTP sa meno a heslo posielajú nešifrovane. V lokálnej sieti ich preto posielajte cez HTTPS.
## HTTPS v lokálnej sieti
Od verzie 9.1.0 vie eKasa okrem HTTP obsluhovať aj HTTPS. Nastavenie je vo webovom rozhraní v záložke
**Ostatné**, časť **Hosting**:
| Nastavenie | Predvolená hodnota | Popis |
|---|---|---|
| **Port (HTTP)** | `3010` | nezabezpečené spojenie |
| **HTTPS → Režim** | Vypnuté (len HTTP) | Zapnuté (HTTP aj HTTPS), Presmerovať HTTP na HTTPS (odpoveď `307`), Len HTTPS (vypnúť HTTP) |
| **Port (HTTPS)** | `4010` | zabezpečené spojenie |
| **Certifikát** | samopodpísaný | alebo vlastný certifikát vo formáte PFX |
V lokálnej sieti je eKasa dostupná aj pod menom `ekasa.local`, napríklad `https://ekasa.local:4010`. Ak je v sieti
viac zariadení s eKasou, každému nastavte vlastný názov inštancie, napríklad `pokladna2.ekasa.local`.
Samopodpísaný certifikát je vystavený na mená `ekasa.local`, `*.ekasa.local` a `localhost`. Klienti mu predvolene
nedôverujú. Stiahnite si jeho verejnú časť v nastaveniach tlačidlom na stiahnutie alebo cez API a nainštalujte ju
na klientoch medzi dôveryhodné certifikáty:
```http
GET https://ekasa.local:4010/api/v1/settings/hosting/https/certificates/pfx?format=pem
```
Pre spojenie cez IP adresu potrebujete vlastný certifikát, ktorý túto adresu obsahuje.
Odporúčané nastavenie pre prevádzku v sieti: režim **Presmerovať HTTP na HTTPS** alebo **Len HTTPS** a v časti
**Prihlásenie** voľba **Vyžadovať HTTPS pre prihlásenie**. eKasa potom odmietne prihlasovacie údaje poslané
cez HTTP so stavom `401` ešte predtým, ako ich spracuje.
## Kam ďalej
- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Inštalácia, prvé volanie a pravidlá komunikácie.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes): Význam kódov v chybových odpovediach.
---
# .NET knižnica
> Požiadavky .NET knižnice NineDigit.eKasa, podporované verzie .NET a operačné systémy, NuGet balíky, aplikácia Portos eKasa Servis a overenie podpisu.
Zdroj: https://ekasa.ninedigit.sk/docs/dotnet
eKasu môžete do svojho softvéru zapojiť cez HTTP API alebo ako .NET knižnicu. Tento článok popisuje integráciu
cez **.NET knižnicu** `NineDigit.eKasa`. Rozdiely oboch možností nájdete v článku
[Možnosti integrácie](https://ekasa.ninedigit.sk/docs/integration-options).
## Požiadavky
Knižnica je zostavená pre .NET Standard 2.0, .NET 6, .NET 9 a .NET 10
([viac o .NET Standard](https://docs.microsoft.com/en-us/dotnet/standard/net-standard)).
### Podporované verzie .NET
- .NET Core 2.0 a novší (.NET Core 3.1, .NET 5, .NET 6 a ďalšie),
- .NET Framework 4.6.1 a novší. Namiesto 4.6.1 dôrazne odporúčame .NET Framework 4.7.2. Pozrite si
[tabuľku kompatibility .NET](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) na stránke Microsoftu.
### Podporované operačné systémy
Od verzie 5 funguje knižnica na všetkých bežných operačných systémoch: Windows, macOS a Linux. Podporované verzie
a distribúcie nájdete v [dokumentácii .NET](https://docs.microsoft.com/en-us/dotnet/core/install/dependencies).
Verzia 3 a staršie fungujú len vo Windows.
## Aplikácia Portos eKasa Servis
**Portos eKasa Servis** je desktopová aplikácia pre servisných technikov. Poskytuje rozhranie na:
- zobrazenie celkového stavu systému,
- vloženie inicializačného balíka (identifikačných a autentifikačných údajov pokladnice),
- ručné spracovanie fronty nespracovaných registrácií dokladov a miesta predaja,
- tlač nespracovaných registrácií dokladov a miesta predaja,
- nastavenie systému.
Vďaka nej vaša aplikácia nemusí mať vlastnú obrazovku na vloženie inicializačného balíka ani na nastavenia eKasy.
Požiadavky aplikácie Portos eKasa Servis:
- Windows 7 a novší,
- .NET Framework 4.7.2.
## NuGet balíky
### `NineDigit.eKasa`
Hlavný NuGet balík s certifikovaným klientom eKasa. Nájdete ho na
[nuget.org](https://www.nuget.org/packages/NineDigit.eKasa).
Vstupnou triedou je `Client`. Sprístupňuje všetky hlavné funkcie, najmä:
- metódy na registráciu dokladov a miesta predaja,
- službu na správu identifikačných údajov (`IdentityManager`),
- službu na správu autentifikačných údajov (`CertificateManager`),
- službu na prístup k subjektom (`SubjectProvider`); subjekt je dvojica identifikačných a autentifikačných údajov
pokladnice,
- frontu nespracovaných registrácií (`Queue`) a službu na sledovanie jej spracovania (`QueueMonitor`).
Ako klienta vytvoriť, popisuje článok [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation).
### `NineDigit.eKasa.Configuration`
Balík na načítanie konfiguračného súboru, ktorý upravuje aplikácia Portos eKasa Servis. Konfiguráciu odporúčame
načítavať práve týmto spôsobom, podrobnosti sú v článku [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration).
Od verzie 8 je konfigurácia súčasťou balíka `NineDigit.eKasa` a samostatný balík `NineDigit.eKasa.Configuration`
odinštalujte (pozri [Migrácia na verziu 8](https://ekasa.ninedigit.sk/docs/migration/v8#1-konfigur%C3%A1cia-je-s%C3%BA%C4%8Das%C5%A5ou-kni%C5%BEnice-ninedigitekasa)).
Pre staršie verzie je balík na [nuget.org](https://www.nuget.org/packages/NineDigit.eKasa.Configuration).
## Overenie digitálneho podpisu
Digitálny podpis knižnice (súboru `.dll`) overíte vo Windows takto:
1. Kliknite pravým tlačidlom myši na súbor `.dll` a zvoľte **Properties** (Vlastnosti).
2. V okne zvoľte záložku **Digital Signatures** (Digitálne podpisy) a v zozname certifikátov vyberte
**Nine Digit, s.r.o.**
3. Kliknite na **Details** (Podrobnosti).
4. V hornej časti nového okna sa zobrazí text **This digital signature is OK.** (Tento digitálny podpis je v poriadku.)
## Kam ďalej
- [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation): Konštruktory triedy Client a jedna inštancia počas behu aplikácie.
- [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration): Načítanie nastavení z aplikácie Portos eKasa Servis.
- [Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging): Napojenie Serilogu, log4net či Seq cez Microsoft.Extensions.Logging.
---
# Vytvorenie klienta
> Ako vytvoriť inštanciu NineDigit.eKasa.Client: konštruktory, konfigurácia, logovanie a jedna inštancia počas celého behu aplikácie.
Zdroj: https://ekasa.ninedigit.sk/docs/dotnet/instantiation
Knižnicu používate cez inštanciu triedy `NineDigit.eKasa.Client`, vstupného bodu celého riešenia. Klientovi
odovzdáte konfiguráciu a logovanie a vaša aplikácia potom používa jednu jeho inštanciu počas celého behu, pretože
s chráneným dátovým úložiskom (CHDÚ) komunikuje výhradne.
## Typické nastavenie
1. **Načítajte konfiguráciu**
Zo súboru nastavení aplikácie Portos eKasa Servis, pozri [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration).
2. **Pripravte logovanie**
Inštanciu `ILoggerFactory` z vášho logovacieho nástroja, pozri [Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging).
3. **Vytvorte jedného klienta**
Konštruktorom s konfiguráciou aj logovaním. Inštanciu používajte počas celého behu aplikácie.
## Konštruktory
Trieda `Client` má štyri verejné konštruktory:
| Konštruktor | Konfigurácia | Logovanie |
|---|---|---|
| `new Client()` | predvolená | žiadne |
| `new Client(ILoggerFactory loggerFactory)` | predvolená | `loggerFactory` |
| `new Client(ClientConfiguration configuration)` | `configuration` | žiadne |
| `new Client(ClientConfiguration configuration, ILoggerFactory loggerFactory)` | `configuration` | `loggerFactory` |
Odporúčame konštruktor, ktorý prijíma konfiguráciu aj logovanie:
```csharp
Client client = new Client(configuration, loggerFactory);
```
Ako konfiguráciu načítať, popisuje článok [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration), ako napojiť logovanie, článok
[Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging).
## Životný cyklus inštancie
Vaša aplikácia má používať **jednu dlhodobo žijúcu inštanciu** triedy `NineDigit.eKasa.Client`. Táto inštancia
komunikuje s chráneným dátovým úložiskom (CHDÚ) výhradne.
## Príklad celého nastavenia
Príklad spája všetky tri kroky: načíta konfiguráciu aplikácie Portos eKasa Servis, napojí Serilog (NuGet balíky
`Serilog.Extensions.Logging` a `Serilog.Sinks.Console`) a vytvorí jednu inštanciu klienta pre celú aplikáciu.
```csharp
using System;
using System.IO;
using Microsoft.Extensions.Logging;
using NineDigit.eKasa;
using NineDigit.eKasa.Configuration.DataSources;
using Serilog;
using Serilog.Extensions.Logging;
static class EKasa
{
// jedna dlhodobo žijúca inštancia pre celú aplikáciu
public static Client Client { get; } = CreateClient();
static Client CreateClient()
{
// 1. konfigurácia z aplikácie Portos eKasa Servis
string configurationFilePath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
"NineDigit", "Portos.eKasa", "settings.json");
IDataSource configurationDataSource =
new JsonClientConfigurationFileDataSource(configurationFilePath);
// ak súbor neexistuje, použije sa predvolená konfigurácia
ClientConfiguration configuration = configurationDataSource.Load() ?? new ClientConfiguration();
// 2. logovanie (Serilog do konzoly)
Serilog.ILogger serilogLogger = new LoggerConfiguration()
.MinimumLevel.Debug()
.WriteTo.Console()
.CreateLogger();
ILoggerFactory loggerFactory = new SerilogLoggerFactory(serilogLogger);
// 3. klient s konfiguráciou aj logovaním
return new Client(configuration, loggerFactory);
}
}
```
## Kam ďalej
- [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration): Načítanie nastavení z aplikácie Portos eKasa Servis.
- [Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging): Napojenie vlastného logovacieho nástroja.
---
# Konfigurácia
> Ako načítať konfiguráciu klienta eKasa zo súboru nastavení aplikácie Portos eKasa Servis do vlastnej .NET aplikácie.
Zdroj: https://ekasa.ninedigit.sk/docs/dotnet/configuration
Aplikácia Portos eKasa Servis ukladá nastavenia do textového súboru vo formáte JSON. Ak má vaša aplikácia používať
rovnaké nastavenia, načítajte tento súbor a jeho obsah odovzdajte konštruktoru triedy `Client`. Nastavenia potom
servisný technik upravuje v aplikácii Portos eKasa Servis a vaša aplikácia ich prevezme.
## Načítanie konfiguračného súboru vo vašej aplikácii
1. **Zostavte cestu k súboru**
Súbor `settings.json` v predvolenom pracovnom adresári `NineDigit/Portos.eKasa` v priečinku
`Environment.SpecialFolder.CommonApplicationData`.
2. **Načítajte konfiguráciu**
Čítačom `JsonClientConfigurationFileDataSource` a jeho metódou `Load()`.
3. **Odovzdajte ju klientovi**
Konštruktoru triedy `Client`, pozri [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation).
```csharp
// cesta k predvolenému pracovnému adresáru, ktorý obsahuje konfiguračný súbor
string ekasaWorkingDirectoryPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
"NineDigit",
"Portos.eKasa");
// úplná cesta ku konfiguračnému súboru
string configurationFilePath = Path.Combine(ekasaWorkingDirectoryPath, "settings.json");
// vytvorenie čítača konfigurácie
IDataSource configurationDataSource = new JsonClientConfigurationFileDataSource(configurationFilePath);
// načítanie obsahu konfiguračného súboru do konfiguračného objektu,
// ak súbor neexistuje, použije sa predvolená konfigurácia
ClientConfiguration configuration = configurationDataSource.Load() ?? new ClientConfiguration();
// konfiguračný objekt odovzdajte konštruktoru klienta,
// klient potom používa rovnaké nastavenia ako aplikácia Portos eKasa Servis
Client client = new Client(configuration);
```
Priečinok `CommonApplicationData` je predvolený pracovný adresár na Windows. Na macOS a Linuxe je to
`/etc/NineDigit/Portos.eKasa`, lebo do `CommonApplicationData` sa na macOS nedá zapisovať. Cestu pre aktuálnu
platformu vráti `EKasaPath.AppDataDirectoryPath`:
```csharp
string configurationFilePath = Path.Combine(EKasaPath.AppDataDirectoryPath, "settings.json");
```
| Konfiguračný súbor | `Load()` vráti | Klient použije |
|---|---|---|
| existuje | načítanú konfiguráciu | nastavenia aplikácie Portos eKasa Servis |
| neexistuje | `null` | predvolenú konfiguráciu (`new ClientConfiguration()`) |
### Menné priestory a NuGet balík
| Trieda | Menný priestor |
|---|---|
| `JsonClientConfigurationFileDataSource` | `NineDigit.eKasa.Configuration.DataSources` |
| `IDataSource` | `NineDigit.eKasa.Configuration.DataSources` |
| `ClientConfiguration` | `NineDigit.eKasa` |
Od verzie 8 sú tieto triedy súčasťou NuGet balíka `NineDigit.eKasa`, v starších verziách boli v samostatnom balíku
`NineDigit.eKasa.Configuration`.
## Úprava iného konfiguračného súboru v aplikácii Portos eKasa Servis
Ak chcete v aplikácii Portos eKasa Servis upravovať iný konfiguračný súbor, zmeňte cestu k nemu:
1. **Otvorte ponuku**
V pravom hornom rohu aplikácie kliknite na tlačidlo ponuky.
2. **Zvoľte Nastavenia aplikácie**
V ponuke vyberte **Nastavenia aplikácie**.
3. **Zadajte cestu**
Zadajte cestu ku konfiguračnému súboru, prípadne ho vyhľadajte tlačidlom na prehľadávanie súborov.
## Kam ďalej
- [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation): Konštruktory triedy Client a jedna inštancia počas behu aplikácie.
- [Logovanie](https://ekasa.ninedigit.sk/docs/dotnet/logging): Napojenie vlastného logovacieho nástroja.
---
# Logovanie
> Ako napojiť vlastný logovací nástroj (Serilog, log4net, Seq) na .NET knižnicu eKasa cez Microsoft.Extensions.Logging.Abstractions.
Zdroj: https://ekasa.ninedigit.sk/docs/dotnet/logging
Knižnica eKasa sa na logovanie napája cez abstrakciu
[*Microsoft.Extensions.Logging.Abstractions*](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Abstractions/).
Trieda `Client` prijíma inštanciu `ILoggerFactory`, takže knižnica nepredpisuje logovací nástroj: použijete ten,
ktorý už má vaša aplikácia.
## Podporované nástroje
Môžete použiť ľubovoľný logovací nástroj, ktorý vytvorí `ILoggerFactory`, napríklad:
| Nástroj | Napojenie na `ILoggerFactory` |
|---|---|
| Serilog | [serilog-extensions-logging](https://github.com/serilog/serilog-extensions-logging) |
| log4net | [Microsoft.Extensions.Logging.Log4Net.AspNetCore](https://github.com/huorswords/Microsoft.Extensions.Logging.Log4Net.AspNetCore) |
| Seq | [Seq.Extensions.Logging](https://www.nuget.org/packages/Seq.Extensions.Logging/) |
## Príklad so Serilogom
1. **Nainštalujte NuGet balíky**
`Serilog.Extensions.Logging` a `Serilog.Sinks.Console`.
2. **Vytvorte logger Serilogu**
Nastavte úroveň podrobnosti logovaných správ a výstup do konzoly.
3. **Zabaľte ho do `ILoggerFactory`**
Triedou `SerilogLoggerFactory`.
4. **Odovzdajte ho klientovi**
Konštruktoru `Client(configuration, loggerFactory)`, pozri [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation).
```csharp
using Microsoft.Extensions.Logging;
using NineDigit.eKasa;
using Serilog;
using Serilog.Extensions.Logging;
namespace SerilogExampleApp
{
class SerilogLoggerExample
{
public void Demo(ClientConfiguration configuration)
{
// Trieda Client prijíma inštanciu ILoggerFactory.
// Vďaka tejto abstrakcii môžete použiť svoj obľúbený logovací nástroj.
// V tomto príklade používame Serilog s NuGet balíkmi:
// - Serilog.Extensions.Logging
// - Serilog.Sinks.Console
Serilog.ILogger serilogLogger = new LoggerConfiguration()
.MinimumLevel.Debug() // úroveň podrobnosti logovaných správ
.WriteTo.Console()
.CreateLogger();
// vytvorenie univerzálnej inštancie Microsoft.Extensions.Logging.ILoggerFactory
ILoggerFactory loggerFactory = new SerilogLoggerFactory(serilogLogger);
// otestovanie loggera
loggerFactory.CreateLogger(nameof(SerilogLoggerExample)).LogDebug("Hello from SerilogExampleApp!");
// vytvorenie vstupného bodu celého riešenia, inštancie triedy Client
Client client = new NineDigit.eKasa.Client(configuration, loggerFactory);
}
}
}
```
Ďalšie možnosti nastavenia Serilogu nájdete v
[dokumentácii Serilogu](https://github.com/serilog/serilog/wiki/Configuration-Basics).
## Kam ďalej
- [Vytvorenie klienta](https://ekasa.ninedigit.sk/docs/dotnet/instantiation): Konštruktory triedy Client a jedna inštancia počas behu aplikácie.
- [Konfigurácia](https://ekasa.ninedigit.sk/docs/dotnet/configuration): Načítanie nastavení z aplikácie Portos eKasa Servis.
---
# Rozsah integrácie
> Čo musí váš softvér s eKasou vedieť: minimálna integrácia s registráciou dokladu, kontrola stavu, poloha pokladnice a voliteľné funkcie.
Zdroj: https://ekasa.ninedigit.sk/docs/integration-scope
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](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id).
2. **Registrácia dokladu** pri predaji, vrátení tovaru aj oprave. Položky, platby a typy položiek popisuje článok
[Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration).
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](https://ekasa.ninedigit.sk/docs/rest-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.
**HTTP API:**
```http
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é):
```json
{
"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ť.
**.NET knižnica:**
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](https://ekasa.ninedigit.sk/docs/status).
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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1)) |
| 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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-q)) |
| 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](https://www.financnasprava.sk/sk/podnikatelia/dane/ekasa/vyrobcovia-ekasa) 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](https://ekasa.ninedigit.sk/docs/status). 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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-11.odsek-3)).
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](https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types).
### 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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-7.odsek-8)).
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](https://ekasa.ninedigit.sk/docs/location-registration).
## 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](https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types).
- **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](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt):** objednávka, účet pred zaplatením alebo iný text na tlačiarni.
- **[Kópia a vyhľadanie dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup)**.
- **[QR platby](https://ekasa.ninedigit.sk/docs/qr-payments)** bez platobného terminálu.
- **[Peňažná zásuvka](https://ekasa.ninedigit.sk/docs/drawer)** otváraná cez eKasu.
## Kam ďalej
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status): Úložisko, autentifikačné údaje, tlačiareň a spojenie.
- [Registrácia polohy](https://ekasa.ninedigit.sk/docs/location-registration): Kedy a ako zaregistrovať polohu prenosnej pokladnice.
---
# Registrácia dokladu
> Prehľad registrácie dokladu: typy dokladov, adresy API a metódy knižnice, štruktúra požiadavky a odkazy na položky, platby, zľavy, opravy a výsledok.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration
Registrácia dokladu je hlavná úloha integrácie: váš softvér pošle eKase údaje o predaji a eKasa doklad overí, zapíše
do úložiska, odošle do systému eKasa, vyhotoví a vráti výsledok. Celý postup krok za krokom ukazuje
[Ako funguje eKasa](https://ekasa.ninedigit.sk/docs/how-it-works). Táto stránka je prehľad, podrobnosti nájdete na podstránkach.
Vzorové riešenie s .NET knižnicou nájdete v projekte
[ninedigit-ekasa-quickstart](https://github.com/ninedigit/ninedigit-ekasa-quickstart) na GitHube.
## Typy dokladov
Každý typ dokladu má vlastnú adresu v API a vlastnú triedu požiadavky v knižnici:
**HTTP API:**
| Doklad | Kedy | Adresa |
|---|---|---|
| Pokladničný doklad | predaj, vrátenie, oprava | `POST /api/v1/requests/receipts/cash_register` |
| Paragón | dodatočná evidencia dokladu z poruchy pokladnice | `POST /api/v1/requests/receipts/paragon` |
| Úhrada faktúry | platba faktúry na predajnom mieste | `POST /api/v1/requests/receipts/invoice` |
| Paragón pri úhrade faktúry | dodatočná evidencia úhrady faktúry z poruchy | `POST /api/v1/requests/receipts/invoice_paragon` |
**.NET knižnica:**
| Doklad | Kedy | Požiadavka pre `client.RegisterReceiptAsync()` |
|---|---|---|
| Pokladničný doklad | predaj, vrátenie, oprava | `RegisterCashRegisterReceiptRequest` |
| Paragón | dodatočná evidencia dokladu z poruchy pokladnice | `RegisterParagonReceiptRequest` |
| Úhrada faktúry | platba faktúry na predajnom mieste | `RegisterInvoiceReceiptRequest` |
| Paragón pri úhrade faktúry | dodatočná evidencia úhrady faktúry z poruchy | `RegisterInvoiceParagonReceiptRequest` |
Doklady typu neplatný doklad, vklad a výber sa od 1. 1. 2026 neevidujú a eKasa ich od verzie 9 nepodporuje.
Údaj o kupujúcom sa na doklade neuvádza od roku 2021, keď ho zrušil Ústavný súd SR.
## Štruktúra požiadavky
Požiadavka cez HTTP API má tri časti:
```jsonc
{
"request": {
"data": { /* … údaje dokladu */ },
"externalId": "objednavka-2026-000123"
},
"print": {
"printerName": "pos"
}
}
```
| Časť | Povinná | Obsah |
|---|---|---|
| `request.data` | áno | údaje dokladu: kód pokladnice, [položky](https://ekasa.ninedigit.sk/docs/receipt-registration/items), [platby](https://ekasa.ninedigit.sk/docs/receipt-registration/payments), texty |
| `request.externalId` | vždy uveďte | váš identifikátor, ktorý chráni pred [dvojitou evidenciou tržby](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id) |
| `print` | nie | [spôsob vyhotovenia](https://ekasa.ninedigit.sk/docs/receipt-registration/printing): papier, PDF alebo e-mail. Predvolene papier. |
V .NET knižnici zodpovedá `request` objekt požiadavky a `print` parameter `RegisterReceiptPrintContext`.
## Témy
- [Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id): externalId: prečo je nevyhnutný a ako ho použiť.
- [Typy dokladov](https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types): Pokladničný doklad, paragón a úhrada faktúry s príkladmi.
- [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items): Typ položky, cena, množstvo a sadzba DPH.
- [Platby a zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments): Platidlá a zaokrúhlenie hotovosti.
- [Zľavy](https://ekasa.ninedigit.sk/docs/receipt-registration/discounts): Zľava na položku a na celý doklad.
- [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections): Oprava dokladu, vrátenie tovaru a úhrady faktúry.
- [Poukazy](https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers): Jednoúčelový a viacúčelový poukaz.
- [Odpočet zálohy](https://ekasa.ninedigit.sk/docs/receipt-registration/advances): Záloha prijatá pred dodaním tovaru.
- [Vyhotovenie dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/printing): Papier, PDF alebo e-mail a vlastné texty.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): isSuccessful, číslo dokladu a rekapitulácia DPH.
---
# Ochrana pred duplicitou (externalId)
> Prečo každý doklad musí mať vlastný externalId: zabráni dvojitej evidencii tržby, keď sa stratí odpoveď. Ako ho tvoriť, čo eKasa vráti a ktoré úložiská ho strážia.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/external-id
`externalId` je váš vlastný identifikátor dokladu, napríklad číslo objednávky. Formálne je nepovinný, v praxi je to
**jedna z najdôležitejších vecí celej integrácie**: bráni tomu najhoršiemu, čo sa môže stať, totiž dvojitej
evidencii tej istej tržby.
**Uvádzajte `externalId` pri každom doklade.** Bez neho nemá eKasa ako rozpoznať, že ten istý predaj posielate
druhýkrát, a zaeviduje ho znova. Zákazník dostane dva doklady a podnikateľovi sa v systéme eKasa započíta dvojnásobná
tržba.
## Kedy duplicita vzniká
Doklad sa zaeviduje, ale odpoveď sa k vášmu softvéru nedostane: vyprší časový limit, preruší sa sieť alebo spadne
aplikácia. Váš softvér nevie, či sa doklad zaevidoval, a pošle ho znova.
```mermaid
sequenceDiagram
autonumber
participant S as Váš softvér
participant K as eKasa
S->>K: doklad (externalId objednavka-42)
Note over K: doklad zaevidovaný a vytlačený
K--xS: odpoveď sa stratí
S->>K: ten istý doklad znova (externalId objednavka-42)
K-->>S: pôvodný výsledok, nič sa neeviduje ani netlačí
```
Bez `externalId` by krok 4 zaevidoval a vytlačil druhý doklad.
## Ako na to
1. **Vytvorte identifikátor**
Pre každý predaj jeden, jedinečný v rámci pokladnice: číslo objednávky, ID transakcie alebo UUID. Najviac 40 znakov.
2. **Uložte ho pred odoslaním**
Identifikátor uložte k predaju ešte pred volaním eKasy, aby ste ho po páde aplikácie poznali.
3. **Pri opakovaní pošlite to isté**
Ak odpoveď nedostanete, pošlite doklad znova s rovnakým `externalId` aj rovnakými údajmi.
**HTTP API:**
```jsonc
{
"request": {
"data": { /* … údaje dokladu */ },
"externalId": "objednavka-2026-000123"
}
}
```
**.NET knižnica:**
```csharp
var request = new RegisterCashRegisterReceiptRequest("objednavka-2026-000123", receipt);
RegisterReceiptResult result = await client.RegisterReceiptAsync(
request, RegisterReceiptPrintContext.CreatePos(), cancellationToken);
```
Rovnako funguje `externalId` aj pri [registrácii polohy](https://ekasa.ninedigit.sk/docs/location-registration).
## Čo eKasa vráti
```mermaid
flowchart TD
A{Použil sa tento externalId už skôr?} -->|nie| B[Doklad sa zaeviduje bežným spôsobom]
A -->|áno| C{Rovnaké údaje dokladu?}
C -->|nie| D[Chyba -403 StorageDuplicateKey]
C -->|áno| E{Pôvodná registrácia ešte prebieha?}
E -->|áno| V{Verzia eKasy?}
V -->|9.1.0 a novšia| F[eKasa počká a vráti jej výsledok]
V -->|staršia ako 9.1.0| H[Chyba -100 GeneralError, pôvodná registrácia pokračuje]
E -->|nie| G[Pôvodný výsledok, nič sa neeviduje ani netlačí]
```
Chyba [`-403 StorageDuplicateKey`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-403-storageduplicatekey) znamená, že ten istý
`externalId` ste použili pri inom doklade.
„Rovnaký doklad“ znamená rovnaké údaje dokladu (položky, platby, texty). Spôsob vyhotovenia v `print` sa
neporovnáva.
Od verzie 9.1.0 eKasa navyše zvláda situáciu, keď váš softvér po vypršaní limitu zatvorí spojenie a požiadavku
hneď zopakuje: opakovaná požiadavka počká, kým sa pôvodná registrácia dokončí. Registrácia, ktorej požiadavka sa
už zapísala do úložiska, sa dokončí aj po zatvorení spojenia: doklad sa odošle do systému eKasa a vytlačí.
## Ktoré úložiská unikátnosť strážia
Unikátnosť `externalId` kontroluje úložisko pri zápise, cez svoju tabuľku indexov.
| Úložisko | Kontroluje `externalId` |
|---|:---:|
| CHDU Lite | áno |
| CHDU-SK | áno |
| SwissBit | áno |
| In-Memory | nie |
Testovacie úložisko **In-Memory** duplicitu nekontroluje: doklad s rovnakým `externalId` zaregistruje znova. Opakované
odoslanie si preto pred nasadením vyskúšajte so skutočným úložiskom. Vo vašom softvéri však `externalId` posielajte
vždy, aj pri vývoji na In-Memory.
## Ďalšie využitie
Podľa `externalId` doklad aj [vyhľadáte](https://ekasa.ninedigit.sk/docs/receipt-lookup) a [vytlačíte jeho kópiu](https://ekasa.ninedigit.sk/docs/receipt-lookup#tla%C4%8D-k%C3%B3pie-dokladu), bez
toho, aby ste si museli pamätať číslo dokladu.
## Kam ďalej
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): isSuccessful, číslo dokladu a identifikátor.
- [Vyhľadanie dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup): Doklad podľa externalId alebo čísla.
- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Čo musí váš softvér vedieť.
---
# Typy dokladov
> Pokladničný doklad, paragón, úhrada faktúry a paragón pri úhrade faktúry: kedy ktorý doklad použiť a ako ho zaregistrovať.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types
Typ dokladu určuje, v akej situácii doklad vzniká a ktoré údaje musí obsahovať. Väčšina predajov je **pokladničný doklad**. Ostatné typy pokrývajú poruchu pokladnice (paragón) a platby faktúr.
```mermaid
flowchart TD
A{Platí zákazník faktúru?} -->|nie, bežný predaj| B{Fungovala pokladnica v čase predaja?}
B -->|áno| C[Pokladničný doklad]
B -->|nie, dodatočná evidencia| D[Paragón]
A -->|áno| E{Fungovala pokladnica v čase platby?}
E -->|áno| F[Úhrada faktúry]
E -->|nie, dodatočná evidencia| G[Paragón pri úhrade faktúry]
```
## Pokladničný doklad
Bežný pokladničný doklad, ktorý je vyhotovovaný pri predaji, prípadne pri vrátení tovaru alebo stornovaní dokladu.
[Obrázok: Pokladničný doklad s dvoma cappuccinami a vernostnou zľavou, platba kartou]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Cappuccino",
"quantity": {
"amount": 2.0,
"unit": "ks"
},
"unitPrice": 2.9,
"price": 5.8,
"vatRate": 19.0
},
{
"type": "discount",
"name": "Vernostná zľava",
"quantity": {
"amount": 1.0
},
"unitPrice": -1.0,
"price": -1.0,
"vatRate": 19.0
}
],
"payments": [
{
"name": "Karta",
"amount": 4.8
}
]
}
}
}
```
**.NET knižnica:**
Metóda: `client.RegisterReceiptAsync(RegisterCashRegisterReceiptRequest, RegisterReceiptPrintContext, CancellationToken)`
## Pokladničný doklad - paragón
Keď pokladnica nefunguje, obsluha vypisuje zákazníkom papierové doklady, takzvané **paragóny**. Po obnovení
prevádzky ich musí dodatočne zaevidovať v pokladnici, a to najneskôr do desiatich dní (§ 11 ods. 3 zákona
č. 384/2025 Z. z.).
Výpadok internetu nie je porucha: pokladnica s úložiskom CHDÚ, ktorú eKasa vytvára, doklady ďalej vyhotovuje
a zaeviduje ich v offline režime, odošle ich po obnovení spojenia. Paragón pri výpadku internetu ukladá zákon len
softvérovej a virtuálnej pokladnici (§ 11 ods. 1), tie táto dokumentácia nepokrýva.
**Porucha**: pokladnica nefunguje
→
**Paragón**: vypísaný v čase T s číslom P
→
**Oprava**: porucha pominie
→
**Evidencia**: doklad s issueDate T a paragonNumber P
Váš softvér preto potrebuje formulár, v ktorom obsluha k položkám zadá z paragónu:
- `issueDate`: dátum a čas vyhotovenia paragónu (T),
- `paragonNumber`: číslo paragónu (P).
Ostatné údaje sú rovnaké ako pri pokladničnom doklade.
[Obrázok: Zaevidovaný paragón: hlavička Zaevidovanie paragónu, číslo a dátum paragónu, položky a platba]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/paragon
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"issueDate": "2026-11-18T12:30:40+01:00",
"paragonNumber": 1,
"items": [
{
"type": "positive",
"name": "Cappuccino",
"quantity": {
"amount": 2.0,
"unit": "ks"
},
"unitPrice": 2.9,
"price": 5.8,
"vatRate": 19.0
},
{
"type": "discount",
"name": "Vernostná zľava",
"quantity": {
"amount": 1.0
},
"unitPrice": -1.0,
"price": -1.0,
"vatRate": 19.0
}
],
"payments": [
{
"name": "Karta",
"amount": 4.8
}
]
}
}
}
```
**.NET knižnica:**
Metóda: `client.RegisterReceiptAsync(RegisterParagonReceiptRequest, RegisterReceiptPrintContext, CancellationToken)`
## Úhrada faktúry
Faktúru podnikateľ vystaví mimo eKasy, napríklad v účtovnom programe. Keď ju zákazník príde zaplatiť na predajné
miesto, podnikateľ platbu zaeviduje ako **úhradu faktúry**.
**Faktúra**: vystavená mimo eKasy
→
**Platba**: zákazník platí na predajnom mieste
→
**Úhrada faktúry**: číslo faktúry a uhrádzaná suma
Doklad úhrady faktúry nemá položky (`items`). Obsluha zadá:
- `invoiceNumber`: číslo faktúry,
- `amount`: uhrádzanú sumu s DPH, teda celú sumu faktúry alebo len jej časť, ak zákazník platí po častiach.
Ak zákazník platí v hotovosti, uveďte v `amount` sumu pred zaokrúhlením a zaokrúhlenie vo vlastnosti `roundingAmount`
(pozri [Zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments#zaokr%C3%BAh%C4%BEovanie)).
[Obrázok: Doklad úhrady faktúry: číslo faktúry a suma, bez položiek a rekapitulácie DPH]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/invoice
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"invoiceNumber": "FA-2026-0142",
"amount": 189.9
}
}
}
```
**.NET knižnica:**
Metóda: `client.RegisterReceiptAsync(RegisterInvoiceReceiptRequest, RegisterReceiptPrintContext, CancellationToken)`
## Úhrada faktúry - paragón
Kombinácia oboch predchádzajúcich prípadov: zákazník platí faktúru v čase, keď pokladnica nefunguje. Obsluha mu
vypíše paragón a po odstránení poruchy ho zaeviduje ako úhradu faktúry.
**Faktúra**: vystavená mimo eKasy
→
**Porucha**: pokladnica nefunguje
→
**Paragón**: platba faktúry v čase T, číslo P
→
**Evidencia**: úhrada faktúry s T, P, číslom faktúry a sumou
Doklad nemá položky (`items`). Obsluha zadá:
- `issueDate`: dátum a čas vyhotovenia paragónu (T),
- `paragonNumber`: číslo paragónu (P),
- `invoiceNumber`: číslo faktúry,
- `amount`: uhrádzaná suma s DPH (celá suma faktúry alebo jej časť)
[Obrázok: Zaevidovaný paragón pri úhrade faktúry: číslo a dátum paragónu, číslo faktúry a suma]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/invoice_paragon
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"issueDate": "2026-11-18T12:30:40+01:00",
"invoiceNumber": "FA-2026-0143",
"paragonNumber": 2,
"amount": 189.9
}
}
}
```
**.NET knižnica:**
Metóda: `client.RegisterReceiptAsync(RegisterInvoiceParagonReceiptRequest, RegisterReceiptPrintContext, CancellationToken)`
## Kam ďalej
- [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items): Typ položky, cena, množstvo a sadzba DPH.
- [Platby a zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments): Platidlá a zaokrúhlenie hotovosti.
- [Vyhotovenie dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/printing): Papier, PDF alebo e-mail a vlastné texty.
---
# Položky dokladu
> Vlastnosti položky dokladu: typ, označenie, cena, množstvo, sadzba DPH, dôvod nulovej sadzby, predávajúci a popis.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/items
Položky (`items`) sú tovary a služby na doklade, ale aj zľavy, vrátenia, vratné obaly či odpočty záloh. **Typ položky
určuje, čo položka znamená**, a od neho sa odvíja znamienko ceny, povolené sadzby DPH aj to, či treba uviesť pôvodný
doklad.
Položky uvádzate len pri niektorých typoch dokladov:
| Typ dokladu | Identifikátor | Obsahuje položky |
|---|---|:---:|
| Pokladničný doklad | `CashRegister` | áno |
| Paragón | `Paragon` | áno |
| Faktúra | `Invoice` | nie |
| Paragón pri úhrade faktúry | `InvoiceParagon` | nie |
Pokladničný doklad a paragón musia mať aspoň jednu položku, najviac ich môže byť 500.
- [Vlastnosti položky](#vlastnosti-položky): Prehľad všetkých polí, povinnosť a formát.
- [Typy položiek](#typ-položky-type): Predaj, zľava, vrátenie, vratné obaly, záloha, poukaz, oprava.
- [Vratné obaly](#vrátenie-dokladu-s-vratným-obalom): Predaj so zálohou na obal a jeho vrátenie.
- [Sadzby DPH](#sadzba-dph-vatrate): Platné sadzby podľa obdobia a podľa typu položky.
## Vlastnosti položky
Každá položka sa skladá z týchto vlastností. V .NET knižnici (trieda `ReceiptItem`) majú rovnaký názov s veľkým
začiatočným písmenom (`Type`, `UnitPrice`…).
| Vlastnosť | Povinná | Formát | Význam |
|---|---|---|---|
| [`type`](#typ-položky-type) | áno | `positive`, `discount`, `returned`… | typ položky |
| [`name`](#označenie-name) | áno | text, najviac 255 znakov | označenie tovaru alebo služby |
| [`price`](#celková-cena-price) | áno | `-10000000` až `10000000`, 2 desatinné miesta | celková cena |
| [`unitPrice`](#jednotková-cena-unitprice) | áno | `-10000000` až `10000000`, 6 desatinných miest, znamienko podľa typu | jednotková cena v EUR |
| [`quantity`](#množstvo-quantity) | áno | `amount` a `unit` | množstvo tovaru alebo rozsah služby |
| [`referenceReceiptId`](#referenčné-číslo-dokladu-referencereceiptid) | pri `returned` a `correction` | ID dokladu, OKP alebo číslo dokladu z ERP | pôvodný doklad |
| [`vatRate`](#sadzba-dph-vatrate) | podľa [typu položky](#povolené-hodnoty-sadzby-dph) | číslo, 2 desatinné miesta, alebo `null` | sadzba DPH |
| [`specialRegulation`](#dôvod-nulovej-sadzby-specialregulation) | nie | `VATReverseCharge`, `VATExemptionGood`… | dôvod nulovej sadzby |
| [`seller`](#predávajúci-seller) | nie | `id` a `type` | predávajúci, ak je iný ako podnikateľ pokladnice |
| [`voucherNumber`](#číslo-poukazu-vouchernumber) | pri `voucher` | text, 1 až 50 znakov | číslo jednoúčelového poukazu |
| [`description`](#popis-položky-description) | nie | text, podporuje [tokeny](https://ekasa.ninedigit.sk/docs/token-syntax) | dodatočný popis na doklade |
## Typ položky (`type`)
Povinný. Položka kladného typu musí mať kladnú jednotkovú cenu, položka záporného typu zápornú.
| Identifikátor | Názov | Cena | Kedy | Podmienky |
|---|---|---|---|---|
| `positive` | Kladná položka | kladná | predaj tovaru alebo poskytnutie služby | |
| `returnedContainer` | Vrátené obaly | záporná | vykúpené zálohované obaly; aj vrátenie predaného vratného obalu, napríklad pri vrátení dokladu | |
| `returned` | Vrátená | záporná | zrušenie evidovanej položky po jej vystavení na pokladničnom doklade pri vrátení tovaru alebo služby, napríklad pri reklamácii | nepoužíva sa pre vratné obaly |
| `correction` | Opravná | kladná aj záporná | negácia položky už zaevidovaného dokladu v systéme e-kasa v prípade jej opravy, napríklad pri omyle obsluhy | |
| `discount` | [Zľava](https://ekasa.ninedigit.sk/docs/receipt-registration/discounts) | záporná | poskytnutá zľava | na doklade musí byť aj kladná položka (`positive`) v rovnakej sadzbe DPH, ku ktorej sa zľava vzťahuje; súčet zliav nesmie prevyšovať súčet položiek s kladnou cenou v tejto sadzbe DPH |
| `advance` | [Odpočítaná záloha](https://ekasa.ninedigit.sk/docs/receipt-registration/advances) | záporná | suma prijatého preddavku na doklade vystavenom v čase úhrady doplatku ceny za predaný tovar alebo poskytnutú službu, ak bola za tovar už v minulosti obdržaná záloha | na doklade musí byť aj kladná položka (`positive`), ku ktorej sa odpočet zálohy vzťahuje |
| `voucher` | [Výmena poukazu](https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers) | záporná | suma jednoúčelového poukazu pri jeho výmene za tovar alebo poskytnutú službu, teda pri uplatnení vopred zakúpeného poukazu | na doklade musí byť aj kladná položka (`positive`), ku ktorej sa výmena poukazu vzťahuje; okrem poukazov smú byť na doklade len kladné položky (`positive`) a zľavy (`discount`) |
### Vrátenie dokladu s vratným obalom
Pri vrátení tovaru, napríklad pri vrátení celého dokladu, sa vratný obal z pôvodného dokladu neeviduje ako vrátená
položka (`returned`), ale ako vrátené obaly (`returnedContainer`):
| | Vrátený tovar (`returned`) | Vrátený obal (`returnedContainer`) |
|---|---|---|
| sadzba DPH | povinná, sadzba predaja | `null` (položka nepodlieha DPH) |
| jednotková cena | záporná | záporná |
| `referenceReceiptId` | povinné | neuvádza sa |
Vrátená položka (`returned`) musí mať sadzbu DPH, preto ju pre vratný obal použiť nemožno. Registrácia takého dokladu
skončí validačnou chybou _Sadzba DPH je povinná pre všetky položky okrem kladnej položky, položky zľavy, vrátenia
vratných obalov alebo opravnej položky._
**Pôvodný doklad.** Nápoj sa predáva spolu so zálohou na vratný obal. Záloha je kladná položka (`positive`) so
sadzbou `null` a na doklade sa vytlačí v časti **Vratné obaly** ako predaj:
[Obrázok: Doklad s predajom nápoja Coca Cola a zálohy na PET fľašu, záloha v časti Vratné obaly ako predaj; zvýraznené sú záloha a časť Vratné obaly]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 23.00
},
{
"type": "positive",
"name": "Záloha PET",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 0.15,
"price": 0.15,
"vatRate": null
}
],
"payments": [
{
"name": "Karta",
"amount": 2.14
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Positive, "Coca Cola", 1.99m, new Quantity(1, "ks"), 23m),
new ReceiptItem(ReceiptItemType.Positive, "Záloha PET", 0.15m, new Quantity(1, "ks"), VatRate.None),
};
```
**Vrátenie tohto dokladu.** Nápoj je vrátená položka (`returned`) s odkazom na pôvodný doklad, záloha sú vrátené
obaly (`returnedContainer`) bez odkazu:
[Obrázok: Vrátenie dokladu: Coca Cola ako vrátená položka s identifikátorom pôvodného dokladu, záloha ako návrat v časti Vratné obaly; zvýraznené sú záloha a časť Vratné obaly]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "returned",
"name": "Coca Cola",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": -1.99,
"price": -1.99,
"vatRate": 23.00,
"referenceReceiptId": "O-974C23A2520D4E788C23A2520DA-TEST"
},
{
"type": "returnedContainer",
"name": "Záloha PET",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": -0.15,
"price": -0.15,
"vatRate": null
}
],
"payments": [
{
"name": "Karta",
"amount": -2.14
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Returned, "Coca Cola", -1.99m, new Quantity(1, "ks"), 23m,
referenceReceiptId: "O-974C23A2520D4E788C23A2520DA-TEST"),
new ReceiptItem(ReceiptItemType.ReturnedContainer, "Záloha PET", -0.15m, new Quantity(1, "ks"), VatRate.None),
};
```
## Označenie (`name`)
Povinné. Označenie tovaru alebo služby je neprázdny text s dĺžkou najviac 255 znakov.
Niektoré symboly (najmä netlačiteľné) sú však systémom eKasa zakázané. Viac v článku
[Kódovanie a špeciálne znaky](https://ekasa.ninedigit.sk/docs/encoding).
## Celková cena (`price`)
Povinná. Celková cena tovaru alebo služby v rozsahu `-10000000` až `10000000`, s presnosťou na dve desatinné miesta.
Musí sa rovnať súčinu jednotkovej ceny a množstva zaokrúhlenému na dve desatinné miesta (polovica sa zaokrúhľuje
nahor):
```
price = unitPrice × quantity
```
## Jednotková cena (`unitPrice`)
Povinná. Jednotková cena tovaru alebo služby v EUR v rozsahu `-10000000` až `10000000` s presnosťou na šesť desatinných
miest. Znamienko určuje typ položky:
| Typ položky | Typy | Povolený rozsah |
|---|---|---|
| kladná | `positive` | `0` až `10000000` |
| záporná | `returnedContainer`, `returned`, `discount`, `advance`, `voucher` | `-10000000` až `0` |
| opravná | `correction` | plný rozsah `-10000000` až `10000000` |
## Množstvo (`quantity`)
Povinné. Množstvo tovaru alebo rozsah služby má dve polia:
| Pole | Povinné | Hodnoty | Predvolená |
|---|:---:|---|---|
| `amount` | áno | `0` až `10000000`, štyri desatinné miesta | |
| `unit` | nie | množstevná jednotka, 1 až 3 znaky | `x` |
## Referenčné číslo dokladu (`referenceReceiptId`)
Odkaz na pôvodný doklad. Povinné je iba pri položke typu `correction` alebo `returned`. Pri ostatných typoch musí byť
`null` (nesmie byť uvedené). Platí to aj pre položku `returnedContainer` pri vrátení dokladu, hoci vracia obal
z konkrétneho pôvodného dokladu.
| Pôvodný doklad | Referenčné číslo |
|---|---|
| zaregistrovaný v online režime, má unikátny identifikátor dokladu | tento identifikátor (pole `response.data.id`) |
| zaregistrovaný v offline režime, nemá unikátny identifikátor dokladu | OKP (pole `request.data.okp`) |
| vyhotovený elektronickou registračnou pokladnicou (ERP, teda pokladnicou používanou pred súčasnou eKasa legislatívou) | poradové číslo pokladničného dokladu |
## Sadzba DPH (`vatRate`)
Číselná hodnota s presnosťou na dve desatinné miesta, alebo `null` pre položku nepodliehajúcu DPH.
### Platné sadzby podľa časových období
Vývoj sadzieb DPH používaných v SR od začiatku projektu eKasa (1. 4. 2019):
| Sadzba DPH | Do 31. 12. 2024 | Od 1. 1. 2025 |
|---|---|---|
| základná | 20 % | 23 % |
| znížené | 10 % | 19 % a 5 % |
Okrem základnej a znížených sadzieb, ktoré sa v čase môžu meniť, sa používajú fixné hodnoty:
| Hodnota | Použitie | .NET knižnica |
|---|---|---|
| `0` | položky oslobodené od DPH, alebo evidencia tržieb podnikateľa, ktorý nie je platiteľom DPH | `VatRate.Zero` |
| `null` | položky nepodliehajúce DPH (v súčasnosti návrat a predaj vratných obalov) | `VatRate.None` |
### Povolené hodnoty sadzby DPH
Povolené sadzby závisia od typu položky, zámeru jej využitia a dátumu vyhotovenia dokladu (pri registrácii paragónu
alebo paragónu pri úhrade faktúry je rozhodujúca hodnota `issueDate`):
| Typ položky | Do 31. 12. 2024 | Od 1. 1. 2025 |
|---|---|---|
| `positive` | `20`, `10`, `0`, `null` | `23`, `20`\*, `19`, `10`\*, `5`, `0`, `null` |
| `discount` | `20`, `10`, `0`, `null`\*\* | `23`, `19`, `5`, `0`, `null`\*\* |
| `returnedContainer` | `null` | `null` |
| `returned` | `20`, `10`, `0` | `23`, `20`, `19`, `10`, `5`, `0` |
| `advance` | `20`, `10`, `0` | `23`, `20`, `19`, `10`, `5`, `0` |
| `voucher` | `20`, `10`, `0` | `23`, `20`, `19`, `10`, `5`, `0` |
| `correction` | `20`, `10`, `0`, `null` | `23`, `20`, `19`, `10`, `5`, `0`, `null` |
\* iba ak sa na doklade nachádza aj položka typu `returned` (od verzie `7.0.1`)
\*\* od verzie `7.0.6`
**Zľava (`discount`)** sa uplatňuje „v reálnom čase“, musí preto používať aktuálne platné sadzby DPH. Zľavu na
položky nepodliehajúce DPH je možné od verzie `7.0.6` evidovať so sadzbou `null`.
**Kladná položka (`positive`)** sa používa v rôznych situáciách a od každej sa odvíja iná sada povolených sadzieb:
| Kladná položka znamená | Povolené sadzby |
|---|---|
| predaj tovaru alebo služby | predaj sa realizuje „v reálnom čase“, preto iba aktuálne platné sadzby: `20`, `10` a `0` pred 1. 1. 2025, resp. `23`, `19`, `5` a `0` od 1. 1. 2025 |
| predaj vratných obalov | `null` (položka nepodlieha DPH) |
| vrátenie zľavy | od verzie `7.0.1` okrem aktuálnych aj historické sadzby; na doklade musí byť aspoň jedna ďalšia položka evidujúca návrat (`returned`) |
Vrátenie zľavy v kladnej položke využijete, ak ste na pôvodnom doklade evidovali k predanému tovaru (`positive`) aj
zľavu (`discount`) na samostatnom riadku a teraz evidujete návrat tohto tovaru. Doklad kombinuje vrátenie tovaru
(`returned`) a vrátenie zľavy ako položku typu `positive`, pretože vrátenie zľavy sa eviduje v kladnej hodnote a typ
`discount` umožňuje iba záporné ceny. Že kladná položka eviduje vrátenie zľavy, overuje eKasa tak, že na doklade
vyžaduje aspoň jednu položku `returned`.
**Vratné obaly** (predaj `positive` aj výkup `returnedContainer`) sa evidujú ako položky nepodliehajúce DPH, `vatRate`
musí byť `null` (`VatRate.None` v .NET knižnici).
**Ostatné položky** (`returned`, `advance`, `voucher`, `correction`) môžu mať všetky aktuálne aj historicky platné
sadzby, vždy však sadzbu pôvodnej operácie:
| Typ položky | Sadzba musí byť rovnaká ako pri | 20 % alebo 10 % je povolená aj vtedy, ak |
|---|---|---|
| `returned` | evidencii predaja | predaj bol pred 1. 1. 2025 |
| `advance` | evidencii prijatia zálohy | záloha bola prijatá pred 1. 1. 2025 |
| `voucher` | evidencii predaja jednoúčelového poukazu | predaj poukazu bol zaevidovaný pred 1. 1. 2025 |
| `correction` | pôvodnej položke | pôvodná položka bola zaevidovaná pred 1. 1. 2025 |
Pri nesprávnej sadzbe DPH vráti eKasa validačnú chybu, napríklad: _Sadzba DPH 23,00% nie je platná pre doklad
s dátumom vyhotovenia 11. 11. 2024_.
## Dôvod nulovej sadzby (`specialRegulation`)
Príznak, ktorý bližšie určuje dôvod priradenia sadzby dane s hodnotou 0, ak takáto bola položke priradená. Je
nepovinný, a to aj pri položkách s nulovou sadzbou.
Uviesť ho možno iba pri položke so sadzbou `0` alebo bez DPH (`null`), ak predstavuje niektorú z týchto možností
(v .NET knižnici enum `TaxFreeReason`):
| Hodnota | Význam |
|---|---|
| `VATReverseCharge` | prenesenie daňovej povinnosti |
| `VATExemptionGood` | oslobodenie položky od dane |
| `TravelAgency` | osobitná úprava uplatňovania dane pri cestovných kanceláriách |
| `UsedGood` | osobitná úprava uplatňovania dane pri použitom tovare |
| `Artwork` | osobitná úprava uplatňovania dane pri umeleckých dielach |
| `CollectiblesAndAntiques` | osobitná úprava uplatňovania dane pri zberateľských predmetoch a starožitnostiach |
## Predávajúci (`seller`)
Nepovinný. Uvádza sa iba vtedy, ak predávajúci, v ktorého mene bol predaný tovar alebo poskytnutá služba, je iný ako
podnikateľský subjekt priradený k on-line registračnej pokladnici.
| Pole | Povinné | Hodnoty |
|---|:---:|---|
| `id` | áno | identifikátor predávajúceho, v ktorého mene bol predaný tovar alebo poskytnutá služba |
| `type` | áno | typ identifikátora, pozri tabuľku nižšie |
| `type` | Identifikátor | Formát `id` |
|---|---|---|
| `DIC` | DIČ | `^[0-9]{10}$`, presne 10 číslic |
| `ICDPH` | IČ DPH | `^SK[0-9]{8,10}$`, písmená SK a za nimi 8 až 10 číslic; prijme sa aj samotné 10-miestne DIČ |
## Číslo poukazu (`voucherNumber`)
Číslo jednoúčelového poukazu pri jeho výmene za tovar alebo poskytnutú službu. Text s dĺžkou 1 až 50 znakov.
| Typ položky | `voucherNumber` |
|---|---|
| `voucher` | povinné |
| `correction` | možno uviesť |
| ostatné | musí byť `null` |
## Popis položky (`description`)
Nepovinný dodatočný popis, ktorý sa vytlačí na doklade hneď za názvom produktu a údajmi o množstve a cenách. Slúži
napríklad na dátum spotreby alebo sériové číslo výrobku. Do systému eKasa sa neodosiela.
Popis podporuje tokeny na formátovanie a tlač QR a čiarových kódov, pozri
[Tokeny a formátovanie textu](https://ekasa.ninedigit.sk/docs/token-syntax), napríklad
[sériové číslo ako čiarový kód](https://ekasa.ninedigit.sk/docs/token-syntax#s%C3%A9riov%C3%A9-%C4%8D%C3%ADslo-v%C3%BDrobku-v-popise-polo%C5%BEky).
## Kam ďalej
- [Zľavy](https://ekasa.ninedigit.sk/docs/receipt-registration/discounts): Zľava na položku a na celý doklad.
- [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections): Oprava dokladu, vrátenie tovaru a úhrady faktúry.
- [Platby a zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments): Platidlá a zaokrúhlenie hotovosti.
---
# Platby a zaokrúhľovanie
> Zoznam platieb na doklade, názvy platidiel a zaokrúhľovanie sumy pri platbe v hotovosti.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/payments
Platby (`payments`) hovoria, čím zákazník zaplatil: hotovosťou, platobnou kartou, stravnými lístkami alebo ich
kombináciou. Zoznam platieb je nepovinný a na servery finančnej správy sa neodosiela.
Pri platbe v hotovosti sa suma zaokrúhľuje na 5 centov, aby sa obmedzilo používanie 1- a 2-centových mincí.
Zaokrúhlenie uvádzate vo vlastnosti `roundingAmount`.
- [Platby](#platby-payments): Názov platidla, suma a pravidlá pre zoznam platieb.
- [Zaokrúhľovanie](#zaokrúhľovanie): Pravidlo zaokrúhľovania a vlastnosť roundingAmount.
- [Príklady](#príklady): Hotovosť, karta, kombinácia platidiel a úhrada faktúry.
- [Tabuľka zaokrúhľovania](#tabuľka-zaokrúhľovania): Suma pred a po zaokrúhlení, cent po cente.
## Platby (`payments`)
Váš softvér zoznam platieb vypĺňať nemusí. Ak platby uvedie, platí:
| Pravidlo | Hodnota |
|---|---|
| súčet platieb | rovný alebo vyšší ako celková suma dokladu, teda súčet položiek (`items`) a zaokrúhlenia (`roundingAmount`) |
| počet platieb | najviac `500` |
Každá platba sa skladá z dvojice vlastností:
| Vlastnosť | Povinná | Hodnoty |
|---|:---:|---|
| `name` | áno | názov (slovný popis) platidla, 1 až 255 znakov |
| `amount` | áno | peňažný obnos platby s presnosťou na 2 desatinné miesta |
**Príklad:** zákazník v kaviarni kúpi 2 × cappuccino a cheesecake za 9,30 € a zaplatí 10,00 € v hotovosti. Vydaných
0,70 € je druhá platba so zápornou sumou.
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Cappuccino",
"quantity": {
"amount": 2,
"unit": "ks"
},
"unitPrice": 2.90,
"price": 5.80,
"vatRate": 19
},
{
"type": "positive",
"name": "Cheesecake",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 3.50,
"price": 3.50,
"vatRate": 5
}
],
"payments": [
{
"name": "Hotovosť",
"amount": 10.00
},
{
"name": "Hotovosť",
"amount": -0.70
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Positive, "Cappuccino", 2.90m, new Quantity(2, "ks"), 19m),
new ReceiptItem(ReceiptItemType.Positive, "Cheesecake", 3.50m, new Quantity(1, "ks"), 5m)
};
var receipt = new CashRegisterReceipt("88812345678900001", items)
{
Payments = new ReceiptPayments
{
new ReceiptPayment("Hotovosť", 10.00m),
new ReceiptPayment("Hotovosť", -0.70m)
}
};
RegisterReceiptResult result = await client.RegisterReceiptAsync(
new RegisterCashRegisterReceiptRequest(receipt),
RegisterReceiptPrintContext.CreatePos(),
cancellationToken);
```
## Zaokrúhľovanie
Od 1. 7. 2022 platí zmena zákona o cenách, ktorá priniesla povinné zaokrúhľovanie s cieľom obmedziť používanie
1- a 2-eurocentových mincí. Cena platená v hotovosti sa zaokrúhľuje na 5 eurocentov:
- zvyšok nižší ako polovica z 5 eurocentov sa zaokrúhľuje **nadol**,
- zvyšok rovný alebo vyšší ako polovica z 5 eurocentov sa zaokrúhľuje **nahor**,
- cena v hotovosti 1 alebo 2 eurocenty sa zaokrúhľuje na 5 eurocentov.
Podľa poslednej číslice sumy v hotovosti to znamená:
| Posledná číslica | Zaokrúhli sa | `roundingAmount` |
|---|---|---|
| 0, 5 | nezaokrúhľuje sa | `0` |
| 1, 2 | nadol na 0 | `-0.01`, `-0.02` |
| 3, 4 | nahor na 5 | `0.02`, `0.01` |
| 6, 7 | nadol na 5 | `-0.01`, `-0.02` |
| 8, 9 | nahor na 0 | `0.02`, `0.01` |
| celá suma 0,01 € alebo 0,02 € | nahor na 0,05 € | `0.04`, `0.03` |
- **Zaokrúhľuje sa iba čiastka platená v hotovosti.** Časť dokladu hradená bezhotovostne (platobnou kartou, stravnými
lístkami atď.) sa nezaokrúhľuje.
- **DPH sa vypočíta zo sumy pred zaokrúhlením.** Zaokrúhľovanie pri platbe v hotovosti tak nemá vplyv na výpočet DPH
z nákupu tovaru.
Ako určiť `roundingAmount`, keď zákazník platí v hotovosti celú sumu alebo jej časť:
1. **Sčítajte položky**
Dostanete nezaokrúhlenú cenu nákupu.
2. **Odpočítajte bezhotovostné platby**
Platobná karta, stravné lístky a pod. Zvyšok je cena platená v hotovosti.
3. **Zaokrúhlite cenu v hotovosti na 5 centov**
Rozdiel medzi zaokrúhlenou a nezaokrúhlenou cenou je `roundingAmount`.
### Vlastnosť `roundingAmount`
| Vlastnosť | Povinná | Hodnoty | Predvolená |
|---|:---:|---|---|
| `roundingAmount` | nie | číslo od `-0.04` do `0.04` s presnosťou na 2 desatinné miesta | `0` |
Vlastnosť majú všetky typy dokladov, ktoré eKasa eviduje. Celková suma dokladu sa počíta podľa typu dokladu:
| Typ dokladu | Identifikátor | `roundingAmount` | Celková suma dokladu |
|---|---|---|---|
| Pokladničný doklad | `CashRegister` | áno | súčet položiek (`items`) + `roundingAmount` |
| Paragón | `Paragon` | áno | súčet položiek (`items`) + `roundingAmount` |
| Faktúra (úhrada faktúry) | `Invoice` | áno, od verzie 5.24 | `amount + roundingAmount` |
| Paragón pri úhrade faktúry | `InvoiceParagon` | áno, od verzie 5.24 | `amount + roundingAmount` |
Pri úhrade faktúry uvádzate v poli `amount` uhrádzanú sumu pred zaokrúhlením a eKasa k nej pripočíta `roundingAmount`.
### Príklady
#### Príklad 1: úhrada v hotovosti
Espresso a croissant za 3,28 € zákazník platí v hotovosti, suma sa preto zaokrúhli: k 3,28 € doplníte zaokrúhlenie
`roundingAmount` 0,02 €, výsledná suma účtu je 3,30 €. DPH sa počíta z 3,28 €.
[Obrázok: Doklad: Espresso 1,99 €, Croissant 1,29 €, zaokrúhlenie +0,02, suma 3,30 EUR, hotovosť 3,30, obrat v sadzbe 19 % 1,99 a v sadzbe 5 % 1,29; zvýraznený je riadok zaokrúhlenia]
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Espresso",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 19
},
{
"type": "positive",
"name": "Croissant",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 1.29,
"price": 1.29,
"vatRate": 5
}
],
"roundingAmount": 0.02,
"payments": [
{
"name": "Hotovosť",
"amount": 3.30
}
]
}
}
}
```
#### Príklad 2: úhrada bezhotovostne
Ak zákazník zaplatí celý nákup bezhotovostne, cena sa nezaokrúhľuje: `roundingAmount` je `0`.
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Espresso",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 19
},
{
"type": "positive",
"name": "Croissant",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 1.29,
"price": 1.29,
"vatRate": 5
}
],
"roundingAmount": 0,
"payments": [
{
"name": "Karta",
"amount": 3.28
}
]
}
}
}
```
#### Príklad 3: úhrada kombináciou platidiel
Pri kombinácii hotovosti a iných platidiel sa zaokrúhľuje iba cena hradená v hotovosti.
Nákup v potravinách stojí 15,53 €. Kupujúci chce zaplatiť dvomi stravnými lístkami po 6,00 €, spolu 12,00 €, a zvyšok
doplatiť v hotovosti. Stravné lístky nie sú hotovosť, ich hodnota sa odpočíta z nezaokrúhlenej ceny nákupu:
| | Suma |
|---|---:|
| cena nákupu pred zaokrúhlením | 15,53 € |
| stravné lístky | −12,00 € |
| zvyšok platený v hotovosti | 3,53 € |
| hotovosť po zaokrúhlení (matematicky nahor), kupujúci doplatí | **3,55 €** |
| `roundingAmount` | 0,02 € |
| výsledná cena nákupu po zaokrúhlení | **15,55 €** |
[Obrázok: Doklad: Rožok, Mlieko polotučné, Čaj ovocný a Káva mletá spolu 15,53 €, zaokrúhlenie +0,02, suma 15,55 EUR, stravné lístky 12,00, hotovosť 3,55; zvýraznené sú zaokrúhlenie a platby]
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Rožok",
"quantity": {
"amount": 4,
"unit": "ks"
},
"unitPrice": 0.12,
"price": 0.48,
"vatRate": 5
},
{
"type": "positive",
"name": "Mlieko polotučné 1 l",
"quantity": {
"amount": 3,
"unit": "ks"
},
"unitPrice": 1.09,
"price": 3.27,
"vatRate": 5
},
{
"type": "positive",
"name": "Čaj ovocný 20 × 2 g",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 2.79,
"price": 2.79,
"vatRate": 19
},
{
"type": "positive",
"name": "Káva mletá 500 g",
"quantity": {
"amount": 1,
"unit": "ks"
},
"unitPrice": 8.99,
"price": 8.99,
"vatRate": 19
}
],
"roundingAmount": 0.02,
"payments": [
{
"name": "Stravné lístky",
"amount": 12.00
},
{
"name": "Hotovosť",
"amount": 3.55
}
]
}
}
}
```
Odpoveď (skrátená):
```json
{
"request": {
"data": {
"amount": 15.55,
"roundingAmount": 0.02
}
}
}
```
#### Príklad 4: úhrada faktúry v hotovosti
Zákazník platí v hotovosti faktúru na 246,37 €. Suma sa zaokrúhli nadol na 246,35 €, zaokrúhlenie je −0,02 €.
V poli `amount` je suma faktúry pred zaokrúhlením, celková suma dokladu bude 246,35 €.
```http
POST {server_address}/api/v1/requests/receipts/invoice
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"invoiceNumber": "FA-2026-0142",
"amount": 246.37,
"roundingAmount": -0.02,
"payments": [
{
"name": "Hotovosť",
"amount": 246.35
}
]
}
}
}
```
### Tabuľka zaokrúhľovania
Platená cena v hotovosti pred zaokrúhlením a po ňom:
| Pred zaokrúhlením | Po zaokrúhlení | `roundingAmount` | Poznámka |
|---:|---:|---:|---|
| 0,01 € | 0,05 € | `0.04` | cena do 0,02 € vrátane, ktorá by sa matematicky zaokrúhlila na 0,00 €, sa zaokrúhli nahor na 0,05 € |
| 0,02 € | 0,05 € | `0.03` | cena do 0,02 € vrátane, ktorá by sa matematicky zaokrúhlila na 0,00 €, sa zaokrúhli nahor na 0,05 € |
| 0,03 € | 0,05 € | `0.02` | matematické zaokrúhlenie |
| 0,04 € | 0,05 € | `0.01` | matematické zaokrúhlenie |
| 0,05 € | 0,05 € | `0` | nezaokrúhľuje sa |
| 0,06 € | 0,05 € | `-0.01` | matematické zaokrúhlenie |
| 0,07 € | 0,05 € | `-0.02` | matematické zaokrúhlenie |
| 0,08 € | 0,10 € | `0.02` | matematické zaokrúhlenie |
| 0,09 € | 0,10 € | `0.01` | matematické zaokrúhlenie |
| 0,10 € | 0,10 € | `0` | nezaokrúhľuje sa |
| 0,11 € | 0,10 € | `-0.01` | matematické zaokrúhlenie |
| 0,12 € | 0,10 € | `-0.02` | matematické zaokrúhlenie |
| 0,13 € | 0,15 € | `0.02` | matematické zaokrúhlenie |
| 0,14 € | 0,15 € | `0.01` | matematické zaokrúhlenie |
| 0,15 € | 0,15 € | `0` | nezaokrúhľuje sa |
| 0,16 € | 0,15 € | `-0.01` | matematické zaokrúhlenie |
| 0,17 € | 0,15 € | `-0.02` | matematické zaokrúhlenie |
| 0,18 € | 0,20 € | `0.02` | matematické zaokrúhlenie |
| 0,19 € | 0,20 € | `0.01` | matematické zaokrúhlenie |
| 0,20 € | 0,20 € | `0` | nezaokrúhľuje sa |
| … | … | … | … |
Viac informácií o zaokrúhľovaní:
- [Tlačová správa ministerstva financií](https://www.mfsr.sk/sk/media/tlacove-spravy/novela-zakona-cenach.html)
- [Návrh zákona](https://www.slov-lex.sk/legislativne-procesy/SK/LP/2021/14)
## Kam ďalej
- [Vyhotovenie dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/printing): Papier, PDF alebo e-mail a vlastné texty.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Číslo dokladu, identifikátor a rekapitulácia DPH.
- [Zľavy](https://ekasa.ninedigit.sk/docs/receipt-registration/discounts): Zľava na položku a na celý doklad.
---
# Zľavy
> Ako zaevidovať zľavu na položku aj na celý doklad: dvojica položka a zľava, pravidlá sadzieb DPH a limit sumy zliav.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/discounts
Zľava sa na doklade eviduje ako samostatná položka typu `discount` so zápornou cenou. Odporúčame ju vždy uviesť
**hneď za položkou, ktorej sa týka**, aj keď zákazník dostal zľavu na celý nákup.
## Prečo dvojica položka a zľava
Zákazník, ktorý nakupuje pre firmu, si z dokladu zisťuje obstarávaciu cenu každej položky. Ak je pri každej položke
jej zľava, cena po zľave je hneď jasná. Ak sú zľavy sčítané na konci dokladu, zákazník ich musí rozpočítať sám.
**Odporúčame:** zľava hneď pod položkou
[Obrázok: Výrez dokladu: káva, pod ňou zľava −0,40, koláč, pod ním zľava −0,30]
**Neodporúčame:** zľavy na konci dokladu
[Obrázok: Výrez dokladu: káva a koláč, pod nimi dve zľavy −0,40 a −0,30]
## Pravidlá
- Zľava má typ `discount`, zápornú `unitPrice` aj `price` a množstvo `1`.
- Zľava má **rovnakú sadzbu DPH** ako položka, ktorej sa týka. Zľavy sa poskytujú pri predaji, preto môžu mať len
aktuálne platné sadzby (`23`, `19`, `5`, `0`, prípadne `null`).
- Súčet zliav (v absolútnej hodnote) v jednej sadzbe DPH nesmie byť vyšší ako súčet položiek s kladnou cenou
v tej istej sadzbe. Inak eKasa vráti chybu `Suma zliav nesmie presiahnúť sumu ostatných evidovaných položiek dokladu
v rovnakej sadzbe DPH.`
## Zľava na položku
Vernostná zľava 1 € na dve kolové nápoje:
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": { "amount": 2, "unit": "ks" },
"unitPrice": 1.99,
"price": 3.98,
"vatRate": 23.00
},
{
"type": "discount",
"name": "Vernostná zľava",
"quantity": { "amount": 1 },
"unitPrice": -1.00,
"price": -1.00,
"vatRate": 23.00
}
],
"payments": [
{ "name": "Platobná karta", "amount": 2.98 }
]
}
}
}
```
## Zľava na celý doklad
Zľavu na celý nákup rozpočítajte na jednotlivé položky a každú uveďte za jej položkou. Príklad: 10 % zľava na nákup
za 7 € v dvoch sadzbách DPH.
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Káva",
"quantity": { "amount": 1, "unit": "ks" },
"unitPrice": 4.00,
"price": 4.00,
"vatRate": 23.00
},
{
"type": "discount",
"name": "Zľava 10 % na nákup",
"quantity": { "amount": 1 },
"unitPrice": -0.40,
"price": -0.40,
"vatRate": 23.00
},
{
"type": "positive",
"name": "Koláč",
"quantity": { "amount": 1, "unit": "ks" },
"unitPrice": 3.00,
"price": 3.00,
"vatRate": 19.00
},
{
"type": "discount",
"name": "Zľava 10 % na nákup",
"quantity": { "amount": 1 },
"unitPrice": -0.30,
"price": -0.30,
"vatRate": 19.00
}
],
"payments": [
{ "name": "Platobná karta", "amount": 6.30 }
]
}
}
}
```
Pri rozpočítaní percentuálnej zľavy môžu vzniknúť zaokrúhľovacie rozdiely. Rozdiel pripočítajte k zľave poslednej
položky, aby súčet zliav sedel s celkovou zľavou.
Zľavu môžete uviesť aj súhrnne, jednou položkou `discount` za každú sadzbu DPH na konci dokladu. eKasa takýto doklad
prijme, no zákazník z neho nezistí cenu jednotlivých položiek po zľave.
## Vrátenie tovaru so zľavou
Pri vrátení tovaru, na ktorý bola poskytnutá zľava, vráťte tovar položkou `returned` a zľavu kladnou položkou
`positive` v sadzbe pôvodnej zľavy. Podrobnosti sú v článkoch [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections)
a [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items).
## Kam ďalej
- [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items): Typ položky, cena, množstvo a sadzba DPH.
- [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections): Oprava dokladu, vrátenie tovaru a úhrady faktúry.
- [Poukazy](https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers): Jednoúčelový a viacúčelový poukaz.
---
# Storno a vrátenie
> Oprava zaevidovaného dokladu: storno, vrátenie tovaru, vrátenie úhrady faktúry a dobropis.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/corrections
Zaevidovaný doklad sa nedá zmeniť ani zmazať. Chybu alebo vrátenie tovaru opravíte **novým dokladom**, ktorý sa
odvolá na pôvodný.
Oprava dokladu môže mať rôzne príčiny, a preto sa aj jej registrácia v systéme eKasa líši. Tento článok popisuje
situácie, ktoré pri opravách dokladov môžu nastať, a postup pre každú z nich.
## Ktorý postup použiť
| Situácia | Postup | Nový doklad | Typ položky |
|---|---|---|---|
| obsluha pokladnice vykonala omyl | [Storno dokladu](#storno-dokladu) | `cash_register` | `correction` |
| zákazník vracia zakúpený tovar | [Vrátenie tovaru](#vrátenie-tovaru) | `cash_register` | `returned` |
| zákazník uhradil faktúru v hotovosti a túto úhradu treba vrátiť | [Vrátenie úhrady faktúry](#vrátenie-úhrady-faktúry) | `cash_register` | `correction` |
| dobropisovanie faktúry uhradenej inak ako v hotovosti (napr. prevodom na účet) | [Dobropis faktúry](#dobropis-faktúry) | `invoice` so zápornou sumou | bez položiek |
Pri storne, vrátení tovaru aj vrátení úhrady faktúry sa každá opravná položka odvoláva na pôvodný doklad v poli
`referenceReceiptId`: uvediete v ňom unikátny identifikátor (alebo `OKP`) pôvodného dokladu. Kde ho nájdete, je
v článku [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result).
## Storno dokladu
Ak treba opraviť už vyhotovený doklad (storno dokladu, vrátenie tovaru a podobne), zaregistrujete nový doklad.
Budú v ňom tie položky dokladu, ktoré majú byť opravené, s týmito rozdielmi:
| Pole položky | Hodnota v novom doklade |
|---|---|
| `type` | `correction` namiesto pôvodného typu |
| `unitPrice`, `price` | pôvodné ceny vynásobené `-1`, aby vznikol opačný obrat |
| `referenceReceiptId` | unikátny identifikátor (alebo `OKP`) pôvodného dokladu |
### Príklad
Pôvodný doklad: dve Coca Coly po 1,99 € s vernostnou zľavou 1 €, spolu 2,98 € v hotovosti. Storno doklad obsahuje
obe položky ako `correction` s opačnými cenami a odvolá sa na identifikátor pôvodného dokladu (`UID` na jeho spodku).
**Pôvodný doklad**
[Obrázok: Pôvodný doklad: Coca Cola 2 ks po 1,99 €, vernostná zľava −1,00 €, suma 2,98 € v hotovosti]
**Storno doklad**
[Obrázok: Storno doklad: Coca Cola −3,98 € a vernostná zľava 1,00 € s identifikátorom pôvodného dokladu, suma −2,98 €]
Pôvodný doklad:
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 3.98,
"vatRate": 23.00
},
{
"type": "discount",
"name": "Vernostná zľava",
"quantity": {
"amount": 1.00
},
"unitPrice": -1.00,
"price": -1.00,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": 2.98
}
]
}
}
}
```
Storno doklad:
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "correction",
"referenceReceiptId": "O-40198CCAA6D54C46998CCAA6D56-TEST",
"name": "Coca Cola",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": -1.99,
"price": -3.98,
"vatRate": 23.00
},
{
"type": "correction",
"referenceReceiptId": "O-40198CCAA6D54C46998CCAA6D56-TEST",
"name": "Vernostná zľava",
"quantity": {
"amount": 1.00
},
"unitPrice": 1.00,
"price": 1.00,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": -2.98
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var original = "O-40198CCAA6D54C46998CCAA6D56-TEST";
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Correction, "Coca Cola", -1.99m, new Quantity(2, "ks"), 23m,
referenceReceiptId: original),
new ReceiptItem(ReceiptItemType.Correction, "Vernostná zľava", 1.00m, 1, 23m,
referenceReceiptId: original)
};
var receipt = new CashRegisterReceipt("88812345678900001", items)
{
Payments = new ReceiptPayments { new ReceiptPayment("Hotovosť", -2.98m) }
};
RegisterReceiptResult result = await client.RegisterReceiptAsync(
new RegisterCashRegisterReceiptRequest(receipt),
RegisterReceiptPrintContext.CreatePos(),
cancellationToken);
```
## Vrátenie tovaru
Ak zákazník vráti zakúpený tovar, zaregistrujete nový doklad s tými položkami dokladu, ktoré sú vrátené:
| Pole položky | Hodnota v novom doklade |
|---|---|
| `type` | `returned` namiesto pôvodného typu |
| `quantity.amount` | počet vrátených jednotiek, kladné číslo |
| `unitPrice`, `price` | záporné, ako v príkladoch nižšie |
| `referenceReceiptId` | unikátny identifikátor (alebo `OKP`) pôvodného dokladu |
Ak sa na položku vzťahuje zľava, máte dve možnosti:
| Možnosť | Ako | Príklad |
|---|---|---|
| spojiť položku so zľavou | pôvodnú kladnú položku a prislúchajúcu zľavu vrátite ako jednu položku `returned`, ktorej celková suma sa rovná súčtu ceny kladnej položky a výšky prislúchajúcej zľavy | [Príklad č.1](#príklad-č1) |
| vrátiť zľavu samostatne | položku zľavy zaregistrujete ako kladnú položku (`positive`) | [Príklad č.2](#príklad-č2) |
V oboch príkladoch zákazník vracia tovar z rovnakého pôvodného dokladu ako pri [storne](#príklad): dve Coca Coly
po 1,99 € s vernostnou zľavou 1 €, spolu 2,98 € v hotovosti.
### Príklad č.1
Coca Cola a zľava v jednej vrátenej položke: 2 ks po −1,49 €, spolu −2,98 € (−3,98 € + 1,00 €).
**Pôvodný doklad**
[Obrázok: Pôvodný doklad: Coca Cola 2 ks po 1,99 €, vernostná zľava −1,00 €, suma 2,98 € v hotovosti]
**Doklad s vrátením tovaru**
[Obrázok: Doklad s vrátením tovaru: Coca Cola −2 ks po 1,49 €, suma −2,98 €, s identifikátorom pôvodného dokladu]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "returned",
"referenceReceiptId": "O-40198CCAA6D54C46998CCAA6D56-TEST",
"name": "Coca Cola",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": -1.49,
"price": -2.98,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": -2.98
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Returned, "Coca Cola", -1.49m, new Quantity(2, "ks"), 23m,
referenceReceiptId: "O-40198CCAA6D54C46998CCAA6D56-TEST")
};
```
Doklad zaregistrujete rovnako ako pri [storne](#príklad), s platbou `new ReceiptPayment("Hotovosť", -2.98m)`.
### Príklad č.2
Coca Cola ako vrátená položka za pôvodnú cenu a vernostná zľava vrátená ako kladná položka „Vrátenie zľavy“.
Podrobnosti o sadzbách DPH pri vrátení zľavy sú v článku [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items).
**Pôvodný doklad**
[Obrázok: Pôvodný doklad: Coca Cola 2 ks po 1,99 €, vernostná zľava −1,00 €, suma 2,98 € v hotovosti]
**Doklad s vrátením tovaru**
[Obrázok: Doklad s vrátením tovaru: Coca Cola −3,98 € s identifikátorom pôvodného dokladu a vrátenie zľavy 1,00 €, suma −2,98 €]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "returned",
"referenceReceiptId": "O-40198CCAA6D54C46998CCAA6D56-TEST",
"name": "Coca Cola",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": -1.99,
"price": -3.98,
"vatRate": 23.00
},
{
"type": "positive",
"name": "Vrátenie zľavy",
"quantity": {
"amount": 1.00
},
"unitPrice": 1.00,
"price": 1.00,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": -2.98
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Returned, "Coca Cola", -1.99m, new Quantity(2, "ks"), 23m,
referenceReceiptId: "O-40198CCAA6D54C46998CCAA6D56-TEST"),
new ReceiptItem(ReceiptItemType.Positive, "Vrátenie zľavy", 1.00m, 1, 23m)
};
```
Doklad zaregistrujete rovnako ako pri [storne](#príklad), s platbou `new ReceiptPayment("Hotovosť", -2.98m)`.
## Vrátenie úhrady faktúry
Hotovostnú úhradu faktúry zaregistrovanú cez systém eKasa dokladom typu `invoice` vrátite podobne ako tovar:
vytvoríte pokladničný doklad (typ `cash_register`) s touto položkou:
| Pole položky | Hodnota |
|---|---|
| `type` | `correction` |
| `unitPrice`, `price` | záporná suma pôvodnej hotovostnej úhrady faktúry |
| `referenceReceiptId` | identifikátor pôvodného dokladu, teda úhrady faktúry |
| `name` | napríklad „Vrátenie úhrady faktúry číslo …“ |
**Hotovostná úhrada faktúry**
[Obrázok: Doklad úhrady faktúry FA-0001 na 189,90 €]
**Vrátenie úhrady faktúry**
[Obrázok: Doklad s položkou Vrátenie úhrady faktúry číslo FA-0001 −189,90 € s identifikátorom úhrady faktúry]
Hotovostná úhrada faktúry:
```http
POST {server_address}/api/v1/requests/receipts/invoice
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"invoiceNumber": "FA-0001",
"amount": 189.90
}
}
}
```
Vrátenie hotovostnej úhrady faktúry:
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "correction",
"referenceReceiptId": "O-69EAABF5BE2B465BAAABF5BE2BC-TEST",
"name": "Vrátenie úhrady faktúry číslo FA-0001",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": -189.90,
"price": -189.90,
"vatRate": 0.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": -189.90
}
]
}
}
}
```
**.NET knižnica:**
```csharp
var items = new ReceiptItems
{
new ReceiptItem(ReceiptItemType.Correction, "Vrátenie úhrady faktúry číslo FA-0001",
-189.90m, new Quantity(1, "ks"), 0m,
referenceReceiptId: "O-69EAABF5BE2B465BAAABF5BE2BC-TEST")
};
var receipt = new CashRegisterReceipt("88812345678900001", items)
{
Payments = new ReceiptPayments { new ReceiptPayment("Hotovosť", -189.90m) }
};
```
## Dobropis faktúry
Faktúru, ktorá nebola uhradená cez systém eKasa, a teda k nej neexistuje pokladničný doklad úhrady faktúry
s unikátnym identifikátorom, dobropisujete ako hotovostnú úhradu faktúry (doklad typu `invoice`) so záporným
znamienkom.
[Obrázok: Doklad úhrady faktúry FA-0001 so sumou −189,90 €]
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/invoice
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"invoiceNumber": "FA-0001",
"amount": -189.90
}
}
}
```
**.NET knižnica:**
```csharp
var creditNote = new InvoiceReceipt("88812345678900001", "FA-0001", -189.90m);
RegisterReceiptResult result = await client.RegisterReceiptAsync(
new RegisterInvoiceReceiptRequest(creditNote),
RegisterReceiptPrintContext.CreatePos(),
cancellationToken);
```
## Kam ďalej
- [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items): Typy položiek a odkaz na pôvodný doklad.
- [Zľavy](https://ekasa.ninedigit.sk/docs/receipt-registration/discounts): Zľava na položku a na celý doklad.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Identifikátor dokladu, na ktorý sa oprava odvoláva.
---
# Poukazy
> Predaj a uplatnenie jednoúčelového a viacúčelového poukazu: kedy sa poukaz eviduje ako položka a kedy ako platidlo.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers
Pri poukazoch rozlišujte dva druhy:
- **Jednoúčelový poukaz**: pri predaji je známe miesto dodania aj sadzba DPH tovaru alebo služby, na ktorú sa
poukaz uplatní. Jeho predaj sa eviduje ako bežný predaj.
- **Viacúčelový poukaz**: všetky ostatné, napríklad darčeková karta na ľubovoľný tovar. Jeho predaj je predaj
ceniny a neeviduje sa, eviduje sa až nákup, pri ktorom sa poukaz uplatní.
## Jednoúčelový poukaz
Pre uplatnenie vopred zakúpeného jednoúčelového poukazu je potrebné do dokladu vložiť položku typu `Voucher` (jednoúčelový poukaz).
Ak je celková hodnota tohto poukazu vyššia ako suma ostatných položiek dokladu, výsledná suma dokladu je 0 €, nakoľko z hodnoty poukazu nie je možné vrátiť finančný rozdiel (platí od verzie 5.4).
V prípade, ak sa na doklade nachádza položka uplatnenia jednoúčelového poukazu (typ `Voucher`), na doklade sa okrem nej smú nachádzať iba položky typu `voucher`, `positive` alebo `discount`. Ostatné typy položiek nie sú v tomto prípade povolené.
Od verzie 5.6.3 do verzie 6.10.4 bolo vyžadované, aby kladná položka aj položka typu `Voucher` boli evidované v rovnakej sadzbe DPH.
Toto pravidlo bolo od verzie 7.0 odstránené v súvislosti so zmenou DPH od 1.1.2025, nakoľko ojedinele môže dôjsť k zmene sadzby na tovare/službe nie len v rámci základnej/zníženej sadzby, ale niektoré tovary/služby môžu prejsť aj zo základnej do zníženej. Preto je povolené evidovať tovar alebo službu, na ktorú sa JÚP vzťahuje, a samotný JÚP v rozdielnych sadzbách DPH (t. j. kríženie sadzieb je možné ľubovoľne).
**Príklad 1**: Podnikateľ prijal jednoúčelový poukaz na výmenu vo výške 20 € na nákup produktov. Kupujúci si za daný poukaz kúpil produkty v hodnote 18 €. V tomto prípade je hodnota zakúpeného tovaru nižšia ako hodnota poukazu a nakoľko z hodnoty poukazu nie je možné vrátiť finančný rozdiel, výsledná suma dokladu je 0 €.
**Príklad 2**: Podnikateľ prijal jednoúčelový poukaz na výmenu vo výške 50 € predaný v sadzbe DPH 23 %. Kupujúci nakúpil dva produkty, prvý v cene 60 € a sadzbe DPH 23 % a druhý v cene 40 € a sadzbe DPH 5 %. Výsledná suma dokladu je 50 € (100 € − 50 €). Od verzie 7.0 sa poukaz odpočíta od súčtu všetkých položiek bez ohľadu na ich sadzbu DPH.
Predaj jednoúčelového poukazu:
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [{
"type": "positive",
"name": "Predaj jednoúčelového poukazu",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 20.00,
"price": 20.00,
"vatRate": 23.00
}],
"payments": [{
"name": "Hotovosť",
"amount": 20
}]
}
}
}
```
Uplatnenie jednoúčelového poukazu (výsledná suma dokladu je 0 €):
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [{
"type": "positive",
"name": "Produkt",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 18.00,
"price": 18.00,
"vatRate": 23.00
}, {
"type": "voucher",
"name": "Uplatnenie poukazu 20 EUR",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": -20.00,
"price": -20.00,
"vatRate": 23.00,
"voucherNumber": "123456"
}],
"payments": [{
"name": "Hotovosť",
"amount": 0
}]
}
}
}
```
## Viacúčelový poukaz
**Predaj** viacúčelového poukazu neevidujte. Povinnosť evidovať tržbu sa nevzťahuje na predaj cenín okrem
jednoúčelového poukazu ([§ 3 ods. 2 písm. a) zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-2)), viacúčelový poukaz
je teda cenina. Podľa zákona o DPH ani nejde o dodanie tovaru či služby (§ 9a ods. 5,
[metodický pokyn finančnej správy](https://www.financnasprava.sk/_img/pfsedit/Dokumenty_PFS/Zverejnovanie_dok/Dane/Metodicke_pokyny/Nepriame_dane/2019/2019.09.27_16_DPH_2019_MP.pdf)). Ak by ste predaj zaevidovali, tá istá suma by sa započítala druhýkrát
pri uplatnení poukazu.
Dokladom pre zákazníka je spravidla samotný poukaz s hodnotou a číslom. Ak mu chcete vydať aj potvrdenie o predaji
z eKasy, vytlačte ho ako [nefiškálny doklad s cenou](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt#%C3%BAdaje-o-cene)
(`contentFlags: ["priceInformation"]`), aby bol v každom treťom riadku označený slovami „NEPLATNÝ DOKLAD“.
Zákon zakazuje odovzdať kupujúcemu iný doklad z pokladnice eKasa o prijatí tržby (§ 8 ods. 1). Finančná správa sa
k potvrdeniu o predaji viacúčelového poukazu výslovne nevyjadrila. Ak si nie ste istí, vydajte zákazníkovi len
samotný poukaz.
**Uplatnenie** poukazu je bežný predaj tovaru alebo služby. Doklad obsahuje položky v ich skutočných sadzbách DPH
a poukaz sa uvedie ako platidlo:
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Tričko",
"quantity": { "amount": 1, "unit": "ks" },
"unitPrice": 25.00,
"price": 25.00,
"vatRate": 23.00
}
],
"payments": [
{ "name": "Darčeková karta", "amount": 20.00 },
{ "name": "Hotovosť", "amount": 5.00 }
]
}
}
}
```
Riešenie je zjednodušené a nepokrýva všetky prípady z metodického pokynu. Pri nejasnostiach sa obráťte na podporu
finančnej správy alebo daňového poradcu.
## Kam ďalej
- [Nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt): Text s cenami a označenie NEPLATNÝ DOKLAD.
- [Platby a zaokrúhľovanie](https://ekasa.ninedigit.sk/docs/receipt-registration/payments): Platidlá na doklade.
- [Odpočet zálohy](https://ekasa.ninedigit.sk/docs/receipt-registration/advances): Záloha prijatá pred dodaním tovaru.
---
# Odpočet zálohy
> Odpočet prijatej zálohy pri dodaní tovaru alebo služby, aj keď sa medzitým zmenili sadzby DPH.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/advances
Prijatá záloha (preddavok) je tržba (§ 2 písm. u) zákona č. 384/2025 Z. z.). Pri jej prijatí ju zaevidujte kladnou
položkou (`positive`) v sadzbe DPH tovaru alebo služby, na ktorú sa záloha platí. Pri dodaní tovaru alebo služby sa
potom na doklade odpočíta.
Odpočet zálohy je realizovaný položkou dokladu s typom `advance`, ktorá má zápornú cenu.
Položku odpočtu zálohy uvádzame na rovnakom doklade, na ktorom je evidovaná kladná položka (`positive`) reprezentujúca tovar či službu, ku ktorej sa odpočet zálohy vzťahuje (platí od verzie 7).
V prípade, ak sa na doklade nachádza položka typu `advance` a žiadná iná kladná položka (`positive`), vyhlásená je chyba: _Odpočítaná záloha sa môže evidovať len v prípade, ak je na pokladničnom doklade evidovaná kladná položka_.
## Odpočet zálohy a dodanie tovaru naprieč zmenou sadzieb DPH
Nakoľko časť tovarov prechádza napríklad zo základnej sadzby (20% do 31.12.2024) do zníženej (po 1.1.2025 v 19%), môže tak vzniknúť situácia prijatia zálohy pred 1.1.2025 a dodania tovaru s následným doplatkom ceny po 1.1.2025.
Z uvedeného dôvodu eKasa povoľuje tzv. "kríženie sadzieb", kedy je prijatie zálohy a jej odpočet evidované v inej sadzbe DPH, než v akej je realizovaný predaj (doplatok) kladnej položky.
Kríženie sadzieb je povolené nielen v rámci rovnakej sadzby (napr základná sadzba 20% vs. základná sadzba 23%), ale aj medzi základnou a zníženou sadzbou.
> Pri uplatnení príslušnej sadzby dane pri zmene sadzieb tak, ako to upravuje zákon č. 278/2024 Z. z., ktorým sa menia a dopĺňajú niektoré zákony v súvislosti s ďalším zlepšovaním verejných financií (novela zákona o DPH účinná od 1.1.2025), **je rozhodujúcou skutočnosťou deň vzniku daňovej povinnosti. V prípade, že platiteľ prijal zálohu do 31.12.2024 na plnenie, ktoré bude poskytnuté (tovar alebo služba bude dodaná) po 31.12.2024, musí uplatniť sadzbu dane platnú v čase vzniku každej daňovej povinnosti, tzn. sadzbu dane platnú v čase prijatia preddavku (zálohy) a sadzbu dane platnú v čase dodania tovaru alebo služby na tú časť ceny plnenia, ktorú požaduje a ktorá nebola zahrnutá do prijatej zálohy. Daňová povinnosť totiž vzniká nielen dodaním tovaru alebo služby ale aj v zmysle § 19 ods. 4 zákona o DPH dňom prijatia platby vopred za dodanie tovaru alebo služby.**
>
> Ustanovenie § 85ko predmetnej novely upravuje situácie, keď dôjde po 1.1.2025 k oprave základu dane v zmysle § 25 ods. 1 zákona o DPH, tzn. k úplnému alebo čiastočnému zrušeniu dodávky tovaru alebo služby alebo k úplnému alebo čiastočnému vráteniu dodávky tovaru a k zníženiu alebo zvýšeniu ceny tovaru alebo služby, pri ktorých vznikla daňová povinnosť do 31.12.2024. V týchto prípadoch platiteľ vykonávajúci opravu základu dane podľa § 25 zákona o DPH použije sadzbu dane platnú v čase vzniku daňovej povinnosti, pričom je povinný vypočítať sumu opravenej dane pomerne podľa výšky, v akej sa znížený základ dane vzťahuje na každú vzniknutú daňovú povinnosť.
>
> Zdroj: FS SR
## Kam ďalej
- [Položky dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/items): Typ položky advance a sadzby DPH.
- [Poukazy](https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers): Jednoúčelový a viacúčelový poukaz.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Prehľad a všetky témy.
---
# Vyhotovenie dokladu
> Ako eKasa doklad vyhotoví: papierový doklad, PDF súbor alebo e-mail, offline režim a dodatočné texty na doklade.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/printing
Každý doklad eKasa vyhotoví: vytlačí ho, uloží ako PDF alebo pošle e-mailom. Spôsob určíte pri registrácii, inak sa doklad vyhotoví predvoleným spôsobom z nastavení (štandardne sa vytlačí).
Nadradená aplikácia má pri registrácii dokladu možnosť uviesť spôsob, akým bude doklad vyhotovený.
Elektronický doklad (PDF alebo e-mail) môžete kupujúcemu poskytnúť namiesto vytlačeného len vtedy, ak s tým kupujúci súhlasí a požiada o to pred vytlačením dokladu ([§ 8 ods. 1 zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-8.odsek-1)). Originál dokladu je vždy len jeden: buď vytlačený, alebo elektronický. Elektronický doklad musí kupujúci dostať hneď po zaplatení, rovnako ako vytlačený: zaslanie alebo sprístupnenie sa považuje za odovzdanie dokladu, a ten sa odovzdáva ihneď.
Určenie spôsobu vyhotovenia však nie je dovolené pri všetkých typoch dokladov, ako popisuje tabuľka nižšie.
| Typ dokladu | Identifikátor typu dokladu | možnosť určiť spôsob vyhotovenia |
|-----|-----|-----|
| Pokladničný doklad | `CashRegister` | Áno |
| Paragón | `Paragon` | Nie |
| Faktúra | `Invoice` | Áno |
| Paragón pri úhrade faktúry | `InvoiceParagon` | Nie |
| Neplatný doklad | `Invalid` | Nie |
| Vklad a výber hotovosti | `Deposit`, `Withdraw` | Nie |
Pri typoch dokladov s hodnotou „Nie“ sa doklad vždy vyhotoví predvoleným spôsobom z nastavení aplikácie.
Spôsob vyhotovenia je možné určiť pomocou vlastnosti `print.printerName`.
Podporované sú tri možnosti:
- [Papierový doklad](#pos) (`pos`): Doklad vytlačí tlačiareň pokladnice.
- [PDF súbor](#pdf) (`pdf`): eKasa vytvorí PDF súbor, zákazníkovi ho doručí váš softvér.
- [E-mail](#email) (`email`): eKasa vytvorí PDF súbor a sama ho pošle zákazníkovi e-mailom.
Obe elektronické možnosti vytvoria rovnaký PDF súbor. Líšia sa tým, kto ho doručí zákazníkovi:
| | `email` | `pdf` |
|-----|-----|-----|
| Kto doklad doručí | eKasa ho pošle e-mailom na adresu z požiadavky (`options.To`) | váš softvér: PDF súbor si stiahne cez API ([Získanie PDF súboru](#získanie-pdf-súboru)) a doručí ho sám |
| Čo treba pripraviť | SMTP server v nastaveniach eKasy | spracovanie PDF súboru vo vašom softvéri |
| Kedy ho použiť | zákazník chce doklad e-mailom a stačí, že ho pošle eKasa | doklad doručujete vlastnou cestou, napríklad do klientskej zóny, aplikácie alebo vlastným e-mailom |
Ak nie je objekt `print` špecifikovaný, doklad sa vyhotoví predvoleným spôsobom z nastavení aplikácie, štandardne ako papierový doklad (`pos`).
Ak systém eKasa práve neodpovedá, doklad sa vyhotoví na papier, aj keď ste žiadali PDF alebo e-mail. Podrobnosti
sú v časti [Keď systém eKasa neodpovedá](#offline).
**HTTP API:**
Telo požiadavky na registráciu dokladu, ktoré nadradená aplikácia posiela do HTTP API, obsahuje na najvyššej úrovni dve vlastnosti vedľa seba:
1. `request`: informácie týkajúce sa samotného dokladu
1. `print`: informácie týkajúce sa spôsobu vyhotovenia dokladu
Vlastnosť `print` umožňuje špecifikovať spôsob vyhotovenia dokladu podľa vlastností:
- `printerName`: určuje typ vyhotovenia dokladu.
- `options`: určuje povinné aj voliteľné prepínače ovplyvňujúce vyhotovenie dokladu (podľa spôsobu vyhotovenia, pozri nižšie).
Príklad:
```jsonc
{
"request": {
"data": { /* … údaje dokladu */ }
},
"print": {
"printerName": "pos",
"options": { /* … prepínače vyhotovenia */ }
}
}
```
**.NET knižnica:**
Funkcia knižnice `client.RegisterReceiptAsync()`
1. `RegisterCashRegisterReceiptRequest request`: informácie týkajúce sa samotného dokladu
1. `RegisterReceiptPrintContext printContext`: informácie týkajúce sa spôsobu vyhotovenia dokladu
Parameter funkcie `printContext` umožňuje špecifikovať spôsob vyhotovenia dokladu podľa vlastností:
- `printerName`: určuje typ vyhotovenia dokladu.
- `options`: určuje povinné aj voliteľné prepínače ovplyvňujúce vyhotovenie dokladu (podľa spôsobu vyhotovenia, pozri nižšie).
## pos Papierový doklad
Predvolený spôsob vyhotovenia dokladu.
Pre vyhotovenie dokladu vo forme papierového účtu je potrebné zašpecifikovať v poli `printerName` hodnotu `pos`.
V objekte `options` je možné uviesť nasledovné hodnoty:
| Názov | Povinné pole | Popis |
|-----|-----|-----|
| `OpenDrawer` | Nie | Umožňuje určiť, či sa pre tento konkrétny doklad otvorí (hodnota `true`), prípadne neotvorí (hodnota `false`) peňažná zásuvka. Toto nastavenie umožňuje nadradenej aplikácii variabilne určovať, pri ktorých typoch dokladov, prípadne pri ktorých platidlách je vhodné otvárať peňažnú zásuvku. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie. |
| `PrintLogo` | Nie | Umožňuje určiť, či sa pre tento doklad vytlačí (hodnota `true`), prípadne nevytlačí (hodnota `false`) grafické logo. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie. |
| `LogoMemoryAddress` | Nie | Umožňuje určiť, aké logo sa pre tento doklad vytlačí. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie. |
**HTTP API:**
```json
{
"print": {
"printerName": "pos",
"options": {
"OpenDrawer": false,
"PrintLogo": true,
"LogoMemoryAddress": 1
}
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": 1.99
}
]
}
}
}
```
**.NET knižnica:**
```csharp
// we can override default client configuration with these optional fields:
var printOptions = new PosPrintingOptions()
{
// this will override the "configuration.Printers.Pos.Drawer.Enabled"
// for this specific receipt.
OpenDrawer = false,
// this will override the "configuration.Printers.Pos.Logo.Enabled"
// for this specific receipt.
PrintLogo = true,
// this will override the "configuration.Printers.Pos.Logo.MemoryAddress"
// for this specific receipt.
LogoMemoryAddress = 1
};
// prepare print context object from printer name and printing options
var printContext = RegisterReceiptPrintContext.CreatePos(printOptions);
// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);
// and register receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);
```
## pdf Elektronický doklad vo forme PDF súboru
S `printerName` `pdf` eKasa doklad nevytlačí, ale vytvorí z neho PDF súbor. Zákazníkovi ho doručí váš softvér,
napríklad e-mailom, v aplikácii alebo na webe:
1. Doklad zaregistrujte s `"printerName": "pdf"`.
2. PDF súbor si [stiahnite cez API](#získanie-pdf-súboru).
3. Hneď ho doručte zákazníkovi, napríklad e-mailom alebo odkazom v aplikácii. Doklad musí dostať bezodkladne po
zaplatení, nie neskôr hromadne. Ak ho potrebujete dlhšie, uložte si ho u seba.
V objekte `options` môžete uviesť:
| Názov | Povinné | Popis |
|-----|-----|-----|
| `OpenDrawer` | nie | Otvorí (`true`) alebo neotvorí (`false`) peňažnú zásuvku pri tomto doklade. Má prednosť pred nastavením aplikácie. |
**HTTP API:**
```json
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": 1.99
}
]
}
}
}
```
**.NET knižnica:**
```csharp
// the only option for the pdf printer is OpenDrawer; without options
// the application configuration is used.
var printContext = RegisterReceiptPrintContext.CreatePdf();
// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);
// and finally, register the receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);
// PDF file is created now, by default in the "receipts" folder
// of the application working directory.
```
### Získanie PDF súboru
PDF súbor si stiahnete podľa identifikátora dokladu, rovnako ako pri [vyhľadaní dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup). Vždy uveďte aj
kód pokladnice (`cashRegisterCode`). Doklad sa nájde aj vtedy, keď chýba v [tabuľke indexov](https://ekasa.ninedigit.sk/docs/glossary#tabulka-indexov).
**HTTP API:**
Požiadavka `GET /api/v1/printers/pdf/receipt` vráti PDF súbor. Ak doklad alebo jeho súbor neexistuje, odpoveď má
HTTP stav 404. Všetky parametre opisuje [referencia HTTP API](https://ekasa.ninedigit.sk/docs/rest-api/reference#tag/printers/GET/api/v1/printers/pdf/receipt).
| Doklad určíte | Parametre |
|---|---|
| externým identifikátorom | `externalId` |
| interným identifikátorom | `id` |
| číslom dokladu | `year`, `month` a `receiptNumber` |
```bash
curl -o doklad.pdf "http://localhost:3010/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&externalId=objednavka-1024"
```
**.NET knižnica:**
Metóda `client.GetPdfReceiptStreamAsync` vráti PDF súbor ako `Stream`. Doklad určíte filtrom
`SingleReceiptRegistrationFilter`: externým identifikátorom, interným identifikátorom alebo číslom dokladu.
```csharp
SingleReceiptRegistrationFilter filter = new SingleReceiptRegistrationFilter(
cashRegisterCode: "88812345678900001",
receiptNumberId: new ReceiptNumberId(year: 2026, month: 1, number: 1));
Stream stream = await client.GetPdfReceiptStreamAsync(filter, cancellationToken);
```
### Kde eKasa PDF súbory ukladá
PDF súbory vznikajú na disku zariadenia, na ktorom eKasa beží, v priečinku z nastavenia
`printers.pdf.outputDirectory`. Predvolená hodnota `receipts` je relatívna k pracovnému adresáru aplikácie:
| Systém | Priečinok |
|---|---|
| Windows | `C:\ProgramData\NineDigit\Portos.eKasa\receipts\` |
| macOS a Linux | `/etc/NineDigit/Portos.eKasa/receipts/` |
Súbor sa volá `{kód pokladnice}_{rok a mesiac}_{číslo dokladu}.pdf`, napríklad
`88812345678900001_202601_000123.pdf`.
eKasa PDF súbory po 31 dňoch automaticky zmaže, potom ich už cez API nestiahnete. Ak doklad potrebujete dlhšie,
stiahnite si ho hneď po registrácii a uložte vo svojom softvéri.
## email Elektronický doklad vo forme e-mailu
Pre vyhotovenie dokladu vo forme emailu je potrebné zašpecifikovať v poli `printerName` hodnotu `email`.
V objekte `options` je možné uviesť nasledovné hodnoty:
| Názov | Povinné pole | Popis |
|-----|-----|-----|
| `To` | Áno | E-mailová adresa adresáta (e-mail, na ktorý má byť doklad odoslaný). Doklad sa posiela **len na jednu adresu**: kópia (`CC`) ani skrytá kópia (`BCC`) nie je možná, lebo zákon pozná len jeden originál pokladničného dokladu. Ak potrebujete doklad aj uložiť (napríklad do archívu), použite [`pdf`](#pdf): PDF súbor si stiahnete a zákazníkovi ho doručíte aj uložíte sami. |
| `Subject` | Nie | Umožňuje určiť predmet e-mailu, ktorý sa použije pre tento konkrétny doklad. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácii aplikácie (`printers.email.subject`). |
| `Body` | Nie | Umožňuje určiť telo e-mailu, ktorý sa použije pre tento konkrétny doklad. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácii aplikácie (`printers.email.body`). |
| `RecipientDisplayName` | Nie | Umožňuje určiť zobrazovacie meno adresáta e-mailu. |
| `OpenDrawer` | Nie | Umožňuje určiť, či sa pre tento konkrétny doklad otvorí (hodnota `true`), prípadne neotvorí (hodnota `false`) peňažná zásuvka. Toto nastavenie umožňuje nadradenej aplikácii variabilne určovať, pri ktorých typoch dokladov, prípadne pri ktorých platidlách je vhodné otvárať peňažnú zásuvku. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie. |
**HTTP API:**
```json
{
"print": {
"printerName": "email",
"options": {
"To": "john.doe@example.com",
"Subject": "Váš e-doklad",
"Body": "Ďakujeme za nákup.",
"RecipientDisplayName": "John Doe"
}
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"items": [
{
"type": "positive",
"name": "Coca Cola",
"quantity": {
"amount": 1.00,
"unit": "ks"
},
"unitPrice": 1.99,
"price": 1.99,
"vatRate": 23.00
}
],
"payments": [
{
"name": "Hotovosť",
"amount": 1.99
}
]
}
}
}
```
**.NET knižnica:**
```csharp
// required parameter - recipient's e-mail address
var printOptions = new EmailPrintingOptions("john.brown@example.com")
{
// optional parameter. this will override
// the "configuration.Printers.Email.Subject"
// for this specific receipt.
Subject = "Your receipt, mr. Brown!",
// optional parameter. This will override
// the "configuration.Printers.Email.Body"
// for this specific receipt.
Body = "Thank you for your purchase.",
// optional parameter - recipient's display name
RecipientDisplayName = "John Brown"
};
// prepare print context object from printing options
var printContext = RegisterReceiptPrintContext.CreateEmail(printOptions);
// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);
// and register receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);
```
### Správanie systému po zlyhanom odoslaní e-mailu
Ak sa doklad zaeviduje a zapíše do úložiska, ale zlyhá až odoslanie e-mailu, **registrácia dokladu je úspešná**:
eKasa vráti bežný výsledok registrácie a chybu nehlási. Zlyhanie odoslania zapíše do logu a PDF súbor dokladu
ponechá v rovnakom priečinku ako pri elektronickom doklade vo forme PDF (pozri
[Získanie PDF súboru](#získanie-pdf-súboru)). Po úspešnom odoslaní sa PDF súbor zmaže.
eKasa odoslanie e-mailu neopakuje: ten istý doklad sa nesmie vyhotoviť viackrát. Ak e-mail neodišiel, doklad
zákazníkovi odovzdajte inak, napríklad vytlačte [kópiu dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup#tla%C4%8D-k%C3%B3pie-dokladu).
Príčinu zistíte v logoch služby (vo webovom rozhraní v menu **Systém → Údržba**). Najčastejšie ide o:
- **spojenie so serverom**: skontrolujte adresu a port SMTP servera; ak server nepodporuje SSL, v poli
**Typ pripojenia** zvoľte **Použiť TLS, ak je k dispozícii**,
- **prihlásenie**: skontrolujte prihlasovacie údaje e-mailového konta,
- **adresu príjemcu**: server adresu odmietol (`RecipientNotAccepted`).
## Keď systém eKasa neodpovedá
Väčšinu dokladov eKasa zaeviduje online: dátovú správu odošle do systému eKasa a doklad vyhotoví až s jeho
odpoveďou. Ak systém eKasa neodpovie do časového limitu (predvolene 10 sekúnd) alebo nie je pripojenie, eKasa doklad
zaeviduje **v offline režime**. Predaj pokračuje, zmení sa len to, ako sa doklad vyhotoví:
```mermaid
flowchart TD
A{printerName} -->|pos| P1[Papierový doklad]
A -->|pdf alebo email| B{Systém eKasa odpovedal?}
B -->|áno, online| E[PDF súbor alebo e-mail]
B -->|nie, offline| P2[Papierový doklad OFF-LINE DOKLAD]
```
- **Doklad je na papieri.** Pokyny finančnej správy vyžadujú, aby doklad zaevidovaný offline mal papierovú podobu.
eKasa ho preto vyhotoví predvoleným spôsobom z nastavení (štandardne papierový doklad `pos`), aj keď ste žiadali
`pdf` alebo `email`. PDF súbor ani e-mail nevzniknú, ani neskôr, keď sa dátová správa odošle.
- **Doklad je platný.** Namiesto unikátneho identifikátora (UID) obsahuje podpisový kód podnikateľa (PKP) a QR kód
s overovacím kódom podnikateľa (OKP).
- **Nič neopakujte.** Dátovú správu eKasa odošle do systému eKasa sama. Doklad neregistrujte znova.
Vo vašom softvéri rozpoznáte offline doklad podľa výsledku `isSuccessful: null` (v .NET `IsSuccessful == null`), pozri
[Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result). Pokladníkovi môžete ukázať, že doklad sa vytlačil a
zákazníkovi treba odovzdať papierový doklad, lebo e-mail neodišiel.
Ak tlač papierového dokladu zlyhá (napríklad chýba papier), vráti sa chyba
[`-502: PrintReceiptError`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-502-printreceiptererror). Doklad je aj vtedy zaevidovaný a
vo fronte, preto ho neposielajte na registráciu znova. Po odstránení problému môžete zákazníkovi vytlačiť
[kópiu dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup). Ak zákazník trvá na origináli, pôvodný doklad
[stornujte](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections#storno-dokladu) a zaregistrujte nový.
Celý priebeh offline režimu popisuje [Ako funguje eKasa](https://ekasa.ninedigit.sk/docs/how-it-works#ke%C4%8F-nie-je-internet).
## Dodatočné texty na doklade
Doklad obsahuje dodatočné vlastnosti pre vloženie dodatočných textov na doklad.
| Názov | Popis | Poznámka |
|----|----|----|
| `headerText` | Text tlačený hneď za identifikačnými údajmi | V prípade použitia tokenov nie je aplikovaný `pageBreak` token |
| `footerText` | Text tlačený na konci dokladu, za QR kódom a identifikátorom dokladu | |
Obe vlastnosti podporujú použitie tzv. `token`-ov pre formátovanie, tlač QR kódov a čiarových kódov. Viac nájdete v článku [Tokeny a formátovanie textu](https://ekasa.ninedigit.sk/docs/token-syntax).
Príklad:
```json
{
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"invoiceNumber": "FA-2026-0001",
"amount": 189.90,
"headerText": "Nine Digit, s.r.o.\nweb: www.ninedigit.sk",
"footerText": "Ďakujeme za úhradu faktúry.\nPotvrdenie o platbe nájdete aj\nv klientskej zóne na www.ninedigit.sk."
}
}
}
```
Takto vyzerá vyhotovený doklad. Hlavička je hneď pod identifikačnými údajmi predávajúceho a dokladu, päta na
konci dokladu:
[Obrázok: Doklad úhrady faktúry, zvýraznený je text hlavičky (Nine Digit, s.r.o., web) pod identifikačnými údajmi a poďakovanie v päte na konci dokladu]
## Kam ďalej
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Číslo dokladu, identifikátor a rekapitulácia DPH.
- [Tokeny a formátovanie](https://ekasa.ninedigit.sk/docs/token-syntax): Tučné písmo, zarovnanie, QR a čiarové kódy v texte.
- [Nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt): Tlač vlastného textu mimo evidencie.
---
# Výsledok registrácie
> Čo obsahuje výsledok registrácie dokladu: isSuccessful, číslo dokladu, unikátny identifikátor a rekapitulácia DPH.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-registration/result
Po každej registrácii dokladu dostane váš softvér výsledok. Z neho zistíte, ako registrácia dopadla: doklad je
zaregistrovaný online, prijatý v offline režime, alebo ho systém eKasa odmietol. Zároveň v ňom sú údaje, ktoré
váš softvér potrebuje ďalej: číslo dokladu, unikátny identifikátor pre neskoršie storno alebo vrátenie tovaru
a rekapitulácia DPH.
Pred registráciou si prečítajte [Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id): `externalId`
zabráni dvojitej evidencii tržby, keď sa odpoveď stratí.
## Čo výsledok obsahuje
**HTTP API:**
API vráti výsledok v tele odpovede na registráciu dokladu.
**.NET knižnica:**
Metóda `RegisterReceiptAsync` vráti objekt `RegisterReceiptResult` s vlastnosťami `IsSuccessful`, `Request`,
`Response` a `Error`.
| Vlastnosť | Obsah | Má hodnotu |
|---|---|---|
| `isSuccessful` | Ako registrácia dopadla, pozri [Tri možné výsledky](#tri-možné-výsledky). | `true`, `null` alebo `false` |
| `request` | Požiadavka odosielaná na systém eKasa: pôvodné údaje zaslané nadradenou aplikáciou a doplnené údaje, napríklad číslo dokladu (`receiptNumber`) a overovací kód podnikateľa (`okp`). | vždy |
| `response` | Výsledok spracovania dokladu s informáciami zo systému finančnej správy eKasa. | len ak `isSuccessful` je `true` |
| `error` | Chybový objekt s informáciami zo systému finančnej správy eKasa. | len ak `isSuccessful` je `false` |
## Tri možné výsledky
| `isSuccessful` | Čo sa stalo | `response` | `error` |
|---|---|---|---|
| `true` | Doklad bol úspešne zaregistrovaný **v online režime**. | výsledok spracovania | `null` |
| `null` | Registrácia dokladu bola prijatá **v offline režime**. | `null` | `null` |
| `false` | Registrácia bola vybavená v online režime, ale **systém eKasa ju odmietol**. | `null` | chyba |
Príklady nižšie obsahujú len vybrané vlastnosti.
**Online** – doklad úspešne zaevidovaný v online režime:
```json
{
"request": {
"data": {
"receiptNumber": 2,
"okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
}
},
"response": {
"data": {
"id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A"
},
"processDate": "2026-01-20T15:34:14+01:00"
},
"isSuccessful": true,
"error": null,
"$type": "Receipt"
}
```
**Offline** – doklad zaevidovaný v offline režime:
```json
{
"request": {
"data": {
"receiptNumber": 2,
"okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
}
},
"response": null,
"isSuccessful": null,
"error": null,
"$type": "Receipt"
}
```
**Odmietnutý** – požiadavka zamietnutá serverom finančnej správy:
```json
{
"request": {
"data": {
"receiptNumber": 2,
"okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
}
},
"response": null,
"isSuccessful": false,
"error": {
"message": "Chyba v podpise dátovej správy.",
"code": -10
},
"$type": "Receipt"
}
```
## Kde nájdete údaje dokladu
**HTTP API:**
| Údaj | Vlastnosť | Podrobnosti |
|---|---|---|
| Číslo dokladu | `request.data.receiptNumber` | [Získanie čísla dokladu](#získanie-čísla-dokladu) |
| Unikátny identifikátor (online) | `response.data.id` | [Získanie unikátneho identifikátora](#získanie-unikátneho-identifikátora-dokladu) |
| Overovací kód podnikateľa (offline) | `request.data.okp` | [Získanie unikátneho identifikátora](#získanie-unikátneho-identifikátora-dokladu) |
| Rekapitulácia DPH | `request.data.vatRatesTaxSummary` | [Rekapitulácia DPH](#rekapitulácia-dph) |
| Chyba zo systému eKasa | `error.code`, `error.message` | [Tri možné výsledky](#tri-možné-výsledky) |
**.NET knižnica:**
| Údaj | Vlastnosť | Podrobnosti |
|---|---|---|
| Číslo dokladu | `result.Request.Data.ReceiptNumber` | [Získanie čísla dokladu](#získanie-čísla-dokladu) |
| Unikátny identifikátor (online) | `result.Response.Data.Id` | [Získanie unikátneho identifikátora](#získanie-unikátneho-identifikátora-dokladu) |
| Overovací kód podnikateľa (offline) | `result.Request.Data.OKP` | [Získanie unikátneho identifikátora](#získanie-unikátneho-identifikátora-dokladu) |
| Rekapitulácia DPH | `VatRatesTaxSummary.Create(result.Request.Data.Items)` | [Rekapitulácia DPH](#rekapitulácia-dph) |
| Chyba zo systému eKasa | `result.Error.Code`, `result.Error.Message` | [Tri možné výsledky](#tri-možné-výsledky) |
```csharp
RegisterReceiptResult result = await client.RegisterReceiptAsync(
request, RegisterReceiptPrintContext.CreatePos(), cancellationToken);
ReceiptNumber receiptNumber = result.Request.Data.ReceiptNumber;
switch (result.IsSuccessful)
{
case true: // online: doklad zaregistrovaný v systéme eKasa
EKasaReceiptId id = result.Response.Data.Id;
break;
case null: // offline: registrácia prijatá v offline režime
OKP okp = result.Request.Data.OKP;
break;
case false: // online, ale systém eKasa doklad odmietol
int? code = result.Error.Code;
string message = result.Error.Message;
break;
}
VatRatesTaxSummary? vatSummary = result.Request.Data.Items is { } items
? VatRatesTaxSummary.Create(items)
: null;
```
## Príklad požiadavky a odpovede
Ukážka je nákup v kaviarni zaplatený v hotovosti. Obsahuje položky v sadzbách DPH 23 %, 19 % a 5 % a vratné obaly
(nepodliehajú DPH). Doklad je vytlačený do PDF:
[Obrázok: Vytlačený doklad z kaviarne s položkami v sadzbách 23 %, 19 % a 5 %, vratnými obalmi, zaokrúhlením, rekapituláciou DPH, UID a OKP]
```http
POST {server_address}/api/v1/requests/receipts/cash_register
{
"print": {
"printerName": "pdf"
},
"request": {
"data": {
"cashRegisterCode": "88812345678900001",
"headerText": "https://ekasa.ninedigit.sk",
"footerText": "Ďakujeme za nákup!",
"items": [
{
"type": "Positive",
"name": "Cappuccino",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": 2.90,
"price": 5.80,
"vatRate": 19.00
},
{
"type": "Positive",
"name": "Croissant maslový (3 ks za 4 €)",
"quantity": {
"amount": 3.00,
"unit": "ks"
},
"unitPrice": 1.333333,
"price": 4.00,
"vatRate": 5.00
},
{
"type": "Positive",
"name": "Minerálka 0,33 l (2 ks za 2,25 €)",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": 1.125,
"price": 2.25,
"vatRate": 19.00
},
{
"type": "Positive",
"name": "Pohľadnica Bratislava",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": 0.88,
"price": 1.76,
"vatRate": 23.00
},
{
"type": "Positive",
"name": "Záloha PET",
"quantity": {
"amount": 2.00,
"unit": "ks"
},
"unitPrice": 0.15,
"price": 0.30
},
{
"type": "ReturnedContainer",
"name": "Vrátenie zálohy PET",
"quantity": {
"amount": 3.00,
"unit": "ks"
},
"unitPrice": -0.15,
"price": -0.45
}
],
"roundingAmount": -0.01,
"payments": [
{
"name": "Hotovosť",
"amount": 20.00
},
{
"name": "Výdavok",
"amount": -6.35
}
]
}
}
}
```
Odpoveď, vybrané vlastnosti. Číslo dokladu `35` je na doklade v riadku **Doklad**, `response.data.id` v riadku
**UID** a `okp` v riadku **OKP**:
```json
{
"request": {
"data": {
"receiptNumber": 35,
"amount": 13.65,
"okp": "C1E7A53E-6D1D48B0-801EE45D-6B67BF63-6C2AA5CF"
}
},
"response": {
"data": {
"id": "O-488AE60F5DDC432E8AE60F5DDC7-TEST"
},
"processDate": "2026-11-19T02:08:43+01:00"
},
"isSuccessful": true,
"error": null,
"$type": "Receipt"
}
```
**Celá odpoveď**
```json
{
"request": {
"data": {
"receiptType": "CashRegister",
"amount": 13.65,
"roundingAmount": -0.01,
"issueDate": "2026-11-19T02:08:43+01:00",
"receiptNumber": 35,
"invoiceNumber": null,
"paragonNumber": null,
"icdph": "SK1234567890",
"ico": "76543210",
"basicVatAmount": 0.33,
"reducedVatAmount": 1.29,
"secondReducedVatAmount": 0.19,
"taxFreeAmount": null,
"nonTaxableAmount": -0.15,
"taxBaseBasic": 1.43,
"taxBaseReduced": 6.76,
"taxBaseSecondReduced": 3.81,
"items": [
{
"type": "Positive",
"name": "Cappuccino",
"price": 5.80,
"unitPrice": 2.900000,
"quantity": {
"amount": 2.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": 19.00,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
},
{
"type": "Positive",
"name": "Croissant maslový (3 ks za 4 €)",
"price": 4.00,
"unitPrice": 1.333333,
"quantity": {
"amount": 3.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": 5.00,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
},
{
"type": "Positive",
"name": "Minerálka 0,33 l (2 ks za 2,25 €)",
"price": 2.25,
"unitPrice": 1.125000,
"quantity": {
"amount": 2.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": 19.00,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
},
{
"type": "Positive",
"name": "Pohľadnica Bratislava",
"price": 1.76,
"unitPrice": 0.880000,
"quantity": {
"amount": 2.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": 23.00,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
},
{
"type": "Positive",
"name": "Záloha PET",
"price": 0.30,
"unitPrice": 0.150000,
"quantity": {
"amount": 2.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": null,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
},
{
"type": "ReturnedContainer",
"name": "Vrátenie zálohy PET",
"price": -0.45,
"unitPrice": -0.150000,
"quantity": {
"amount": 3.0000,
"unit": "ks"
},
"referenceReceiptId": null,
"vatRate": null,
"specialRegulation": null,
"voucherNumber": null,
"seller": null,
"description": null
}
],
"vatRatesTaxSummary": {
"totalVatBase": 12.00,
"totalVatAmout": 1.81,
"totalTaxableAmount": 13.81,
"totalNonTaxableAmount": -0.15,
"totalAmount": 13.66,
"items": [
{
"vatRate": 19.00,
"vatBase": 6.76,
"vatAmount": 1.29,
"totalAmount": 8.05
},
{
"vatRate": 5.00,
"vatBase": 3.81,
"vatAmount": 0.19,
"totalAmount": 4.00
},
{
"vatRate": 23.00,
"vatBase": 1.43,
"vatAmount": 0.33,
"totalAmount": 1.76
},
{
"vatRate": null,
"vatBase": -0.15,
"vatAmount": 0.00,
"totalAmount": -0.15
}
]
},
"okp": "C1E7A53E-6D1D48B0-801EE45D-6B67BF63-6C2AA5CF",
"pkp": "bRkmkbk9S/Kn9sylBgRQphmLLU/o+7gcao0q5TXJyb/ZHnQ27oVOERwQqUKqZeR0Q9J5j35fv1ucBn/TmT85yUfdmZ5a2c3rOdoB/h+z8YT+LFC0+5QCh9bbKkWu9TdXKMdPU4Exkl8bLY8rqpP80Ay/Uz/ACx7jEqdE5lPjIQoijyeYDEPkIWyAtr8vCql07x0c2oCP3fs0i1hcUz18uKcnYxpC08+60hpP1Rmj8FfAfd3S2Xqxo9W3Yn87lCs6n3LcbrNQbXLrHbCfKDuJa7yUyLY0Vh9i1zn5lFQBop9mWRyI+KUCYbWIQzBjIWUtJuz0fo/ofpHLhH54vyT9gQ==",
"payments": [
{
"name": "Hotovosť",
"amount": 20.00
},
{
"name": "Výdavok",
"amount": -6.35
}
],
"headerText": "https://ekasa.ninedigit.sk",
"footerText": "Ďakujeme za nákup!",
"createDate": "2026-11-19T02:08:43+01:00",
"dic": "1234567890",
"cashRegisterCode": "88812345678900001"
},
"id": "9dc3e9ed-695c-4885-b96f-1ff8fa038a85",
"externalId": null,
"date": "2026-11-19T02:08:43+01:00",
"sendingCount": 1
},
"response": {
"data": {
"id": "O-488AE60F5DDC432E8AE60F5DDC7-TEST"
},
"processDate": "2026-11-19T02:08:43+01:00"
},
"isSuccessful": true,
"error": null,
"$type": "Receipt"
}
```
Odpoveď na registráciu dokladu obsahuje aj sumárne informácie podľa kategórie DPH (základná vs. znížená), ktoré však
v prípade kombinácie viacerých sadzieb v rovnakej kategórii (napríklad 23 % a 20 % pri dokladoch z prechodného
obdobia, obe základné sadzby) môžu viesť k **nejednoznačným výsledkom**. Na získanie finančných ukazovateľov o obratoch
DPH preto tieto vlastnosti nepoužívajte a uprednostnite vlastnosť `vatRatesTaxSummary`
([rekapitulácia DPH](#rekapitulácia-dph)). V budúcich verziách môžu byť tieto vlastnosti odstránené.
| Vlastnosť | Obsah | V príklade |
|---|---|---|
| `basicVatAmount` | DPH v základnej sadzbe (23 %) | `0.33` |
| `taxBaseBasic` | základ dane v základnej sadzbe (23 %) | `1.43` |
| `reducedVatAmount` | DPH v zníženej sadzbe (19 %) | `1.29` |
| `taxBaseReduced` | základ dane v zníženej sadzbe (19 %) | `6.76` |
| `secondReducedVatAmount` | DPH v druhej zníženej sadzbe (5 %) | `0.19` |
| `taxBaseSecondReduced` | základ dane v druhej zníženej sadzbe (5 %) | `3.81` |
| `taxFreeAmount` | suma oslobodená od DPH | `null` |
| `nonTaxableAmount` | suma položiek nepodliehajúcich DPH | `-0.15` |
## Získanie čísla dokladu
Číslo dokladu je v poli `request.data.receiptNumber`. Je unikátne v rámci kalendárneho mesiaca a tvorí súvislú
číselnú radu spoločnú pre všetky typy pokladničných dokladov.
## Získanie unikátneho identifikátora dokladu
Unikátny identifikátor dokladu si v nadradenej aplikácii pamätajte pre prípadné dodatočné stornovanie dokladu alebo
pre vrátenie tovaru (reklamácia, …). Kde ho nájdete, závisí od režimu, v ktorom bola požiadavka vybavená:
| Režim | `isSuccessful` | Identifikátor | Pole |
|---|---|---|---|
| online | `true` | unikátny identifikátor dokladu pridelený systémom eKasa | `response.data.id` |
| offline | `null` | identifikátor systému eKasa nie je k dispozícii, namiesto neho sa používa overovací kód podnikateľa (OKP) | `request.data.okp` |
Jeden z týchto dvoch identifikátorov je pri [korekcii dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections) potrebné
uvádzať do poľa `referenceReceiptId` položky dokladu.
Doklad z integračného prostredia si overíte na stránke finančnej správy, pozri
[Príprava a test](https://ekasa.ninedigit.sk/docs/environment-setup#3-po%C5%A1lite-prv%C3%BD-doklad).
## Rekapitulácia DPH
Od verzie `7.0.0` obsahuje odpoveď aj vlastnosť `request.data.vatRatesTaxSummary`: sumárne informácie rozdelené
podľa sadzby DPH (tzv. rekapitulácia DPH). Je k dispozícii aj pre doklady vytvorené staršími verziami aplikácie (pred
aktualizáciou na verziu `7.0.0`). Ak doklad neobsahuje položky (vlastnosť `items` je `null`), aj `vatRatesTaxSummary`
je `null`.
| Vlastnosť | Význam | Príklad |
|---|---|---|
| `totalVatBase` | Celková suma základov dane pre položky podliehajúce DPH | `12.00` |
| `totalVatAmout` | Celková suma výšky dane (názov vlastnosti je naozaj takto) | `1.81` |
| `totalTaxableAmount` | Celková suma položiek podliehajúcich DPH | `13.81` |
| `totalNonTaxableAmount` | Celková suma položiek nepodliehajúcich DPH | `-0.15` |
| `totalAmount` | Celková suma všetkých položiek | `13.66` |
| `items` | Zoznam sumárnych informácií podľa sadzby DPH. Obsahuje tie sadzby DPH (resp. položky nepodliehajúce DPH), ktoré sú zastúpené v zozname položiek dokladu (vlastnosť `items`). | |
Každý prvok zoznamu `items`:
| Vlastnosť | Význam | Príklad |
|---|---|---|
| `vatRate` | Sadzba DPH (`23.00` znamená 23 %), alebo `null` pre položky nepodliehajúce DPH (napr. predaj alebo vrátenie vratných obalov) | `23.00` |
| `vatBase` | Celková suma základu dane pre danú sadzbu DPH | `1.43` |
| `vatAmount` | Suma DPH pre danú sadzbu DPH | `0.33` |
| `totalAmount` | Celkový obrat pre danú sadzbu DPH | `1.76` |
Pre každý prvok (vrátane sumáru pre položky nepodliehajúce DPH, tzn. `vatRate` je `null`) platí:
$$
\text{vatBase} + \text{vatAmount} = \text{totalAmount}
$$
### Príklad
Rekapitulácia z [príkladu vyššie](#príklad-požiadavky-a-odpovede). Na vytlačenom doklade jej zodpovedá tabuľka
**Sadzba – Základ – Daň – Obrat**.
```json
{
"totalVatBase": 12.00,
"totalVatAmout": 1.81,
"totalTaxableAmount": 13.81,
"totalNonTaxableAmount": -0.15,
"totalAmount": 13.66,
"items": [
{
"vatRate": 19.00,
"vatBase": 6.76,
"vatAmount": 1.29,
"totalAmount": 8.05
},
{
"vatRate": 5.00,
"vatBase": 3.81,
"vatAmount": 0.19,
"totalAmount": 4.00
},
{
"vatRate": 23.00,
"vatBase": 1.43,
"vatAmount": 0.33,
"totalAmount": 1.76
},
{
"vatRate": null,
"vatBase": -0.15,
"vatAmount": 0.00,
"totalAmount": -0.15
}
]
}
```
## Kam ďalej
- [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections): Oprava dokladu, vrátenie tovaru a úhrady faktúry.
- [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status): Fronta neodoslaných správ, úložisko a tlačiareň.
- [Vyhľadanie dokladov](https://ekasa.ninedigit.sk/docs/receipt-lookup): Doklady podľa čísla, identifikátora alebo externalId.
---
# Registrácia polohy
> Kedy a ako zaregistrovať polohu prenosnej pokladnice: GPS súradnice, adresa alebo voľný text, výsledok registrácie a časté otázky.
Zdroj: https://ekasa.ninedigit.sk/docs/location-registration
**Prenosná pokladnica**, napríklad na trhoch, v taxíku alebo pri predaji z auta, musí mať zaregistrovanú polohu,
kde podnikateľ práve prijíma tržby. Pokladnica na stálej prevádzke polohu neregistruje, jej adresa je
v identifikačných údajoch.
Polohu zadáte jedným z troch formátov. Uprednostnite adresu alebo GPS súradnice, voľný text použite len vtedy, keď
ani jedno nie je k dispozícii.
- [GPS súradnice](#gps-súradnice) (`gps`): Zariadenie pozná svoju polohu.
- [Adresa](#adresa) (`address`): Predaj na mieste so známou adresou.
- [Voľný text](#voľný-text) (`other`): Adresa ani súradnice nie sú, napríklad evidenčné číslo vozidla.
**HTTP API:**
Každý formát má vlastnú adresu: `POST /api/v1/requests/locations/gps`, `…/address` a `…/other`.
**.NET knižnica:**
Všetky formáty registrujete metódou `client.RegisterLocationAsync()`. Formát určí typ polohy: `GeoCoordinates`,
`PhysicalAddress` alebo `CashRegisterOtherLocation`.
## Kedy polohu registrovať
```mermaid
flowchart TD
A{Je pokladnica prenosná?} -->|nie| B[Polohu neregistrujete]
A -->|áno| C{Má pokladnica už zaregistrovanú polohu?}
C -->|nie| D[Zaregistrujte polohu pred prvým dokladom]
C -->|áno| F{Zmenilo sa miesto predaja od poslednej registrácie?}
F -->|áno| G[Zaregistrujte novú polohu]
F -->|nie| E[Poloha platí ďalej]
```
Zákon o evidencii tržieb vyžaduje adresu alebo GPS súradnice predajného miesta (pri predaji z vozidla jeho evidenčné číslo) zaslať do systému eKasa pred
začiatkom predaja; ak to pre výpadok signálu nejde, do 96 hodín
([§ 7 ods. 8 zákona 384/2025](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-7.odsek-8)).
Bez pripojenia sa registrácia uloží do fronty a eKasa ju odošle automaticky. Poloha nemá exspiráciu, platí, kým
nezaregistrujete novú.
## GPS súradnice
Súradnice v systéme WGS 84, na ktorých pokladnica vyhotovuje doklady.
| Vlastnosť | Popis | Pravidlá |
|---|---|---|
| `latitude` | zemepisná šírka (sever – juh) | povinná, −90 až 90, najviac 10 desatinných miest |
| `longitude` | zemepisná dĺžka (východ – západ) | povinná, −180 až 180, najviac 10 desatinných miest |
**HTTP API:**
```http
POST http://localhost:3010/api/v1/requests/locations/gps
```
```json
{
"data": {
"cashRegisterCode": "88812345678900001",
"location": {
"latitude": 48.148962,
"longitude": 17.165377
}
}
}
```
**.NET knižnica:**
```csharp
var location = new GeoCoordinates(longitude: 17.165377m, latitude: 48.148962m);
RegisterLocationResult result = await client.RegisterLocationAsync(
new RegisterLocationRequest(new CashRegisterLocation(cashRegisterCode, location)),
cancellationToken);
```
## Adresa
| Vlastnosť | Popis | Pravidlá |
|---|---|---|
| `streetName` | ulica. Ak obec nemá ulice, názov obce. | povinná, 1 – 100 znakov |
| `municipality` | obec alebo mesto | povinná, 1 – 100 znakov |
| `buildingNumber` | orientačné číslo alebo názov budovy | nepovinná, 1 – 20 znakov |
| `propertyRegistrationNumber` | súpisné číslo | nepovinná, 1 – 9 999 999 999 |
| `postalCode` | PSČ | nepovinná, presne 5 číslic |
Texty nesmú obsahovať riadiace znaky.
**HTTP API:**
```http
POST http://localhost:3010/api/v1/requests/locations/address
```
```json
{
"data": {
"cashRegisterCode": "88812345678900001",
"location": {
"streetName": "Kresánkova",
"buildingNumber": "12",
"propertyRegistrationNumber": 3597,
"municipality": "Bratislava",
"postalCode": "84105"
}
}
}
```
**.NET knižnica:**
```csharp
var location = new PhysicalAddress(
streetName: "Kresánkova",
municipality: "Bratislava",
buildingNumber: "12",
postalCode: "84105",
propertyRegistrationNumber: 3597);
RegisterLocationResult result = await client.RegisterLocationAsync(
new RegisterLocationRequest(new CashRegisterLocation(cashRegisterCode, location)),
cancellationToken);
```
## Voľný text
Ak adresa ani súradnice nie sú k dispozícii, opíšte polohu textom s dĺžkou 1 až 255 znakov. Typicky ide
o evidenčné číslo vozidla a miesto, napríklad `Taxi ABC, EČV BA123AA, odpočívadlo Zeleneč D1`.
**HTTP API:**
```http
POST http://localhost:3010/api/v1/requests/locations/other
```
```json
{
"data": {
"cashRegisterCode": "88812345678900001",
"location": {
"value": "Taxi ABC, EČV BA123AA"
}
}
}
```
**.NET knižnica:**
```csharp
var location = new CashRegisterOtherLocation("Taxi ABC, EČV BA123AA");
RegisterLocationResult result = await client.RegisterLocationAsync(
new RegisterLocationRequest(new CashRegisterLocation(cashRegisterCode, location)),
cancellationToken);
```
## Ochrana pred duplicitou
Aj registrácia polohy sa odosiela do systému eKasa ako dátová správa, preto jej rovnako ako dokladu priraďte
`externalId`. Ak sa odpoveď stratí a registráciu zopakujete s rovnakým `externalId`, eKasa vráti pôvodný výsledok
namiesto novej registrácie. Podrobnosti sú v článku [Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id).
**HTTP API:**
```json
{
"data": {
"cashRegisterCode": "88812345678900001",
"location": {
"latitude": 48.148962,
"longitude": 17.165377
}
},
"externalId": "poloha-2026-11-19-0800"
}
```
**.NET knižnica:**
```csharp
var request = new RegisterLocationRequest(
"poloha-2026-11-19-0800", new CashRegisterLocation(cashRegisterCode, location));
```
## Výsledok
Registrácia polohy sa do systému eKasa odosiela ako doklad a výsledok má rovnakú štruktúru: `isSuccessful` je
`true` pri online registrácii, `null` pri offline registrácii (poloha čaká vo fronte) a `false`, keď ju systém
eKasa odmietol. Pozri [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result).
**HTTP API:**
Aktuálne zaregistrovanú polohu zistíte cez `GET /api/v1/requests/locations/current?cashRegisterCode=…`,
prípadne ju [vyhľadáte](https://ekasa.ninedigit.sk/docs/receipt-lookup) ako ostatné záznamy.
**.NET knižnica:**
Aktuálne zaregistrovanú polohu zistíte metódou `client.FindLatestLocationAsync(cashRegisterCode, cancellationToken)`,
prípadne ju [vyhľadáte](https://ekasa.ninedigit.sk/docs/receipt-lookup) ako ostatné záznamy.
## Časté otázky
**Ktorý formát mám použiť?**
Ideálne adresu alebo GPS súradnice. Voľný text použite pre evidenčné číslo vozidla alebo vtedy, keď adresa nie je
k dispozícii.
**Môžem použiť viac formátov naraz?**
Nie. Každá registrácia nahradí predchádzajúcu, platí len posledná zaregistrovaná poloha.
**Kedy musím polohu zaregistrovať?**
Len pri prenosnej pokladnici: keď ešte nemá zaregistrovanú polohu alebo keď sa od poslednej registrácie zmenilo
miesto predaja.
**Ako často ju musím meniť?**
Vždy, keď zmeníte miesto, kde prijímate tržby.
**Má poloha exspiráciu?**
Nie. Platí, kým nezaregistrujete novú.
**Čo ak polohu nezaregistrujem?**
Finančná správa vie zistiť, že prenosná pokladnica polohu nemá alebo že nezodpovedá miestu predaja. Neoznámenie
polohy je správny delikt ([§ 16 písm. i) zákona 384/2025](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260228#paragraf-16.pismeno-i)). Pri prvom zistení vás
daňový alebo colný úrad vyzve na odstránenie nedostatku, pri druhom uloží pokutu od 30 do 200 € a pri každom ďalšom
od 60 do 400 € ([§ 17 ods. 1 písm. c) a ods. 2 písm. c)](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260228#paragraf-17.odsek-1.pismeno-c)).
## Kam ďalej
- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Kedy registráciu polohy potrebujete vo svojom softvéri.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Vyhľadanie záznamov](https://ekasa.ninedigit.sk/docs/receipt-lookup): Doklady a polohy podľa čísla alebo dátumu.
---
# Kontrola stavu systému
> Stav eKasy jedným volaním cez /api/v1/health aj jednotlivé kontroly: inicializačný balík, certifikát, úložisko, tlačiareň, spojenie a fronta.
Zdroj: https://ekasa.ninedigit.sk/docs/status
Kontrola stavu upozorní obsluhu na problém skôr, než zastaví predaj: dochádzajúci papier, končiacu platnosť
autentifikačných údajov, plné úložisko alebo doklady, ktoré čakajú na odoslanie. Odporúčame ju volať pri spustení
vášho softvéru a potom pravidelne (pozri [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope#optim%C3%A1lna-integr%C3%A1cia)).
Stav sa skladá zo šiestich oblastí a každú overíte samostatným volaním:
- [Identifikačné a autentifikačné údaje](#kompletný-inicializačný-balík) (`subject`): Či má pokladnica nahraný inicializačný balík.
- [Platnosť certifikátu](#blížiaca-sa-exspirácia-certifikátu) (`subject`): Upozornenie 30 dní pred koncom platnosti.
- [Úložisko](#overenie-stavu-úložiska) (`storage`): Stav a zaplnenie chráneného dátového úložiska.
- [Tlačiareň](#kontrola-stavu-tlačiarne) (`printer`): Papier, kryt a pripravenosť tlačiarne.
- [Spojenie](#kontrola-stavu-internetového-spojenia-so-systémom-ekasa) (`network`): Spojenie so systémom eKasa.
- [Fronta](#kontrola-obsahu-fronty-neodoslaných-správ) (`queue`): Dátové správy, ktoré čakajú na odoslanie.
**HTTP API:**
## Stav jedným volaním
V HTTP API zistíte stav všetkých oblastí naraz jedným volaním:
```http
GET http://localhost:3010/api/v1/health
```
```json
{
"status": "Degraded",
"totalDuration": 27,
"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": "Degraded",
"description": "Tlačiareň je pripravená. Papier v tlačiarni sa míňa."
},
{
"name": "storage",
"status": "Healthy",
"description": "Chránené dátové úložisko je v poriadku."
},
{
"name": "network",
"status": "Healthy",
"description": "Spojenie so serverom finančnej správy je v poriadku."
},
{
"name": "license",
"status": "Healthy",
"description": "Licencia je v poriadku."
}
]
}
```
Celkový `status` je najhorší stav zo všetkých kontrol:
| Stav | Význam | Čo urobiť |
|---|---|---|
| `Healthy` | všetko v poriadku | nič |
| `Degraded` | blíži sa problém, predaj zatiaľ funguje | upozornite obsluhu |
| `Unhealthy` | problém, ktorý treba riešiť hneď | upozornite obsluhu výrazne, predaj môže zlyhať |
Odpoveď má stavový kód HTTP `200` pri každom stave, rozhoduje pole `status`. Text v `description` je po slovensky
a môžete ho obsluhe rovno zobraziť. Pole `data` obsahuje podrobnosti danej kontroly, napríklad údaje o certifikáte.
| Kontrola (`name`) | Čo sleduje |
|---|---|
| `queue` | dátové správy čakajúce na odoslanie; podnikateľ ich musí odoslať do 96 hodín |
| `subject` | identifikačné a autentifikačné údaje a platnosť certifikátu |
| `printer` | pripravenosť tlačiarne a papier |
| `storage` | stav a zaplnenie úložiska |
| `network` | spojenie so systémom eKasa |
| `license` | licenciu eKasy |
| `Expose` | spojenie cez Expose, ak ho používate |
Od verzie 9.1:
- kontroly môžete obmedziť parametrom `tag`, napríklad `?tag=storage,queue` (bez neho sa vykonajú všetky),
- s parametrom `details=false` dostanete len stavy bez popisu a údajov, aj bez prihlásenia. Hodí sa na monitorovanie,
či služba beží,
- pribudli kontroly `indexTable` (tabuľka indexov úložiska) a `hosting` (HTTP a HTTPS).
### Úložisko SwissBit na Androide
Pri úložisku SwissBit v platobnom termináli môže kontrola `storage` vrátiť stav `Degraded` s akciou, ktorú musí
obsluha urobiť na zariadení. Aplikácia eKasa na ňu obsluhu upozorní aj sama.
| `data.storageAction` | Čo urobiť | Kde nastáva |
|---|---|---|
| `GrantStorageAccess` | povoliť aplikácii prístup ku všetkým súborom v nastaveniach zariadenia | Sunmi |
| `RebootDevice` | reštartovať zariadenie, aby sa dokončila príprava úložiska | PAX, pri prvom spustení |
```json
{
"name": "storage",
"status": "Degraded",
"description": "Chránené dátové úložisko vyžaduje reštart zariadenia na dokončenie prípravy.",
"data": { "storageAction": "RebootDevice" }
}
```
**.NET knižnica:**
## Kontroly v knižnici
.NET knižnica jednotný stav jedným volaním nemá. Ten skladá služba eKasy z rovnakých metód, aké máte k dispozícii
aj vy. Každú oblasť overíte vlastnou metódou a stav vyhodnotíte vo svojom softvéri:
| Oblasť (`name` v HTTP API) | Metóda knižnice | Podrobnosti |
|---|---|---|
| `subject` | `client.IdentityManager.FindLatestIdentitiesAsync()`, `client.CertificateManager.FindLatestValidCertificateInfoAsync()` | [údaje](#kompletný-inicializačný-balík), [certifikát](#blížiaca-sa-exspirácia-certifikátu) |
| `storage` | `client.GetStorageInfoAsync()` | [úložisko](#overenie-stavu-úložiska) |
| `printer` | `client.GetPrinterStatusInfoAsync()` | [tlačiareň](#kontrola-stavu-tlačiarne) |
| `network` | `client.ConnectivityMonitor.GetStateAsync()` | [spojenie](#kontrola-stavu-internetového-spojenia-so-systémom-ekasa) |
| `queue` | `client.InitializeQueueAsync()`, `client.Queue.Filter()` | [fronta](#kontrola-obsahu-fronty-neodoslaných-správ) |
| `license` | `client.VerifyLicenseAsync()` | |
| `indexTable` | `client.GetIndexTableStatusAsync()` | |
## Kompletný inicializačný balík
Aby bolo možné on-line pokladnicu (identifikovanú kódom pokladnice) používať, musí byť do eKasy vložený
*inicializačný balík*. Skladá sa z **identifikačných** údajov (v eKase `Identity`) a **autentifikačných** údajov
(`Certificate`).
Kompletnosť inicializačného balíka nie je nutné explicitne kontrolovať. Všetky funkcie eKasy, ktoré balík potrebujú,
preberajú kód pokladnice (`cashRegisterCode`) ako parameter a stav balíka si overia samy.
Ak potrebujete zo svojho softvéru získať zaregistrované identifikačné alebo autentifikačné údaje, použite volania nižšie.
### Získanie identifikačných údajov
**HTTP API:**
```http
GET {server_address}/api/v1/identities
```
**.NET knižnica:**
```csharp
IReadOnlyList identities = await client.IdentityManager.FindLatestIdentitiesAsync(cancellationToken);
```
### Získanie autentifikačných údajov
**HTTP API:**
```http
GET {server_address}/api/v1/certificates
```
**.NET knižnica:**
```csharp
CertificateInfo? certificate = await client.CertificateManager.FindLatestCertificateInfoAsync(
"88812345678900001", cancellationToken);
```
## Blížiaca sa exspirácia certifikátu
Každý certifikát má obmedzenú platnosť, preto kontrolujte aj dátum jeho exspirácie. Vlastnosť `expirationDate`
obsahuje dátum exspirácie, `daysToExpire` počet dní do exspirácie, `isAboutToExpire` je `true` 30 dní pred
exspiráciou a `isExpired` je `true` po exspirácii.
**Platný**: 2 roky od vydania, stav Healthy
→ 30 dní pred koncom
**Blíži sa koniec**: isAboutToExpire, stav Degraded
→ deň exspirácie
**Exspirovaný**: isExpired, stav Unhealthy
Na koniec platnosti musí pokladnica upozorniť najneskôr 30 dní vopred
([§ 5 ods. 3 písm. q) zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-q)). Nové autentifikačné údaje si podnikateľ
vygeneruje na portáli finančnej správy a nahrá do eKasy ešte pred exspiráciou.
### Overenie existencie platného certifikátu
**HTTP API:**
```http
GET {server_address}/api/v1/certificates/valid/latest?cashRegisterCode=88812345678900001
```
Ak pokladnica platný certifikát nemá, odpoveď je `404 Not Found`.
**.NET knižnica:**
```csharp
CertificateInfo? certificate = await client.CertificateManager.FindLatestValidCertificateInfoAsync(
"88812345678900001", cancellationToken);
```
Ak pokladnica platný certifikát nemá, metóda vráti `null`.
Vzorový výstup s údajmi o certifikáte:
```json
{
"alias": "88812345678900001",
"cashRegisterCode": "88812345678900001",
"issueDate": "2025-03-12T09:41:07+01:00",
"expirationDate": "2027-03-12T09:41:07+01:00",
"serialNumber": "2B0A",
"isNotYetValid": false,
"isValid": true,
"isAboutToExpire": false,
"daysToExpire": 113,
"isExpired": false
}
```
Kód pokladnice čítajte z poľa `cashRegisterCode`. Pole `alias` je pomenovanie certifikátu a dnes má rovnakú
hodnotu, na jeho formát sa však nespoliehajte. Certifikačná autorita ho môže v budúcnosti zmeniť.
## Overenie stavu úložiska
Chránené dátové úložisko má obmedzenú kapacitu a po zaplnení ho treba vymeniť. Na blížiace sa zaplnenie upozornite
obsluhu vopred, pri integrácii je to úloha vášho softvéru
(pozri [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope#optim%C3%A1lna-integr%C3%A1cia)).
### Získanie informácie o úložisku
**HTTP API:**
```http
GET {server_address}/api/v1/storage/info
```
**.NET knižnica:**
```csharp
StorageInfo storageInfo = await client.GetStorageInfoAsync(cancellationToken);
```
Vzorový výstup informácie o úložisku:
```json
{
"product": {
"vendorName": "Nine Digit, s.r.o.",
"name": "eKasa CHDÚ",
"version": "v1.0",
"serialNumber": "3A21D0E474C0"
},
"capacity": {
"total": 8589934592,
"used": 2173430
},
"isReadOnly": false
}
```
| Vlastnosť | Popis |
|---|---|
| `product` | dodávateľ (`vendorName`), názov (`name`), verzia (`version`) a sériové číslo (`serialNumber`) úložiska |
| `capacity` | celková (`total`) a použitá (`used`) kapacita úložiska v bajtoch |
| `isReadOnly` | `true`, ak je úložisko nevratne prepnuté do režimu iba na čítanie |
Podielom `used` a `total` vyčíslite obsadenosť úložiska a od určitej hranice (napríklad 80 %) zobrazte obsluhe
upozornenie o blížiacom sa zaplnení.
Režim iba na čítanie sa používa, keď bolo úložisko úmyselne vyradené z prevádzky. Údaje z neho sa dajú ďalej čítať.
## Kontrola stavu tlačiarne
Získanie informácie o stave tlačiarne:
**HTTP API:**
```http
GET {server_address}/api/v1/printers/status
```
**.NET knižnica:**
```csharp
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);
```
Príklad stavu tlačiarne:
```json
{
"state": "Ready",
"paperState": "Ready",
"errorState": "None"
}
```
Popis jednotlivých hodnôt, príklady pre konkrétne situácie, prehľad toho, čo ktoré zariadenie hlási, a správanie
aplikácie pri nepripravenej tlačiarni nájdete v článku [Stav tlačiarne](https://ekasa.ninedigit.sk/docs/printer-status).
## Kontrola stavu internetového spojenia so systémom eKasa
Získanie informácie o stave internetového spojenia so systémom eKasa:
**HTTP API:**
```http
GET {server_address}/api/v1/connectivity/status
```
**.NET knižnica:**
```csharp
InternetConnectionStateInfo connection = await client.ConnectivityMonitor.GetStateAsync(cancellationToken);
```
Príklad stavu internetového pripojenia:
```json
{
"requestDate": "2026-11-19T08:13:25Z",
"state": "Up"
}
```
Vlastnosť `requestDate` je čas zistenia stavu v UTC. Stav internetového pripojenia (vlastnosť `state`) nadobúda
niektorú z nasledovných hodnôt:
- `Up`: internetové spojenie je dostupné,
- `Down`: internetové spojenie nie je dostupné,
- `Unknown`: neznámy stav.
eKasa sama sleduje stav spojenia so systémom eKasa. Ak sú vo fronte neodoslané dátové správy (napríklad doklady
vyhotovené v offline režime), pokúsi sa ich odoslať hneď, ako zistí, že spojenie je opäť dostupné.
## Kontrola obsahu fronty neodoslaných správ
Podnikateľ je povinný odoslať dátovú správu (doklad alebo registráciu polohy) 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)). S povolením daňového úradu na
odklad odosielania (predajné miesto bez internetového signálu) je lehota 30 dní
([§ 4 ods. 3](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-4.odsek-3)).
Preto je vhodné sledovať, či vo fronte nie sú dátové správy, ktoré sa nepodarilo odoslať.
### Počet neodoslaných dátových správ pre konkrétny kód pokladnice (odporúčaný postup)
**HTTP API:**
```http
HEAD {server_address}/api/v1/queue/items/unprocessed?cashRegisterCode=88812345678900001
```
Odpoveď má stavový kód `204` a počet správ je v hlavičke `Content-Range`.
**.NET knižnica:**
```csharp
var filter = new RegisterTokenFilter
{
State = RegisterTokenFilterState.Unprocessed,
CashRegisterCode = "88812345678900001"
};
// fronta musí byť pred získaním jej položiek inicializovaná
await client.InitializeQueueAsync(cancellationToken);
int count = client.Queue.Filter(new RegisterTokenQuery(filter)).Count;
```
### Počet neodoslaných dátových správ pre všetky kódy pokladníc
Alternatívne, no časovo náročnejšie, zistíte počet neodoslaných dátových správ pre všetky kódy pokladníc takto:
**HTTP API:**
```http
HEAD {server_address}/api/v1/requests?status=unprocessed
```
Počet správ je v hlavičke `Content-Range`.
**.NET knižnica:**
```csharp
var query = new RegistrationQuery();
query.Filter.ProcessStatus = RegistrationRecordProcessStatus.Unprocessed;
QueryCountResult result = await client.CountRegistrationsAsync(query, cancellationToken);
```
## Kam ďalej
- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Kedy a ako často stav kontrolovať.
- [Stav tlačiarne](https://ekasa.ninedigit.sk/docs/printer-status): Hodnoty stavu a správanie pri nepripravenej tlačiarni.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Offline doklady a fronta neodoslaných správ.
---
# Stav tlačiarne
> Stav tlačiarne cez API alebo .NET knižnicu: pripravenosť, stav papiera a druh chyby, čo hlási ktoré zariadenie a čo robí eKasa pri nepripravenej tlačiarni.
Zdroj: https://ekasa.ninedigit.sk/docs/printer-status
Stav tlačiarne zistíte pred vyhotovením dokladu, napríklad aby ste obsluhu upozornili na dochádzajúci papier alebo
otvorený kryt. Odpoveď obsahuje celkovú pripravenosť (`state`), stav papiera (`paperState`) a druh chyby
(`errorState`).
**HTTP API:**
```http
GET {server_address}/api/v1/printers/status
```
**.NET knižnica:**
```csharp
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);
```
Príklad stavu tlačiarne:
```json
{
"state": "Ready",
"paperState": "Ready",
"errorState": "None"
}
```
## Vlastnosť `state`
Celkový stav pripravenosti tlačiarne.
| Hodnota | Popis |
|---|---|
| `Ready` | Tlačiareň je pripravená. |
| `Error` | Tlačiareň nie je pripravená (zaneprázdnená alebo v chybovom stave). |
| `Unknown` | Stav sa nepodarilo zistiť (najmä v dôsledku inej chyby). |
## Vlastnosť `paperState`
*Dostupné od verzie `6.6`.*
Stav papiera a mechaniky. Hodnota `null` znamená, že použité úložisko alebo tlačiareň túto informáciu neposkytuje. Nejde teda o tvrdenie, že papier je v poriadku.
| Hodnota | Popis |
|---|---|
| `Ready` | Papier je správne vložený a pripravený na tlač. |
| `NearEnd` | Rolka je takmer prázdna. Tlač pokračuje, ide o varovanie. |
| `Empty` | V tlačiarni nie je vložený papier. |
| `CoverOpen` | Kryt tlačiarne je otvorený. |
| `PaperJam` | Papier v tlačiarni je zaseknutý. |
| `null` | Stav papiera nie je k dispozícii. |
## Vlastnosť `errorState`
*Dostupné od verzie `9.0.6`.*
Druh chyby, ktorá sa netýka papiera.
| Hodnota | Popis |
|---|---|
| `None` | Tlačiareň odpovedala a nenachádza sa v stave súvisiacom s chybou v tejto sekcii. |
| `CutterError` | Chyba automatickej rezačky papiera (nožníc). |
| `Recoverable` | Chyba, ktorá je dočasná a pominie sama po odstránení príčiny, napríklad prehriata tlačová hlava alebo nízke napájacie napätie. |
| `Unrecoverable` | Porucha, ktorú nemožno odstrániť bez zásahu do zariadenia. Volajúcemu je odporúčané kontaktovanie servisu. |
| `null` | Príčinu nie je možné zistiť. Tlačiareň alebo pripojené zariadenie tento typ chybového stavu nehlási. |
Hodnoty `None` a `null` neznamenajú to isté. `None` je odpoveď tlačiarne, že žiadnu chybu netýkajúcu sa papiera nehlási, príčina teda leží inde. `null` znamená, že zariadenia alebo tlačiarne sa na príčinu nedá spýtať.
## Príklady podľa situácie
Pripravená tlačiareň s dostatkom papiera:
```json
{
"state": "Ready",
"paperState": "Ready",
"errorState": "None"
}
```
Dochádzajúca rolka, tlač pokračuje, ide o varovanie:
```json
{
"state": "Ready",
"paperState": "NearEnd",
"errorState": "None"
}
```
Prázdna rolka:
```json
{
"state": "Error",
"paperState": "Empty",
"errorState": "None"
}
```
Otvorený kryt:
```json
{
"state": "Error",
"paperState": "CoverOpen",
"errorState": "None"
}
```
Otvorený kryt spolu s chybou, kryt a chyba sa nevylučujú:
```json
{
"state": "Error",
"paperState": "CoverOpen",
"errorState": "CutterError"
}
```
Chyba rezačky hlásená vstavanou tlačiarňou, ktorá stav papiera popri chybe nehlási:
```json
{
"state": "Error",
"paperState": null,
"errorState": "CutterError"
}
```
Úložisko, ktoré stav papiera ani príčinu chyby neposkytuje (napríklad CHDÚ-SK):
```json
{
"state": "Ready",
"paperState": null,
"errorState": null
}
```
Tlačiareň neodpovedala:
```json
{
"state": "Unknown",
"paperState": null,
"errorState": null
}
```
## Čo ktoré zariadenie hlási
| Pripojenie tlačiarne | `state` | `paperState` | `errorState` |
|---|---|---|---|
| CHDÚ-SK | áno | vždy `null` | vždy `null` |
| CHDÚ Lite, firmvér starší ako `v1.4` | áno | vždy `null` | vždy `null` |
| CHDÚ Lite, firmvér `v1.4` a novší | áno | `Ready`, `NearEnd`, `Empty`, `CoverOpen` | vždy `null` |
| Externá cez USB (ESC/POS) | áno | áno, všetky hodnoty | áno, vrátane `None` |
| Vstavaná (zariadenie Sunmi) | áno | `Ready`, `NearEnd`, `Empty`, `CoverOpen`, `PaperJam` | len konkrétna príčina, inak `null` |
| Vstavaná (zariadenie PAX) | áno | `Ready`, `Empty`, `CoverOpen`, `PaperJam` | len konkrétna príčina, inak `null` |
| Vstavaná (zariadenie Ingenico) | áno | `Ready`, `NearEnd`, `Empty`, `CoverOpen`, `PaperJam` | len konkrétna príčina, inak `null` |
| Zariadenie bez podporovanej tlačiarne | vždy `Ready` | vždy `null` | vždy `null` |
Vstavané tlačiarne hlásia cez sadu výrobcu vždy jedinú hodnotu stavu, takže z nej nemožno usúdiť, že žiadna ďalšia chyba nenastala. Preto pri nich `errorState` nikdy nenadobudne hodnotu `None`. Buď obsahuje konkrétnu príčinu, alebo `null`.
## Správanie pri nepripravenej tlačiarni
V závislosti od spôsobu pripojenia tlačiarne je reakcia aplikácie na jej chybový stav rozdielna.
| Pripojenie tlačiarne | Doklad sa vyhotoví | Správanie na nepripravenosť tlačiarne |
|----|----|----|
| `CHDU-SK` | áno | Chybový stav tlačiarne (napríklad ak ju obsluha nezapla do elektrickej siete) neovplyvňuje činnosť aplikácie, po zapnutí sa údaje z úložiska dodatočne (v rámci veľkosti bufferu) zašlú do tlačiarne. Ak sa však vnútorný buffer úložiska zaplní (odhadom 10 – 12 účteniek), úložisko sa zablokuje a pre jeho ďalšiu činnosť je potrebné ho vypnúť a zapnúť. |
| `CHDU Lite` | nie | Pri chybovom stave tlačiarne sa pokus o registráciu dokladu ihneď skončí chybou. Zariadenie nemá vstavaný buffer pre dodatočné doposlanie tlačového výstupu. |
| Vstavaná tlačiareň zariadenia (Sunmi, Pax, Ingenico, ..) | nie | Pri chybovom stave tlačiarne sa pokus o registráciu dokladu skončí chybou. |
| Externá cez USB | nie | Pripravenosť sa overuje pred zápisom dokladu do chráneného dátového úložiska, takže pri chybe doklad vôbec nevznikne. Doklad, ktorý sa nepodarí vytlačiť, sa nikdy netlačí znova, nakoľko originál smie byť vyhotovený len raz. |
CHDÚ-SK je jediný typ úložiska, pri ktorom doklad vznikne aj vtedy, keď tlačiareň nie je pripravená. Úložisko si tlačový výstup odloží do vnútornej pamäte (buffer) a vytlačí ho dodatočne. Pri všetkých ostatných sa pripravenosť tlačiarne overuje pred vyhotovením dokladu, takže doklad, ktorý sa nedá vytlačiť, vôbec nevznikne. Nejde o odporúčaný režim prevádzky, nakoľko veľkosť buffera je limitovaná a vyústi v neresponzívny stav úložiska.
---
# QR platby
> Platba QR kódom cez notifikátor okamžitých platieb finančnej správy: priebeh, štyri kroky v HTTP API aj .NET, stavy platby, oznámenie o nepotvrdení a časté otázky.
Dostupné od verzie: Windows 8.0.1, macOS 8.0.1, Linux 9.0.2, Android 8.0.1, .NET knižnica (PPEKK) 8.0.1
Zdroj: https://ekasa.ninedigit.sk/docs/qr-payments
QR platba je bezhotovostná platba bez platobného terminálu. Zákazník naskenuje QR kód v aplikácii svojej banky
a zaplatí okamžitým prevodom. O prijatí platby informuje pokladnicu **notifikátor okamžitých platieb** (NOP), ktorý
prevádzkuje finančná správa. eKasa s ním komunikuje za vás.
QR platba je **samostatný krok pred registráciou dokladu**. Údaje dokladu sa pri nej neposielajú. Keď je platba
potvrdená, váš softvér zaregistruje doklad ako pri inej bezhotovostnej platbe.
## Priebeh platby
```mermaid
sequenceDiagram
autonumber
participant S as Váš softvér
participant K as eKasa
participant Z as Zákazník
participant F as Finančná správa (NOP)
S->>K: vytvor platbu (suma)
K->>F: žiadosť o ID platby
F-->>K: ID platby a platobný odkaz
K-->>S: ID platby a odkaz
S->>Z: QR kód na displeji alebo papieri
Z->>F: platba v aplikácii banky
S->>K: stav platby?
K-->>S: zaplatené
S->>K: registrácia dokladu
```
## Kroky
- [ID platby](#1-id-platby): Vytvorenie platby so sumou. Výsledkom je ID platby a platobný odkaz.
- [QR kód](#2-qr-kód-pre-zákazníka): Zobrazenie QR kódu na displeji vášho softvéru alebo cez eKasu.
- [Stav platby](#3-čakanie-na-platbu): Čakanie na potvrdenie platby a jej výsledok.
- [Oznámenie o nepotvrdení](#4-oznámenie-o-nepotvrdení-platby): Doklad, keď platba nepríde včas.
Všetky polia požiadaviek a odpovedí s príkladmi sú v [referencii HTTP API](https://ekasa.ninedigit.sk/docs/rest-api/reference#tag/payments),
v .NET knižnici v triede `QrPayment` a službe `IQrPaymentService`. Nižšie je len to, čo z referencie nevyčítate.
### 1. ID platby
Každá QR platba má jedinečné ID, ktoré pridelí finančná správa. Pošlete sumu a kód pokladnice, eKasa požiada
o ID platby a vráti ho spolu s platobným odkazom pre QR kód. ID si uložte: podľa neho zistíte stav platby aj vtedy,
keď sa proces medzitým preruší.
**HTTP API:**
```http
POST {server_address}/api/v1/payments/qr
Content-Type: application/json
{
"amount": 19.90,
"cashRegisterCode": "88812345678900001",
"comment": "textova poznamka",
"recipientMessage": "eKasa QR platba"
}
```
| Výsledok | Čo robiť |
|---|---|
| `201 Created` | ID platby je v `transactionId`, platobný odkaz v `links`. |
| `500`, kód [`-701`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-701-qrpaymentinitializationerror) | Platbu sa nepodarilo vytvoriť, požiadavku opakujte. |
**.NET knižnica:**
```csharp
IQrPaymentService qrPaymentService = client.QrPaymentService;
var request = new QrPaymentRequest(
cashRegisterCode: "88812345678900001",
amount: 19.90m,
comment: "textova poznamka",
recipientMessage: "eKasa QR platba");
IQrPaymentSession session = await qrPaymentService
.InitiatePaymentAsync(request, cancellationToken);
QrPaymentTransactionId transactionId = session.Payment.TransactionId;
```
| Výsledok | Čo robiť |
|---|---|
| `session.Payment` | aktuálna platba, ID je v `TransactionId`; platobný odkaz vytvoríte metódou `CreatePaymentLink(QrPaymentLinkScheme.PaymeVersion2Point0)` |
| `session.Completion` | úloha, ktorá sa dokončí, keď platba prejde do konečného stavu (krok 3) |
| `QrPaymentInitializationException` | platbu sa nepodarilo vytvoriť, vytvorenie opakujte |
Nepovinné údaje:
- `comment`: poznámka k platbe, eKasa ju pošle do notifikátora okamžitých platieb (NOP) pri generovaní ID platby.
- `recipientMessage`: správa pre príjemcu v platobnom odkaze, zobrazí sa na bankovom výpise. Ak chýba, použije sa
hodnota z [nastavení](https://ekasa.ninedigit.sk/docs/qr-payments/environment-setup#spr%C3%A1va-pre-pr%C3%ADjemcu).
### 2. QR kód pre zákazníka
Obsahom QR kódu je platobný odkaz [Payme](https://www.payme.sk) podľa
[štandardu SBA](https://www.sbaonline.sk/projekt/standard-platobnej-linky/), ktorý je vo vlastnosti `links` odpovede
na vytvorenie platby. QR kód môže zobraziť:
- **váš softvér** na displeji pokladnice alebo zákazníckom displeji,
- **eKasa**, ak váš softvér takú možnosť nemá. Vytlačí QR kód na tlačiarni pokladnice ako papierový ústrižok, takže
na QR platby netreba žiadny ďalší hardvér:
**HTTP API:**
```http
POST {server_address}/api/v1/payments/qr/{transactionId}/render
Content-Type: application/json
{
"rendererName": "posPrinter"
}
```
Odpoveď `204 No Content` znamená, že QR kód je vytlačený. Ak platba neexistuje, vráti sa `404 Not Found`.
**.NET knižnica:**
```csharp
await qrPaymentService.RenderPaymentAsync(
transactionId, QrPaymentRendererName.PosPrinter, cancellationToken);
```
Ak platba neexistuje, metóda vyhodí `QrPaymentNotFoundException`.
Iný spôsob vyobrazenia ako tlačiareň pokladnice (`posPrinter`) eKasa zatiaľ nemá. Vlastný papierový výstup s QR
kódom vytlačíte ako [nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt) s tokenom QR kódu
(pozri [Tokeny a formátovanie textu](https://ekasa.ninedigit.sk/docs/token-syntax)).
### 3. Čakanie na platbu
Váš softvér sa pýta eKasy na stav platby, kým nepríde potvrdenie alebo neuplynie čas čakania. Čas čakania si
nastavíte v softvéri. Zákon ho neurčuje, z praxe odporúčame **90 sekúnd**. Pokladník by mal vedieť čakanie aj
prerušiť.
**HTTP API:**
```http
GET {server_address}/api/v1/payments/qr/{transactionId}?await=true
```
S `await=true` sa odpoveď vráti až po prechode do konečného stavu, bez neho (predvolené `false`) hneď s aktuálnym
stavom. Stav je vo vlastnosti `status`. Ak sa platba nenašla, vráti sa `404 Not Found`
([`-702`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-702-qrpaymentnotfounderror)).
**.NET knižnica:**
```csharp
// aktuálny stav kedykoľvek
QrPayment current = session.Payment;
// čakanie na konečný stav: Paid, Overpaid alebo Expired
QrPayment payment = await session.Completion;
QrPaymentStatus status = payment.GetStatus(DateTimeOffset.Now);
// stav platby podľa ID, napríklad po reštarte vášho softvéru
QrPayment? found = await qrPaymentService.FindPaymentAsync(transactionId, cancellationToken);
```
Relácia z kroku 1 sleduje stav platby priebežne. `FindPaymentAsync` vráti `null`, ak sa platba nenašla.
#### Stavy platby
Konečné stavy sú `paid`, `overpaid` a `expired`. V .NET knižnici má `QrPaymentStatus` rovnaké hodnoty s veľkým
začiatočným písmenom (`Pending`, `Paid`, …).
| Hodnota | Popis |
|---|---|
| `pending` | Platba bola vytvorená, ale zatiaľ nebola prijatá žiadna úhrada. |
| `partiallyPaid` | Prijatá čiastočná úhrada, platba zatiaľ nie je úplne zaplatená. |
| `paid` | Platba je úplne uhradená: prijatá suma sa rovná požadovanej sume. |
| `overpaid` | Prijatá suma presahuje požadovanú hodnotu (preplatok). |
| `expired` | Platba vypršala pred úplnou úhradou. |
```mermaid
stateDiagram-v2
[*] --> pending
pending --> partiallyPaid: časť sumy
pending --> paid: celá suma
pending --> overpaid: viac ako suma
partiallyPaid --> paid: doplatok
partiallyPaid --> overpaid: doplatok navyše
pending --> expired: bez úhrady
partiallyPaid --> expired: bez úplnej úhrady
paid --> [*]
overpaid --> [*]
expired --> [*]
```
Pri `paid` a `overpaid` zaregistrujte doklad podľa skutočne prijatej sumy, pri `expired` pokračujte krokom 4.
### 4. Oznámenie o nepotvrdení platby
Ak potvrdenie nepríde včas alebo pokladník čakanie preruší, pokladnica musí vyhotoviť alebo sprístupniť **doklad
o nepotvrdení zrealizovanej platby** ([§ 15 ods. 3 zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-15.odsek-3)). Povinné údaje dokladu
podľa [Finančnej správy](https://podpora.financnasprava.sk/121316-Bezhotovostn%C3%A1-platba) sú dátum a čas vygenerovania ID platby, ID platby a suma, nepovinné názov a DIČ
podnikateľa. eKasa vytlačí všetky, názov a DIČ v hlavičke podnikateľa:
[Obrázok: Oznámenie o neúspešnej platbe: hlavička podnikateľa, nadpis Potvrdenie k žiadosti o vrátenie okamžitej úhrady, dátum a čas vytvorenia platby, ID transakcie a suma]
**HTTP API:**
```http
POST {server_address}/api/v1/payments/qr/{transactionId}/print_non_delivery_notice
```
Požiadavka nemá telo. Odpoveď `204 No Content` znamená, že oznámenie je vytlačené, `404 Not Found`, že platba
neexistuje.
**.NET knižnica:**
```csharp
if (status == QrPaymentStatus.Expired)
{
await qrPaymentService.PrintPaymentNonDeliveryNoticeAsync(
transactionId, cancellationToken);
}
```
Ak platba neexistuje, metóda vyhodí `QrPaymentNotFoundException`.
## Vyskúšanie platby
Platbu vyskúšate bez vlastného kódu vo webovom rozhraní eKasy. V integračnom prostredí ju namiesto banky zaplatí naša
testovacia utilita, takže môžete skúsiť aj čiastočnú platbu alebo preplatok. Postup je v článku
[Príprava a test](https://ekasa.ninedigit.sk/docs/qr-payments/environment-setup#test-platby).
**.NET knižnica:**
## Celý príklad v .NET
Celý priebeh platby cez .NET knižnicu: vytvorenie, tlač QR kódu, čakanie na výsledok a oznámenie o nepotvrdení.
```csharp
IQrPaymentService qrPaymentService = client.QrPaymentService;
var request = new QrPaymentRequest(cashRegisterCode: "88812345678900001", amount: 19.90m);
// 1. ID
IQrPaymentSession session = await qrPaymentService.InitiatePaymentAsync(request, cancellationToken);
QrPaymentTransactionId transactionId = session.Payment.TransactionId;
// 2. QR
await qrPaymentService.RenderPaymentAsync(transactionId, QrPaymentRendererName.PosPrinter, cancellationToken);
// 3. Paid, Overpaid, Expired
QrPayment payment = await session.Completion;
QrPaymentStatus status = payment.GetStatus(DateTimeOffset.Now);
if (status == QrPaymentStatus.Expired)
{
// 4. Platba nebola potvrdená, tlačíme oznámenie.
await qrPaymentService.PrintPaymentNonDeliveryNoticeAsync(transactionId, cancellationToken);
}
else if (status == QrPaymentStatus.Overpaid)
{
Console.WriteLine($"Zákazník preplatil o {payment.OverpaidAmount}.");
}
```
## Časté otázky
**Je QR platba naviazaná na doklad?**
Nie. Je to samostatný proces pred registráciou dokladu a pri vytvorení platby sa údaje dokladu neposielajú. Po
potvrdení platby váš softvér doklad zaregistruje.
**Ako dlho čakať na zaplatenie?**
Zákon dobu neurčuje. Z praxe odporúčame 90 sekúnd. Čas si nastavíte vo svojom softvéri.
**Čo ak zákazník nezaplatí alebo platba nepríde včas?**
Pokladnica vytlačí doklad o nepotvrdení zrealizovanej platby. Zákazník potom môže zaplatiť inak.
**Môže zákazník zaplatiť inú sumu?**
Nemal by. Podľa špecifikácie platobného odkazu banková aplikácia sumu z QR kódu zmeniť nedovolí. Úplne vylúčiť
sa to však nedá: ak niekto QR kód úmyselne upraví, napríklad zmení v ňom sumu, a naskenuje upravený kód, príde
platba s inou sumou.
Váš softvér preto musí byť na to pripravený a vždy vychádzať zo skutočne zaplatenej sumy v
[stave platby](#paymentstatus):
- `partiallyPaid`: zaplatená len časť, platba ešte nie je uhradená. Zvyšok môže zákazník doplatiť ďalším
QR kódom (odkaz na zostávajúcu sumu je v `links`) alebo iným spôsobom.
- `overpaid`: zaplatené viac, rozdiel je v `overpaidAmount`. Váš softvér musí preplatok obsluhe ukázať, aby ho
mohla so zákazníkom vyriešiť, typicky vrátiť.
Doklad zaregistrujte až podľa skutočne prijatej sumy.
## Kam ďalej
- [Príprava a test](https://ekasa.ninedigit.sk/docs/qr-payments/environment-setup): Nastavenie QR platieb v eKase.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Po potvrdení platby zaregistrujte doklad.
- [Chyby QR platieb](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-700-qrpaymenterror): Kódy -700 až -702.
---
# Príprava a test
> Ako zapnúť QR platby v eKase (IBAN, názov účtu, správa pre príjemcu) a vyskúšať prvú platbu v integračnom prostredí.
Dostupné od verzie: Windows 8.0.1, macOS 8.0.1, Linux 9.0.2, Android 8.0.1, .NET knižnica (PPEKK) 8.0.1
Zdroj: https://ekasa.ninedigit.sk/docs/qr-payments/environment-setup
QR platby potrebujú eKasu vo verzii 8.0 alebo novšej, na Linuxe 9.0 alebo novšej. Pred prvou platbou vyplňte
v nastaveniach eKasy údaje o účte, na ktorý podnikateľ prijíma platby, a platbu vyskúšajte.
## Nastavenie
Vo webovom rozhraní služby sú údaje v menu **Systém → Nastavenia**, záložka **QR platby**. Pri .NET knižnici sú
v konfigurácii klienta, časť `QrPayments`.
[Obrázok: Nastavenia QR platieb vo webovom rozhraní eKasy: číslo účtu, názov účtu a správa pre príjemcu]
### Číslo účtu (IBAN)
Účet, na ktorý podnikateľ prijíma okamžité platby. V banke musí byť označený ako **notifikačný účet**, teda účet,
o ktorého prichádzajúcich platbách banka posiela informácie v reálnom čase.
### Názov účtu
Názov, pod ktorým banka účet vedie. Nesmie obsahovať mäkčene ani dĺžne, zo špeciálnych znakov len
`+ ? / - ( ) . , : '`. Podnikateľ ho nájde v internet bankingu, na výpise z účtu alebo v pobočke banky.
### Správa pre príjemcu
Voliteľný text, ktorý sa zobrazí na bankovom výpise. Pomáha priradiť platby v účtovníctve.
## Test platby
Platbu vyskúšate bez vlastného kódu priamo vo webovom rozhraní služby.
1. **Vytvorte platbu**
V menu **QR platba** zadajte sumu a potvrďte **VYTVORIŤ**. Prvá platba môže v integračnom prostredí trvať dlhšie.
2. **Zaplaťte**
Kliknite na **ZAPLATIŤ CEZ PAYME (V2.0)** a zaplaťte podľa prostredia (nižšie).
3. **Skontrolujte stav**
Po prijatí notifikácie sa platba prepne na **Uhradená**. Ďalšiu platbu začnete tlačidlom **HOTOVO**.
[Obrázok: Formulár novej QR platby vo webovom rozhraní eKasy so sumou a kódom pokladnice]
[Obrázok: Prebiehajúca QR platba s tlačidlom ZAPLATIŤ CEZ PAYME]
Ako platbu zaplatíte, závisí od prostredia, v ktorom eKasa beží:
- [Produkčné prostredie](#platba-v-produkčnom-prostredí): Skutočná platba aplikáciou banky.
- [Integračné prostredie](#platba-v-integračnom-prostredí): Platbu odošle testovacia utilita, banka neplatí.
### Platba v produkčnom prostredí
V produkčnom prostredí platíte naozaj. QR kód naskenujte mobilnou aplikáciou svojej banky a platbu potvrďte. Suma
príde na účet nastavený v poli IBAN, na test preto stačí malá suma.
### Platba v integračnom prostredí
V integračnom prostredí skutočná banka neplatí. Platbu odošle naša
[testovacia utilita](https://ekasa.ninedigit.sk/apps/utils/NineDigit.eKasa.QrPayment.win-x64.zip) pre Windows:
1. Po kliknutí na **ZAPLATIŤ CEZ PAYME (V2.0)** skopírujte adresu, ktorú zobrazí prehliadač.
2. Spustite `NineDigit.eKasa.QrPayment.exe` a na výzvu _Please enter payme v2 URL_ adresu vložte.
3. Sumu môžete zmeniť a vyskúšať tak čiastočnú alebo vyššiu platbu. Pôvodnú sumu potvrdíte klávesom `Enter`.
4. Hlásenie _Notification sent successfully._ znamená, že platba bola odoslaná.
[Obrázok: Testovacia utilita QR platby po úspešnom odoslaní notifikácie]
[Obrázok: Uhradená QR platba vo webovom rozhraní eKasy]
## Kam ďalej
- [Kroky platby](https://ekasa.ninedigit.sk/docs/qr-payments#kroky): ID platby, QR kód, stav a oznámenie z vášho softvéru.
- [QR platby](https://ekasa.ninedigit.sk/docs/qr-payments): Priebeh platby a časté otázky.
- [Stavy platby](https://ekasa.ninedigit.sk/docs/qr-payments#paymentstatus): Od vytvorenia po úhradu alebo vypršanie.
---
# Nefiškálny doklad
> Tlač vlastného textu cez eKasu: objednávka, účet pred zaplatením či potvrdenie. Text, hlavička podnikateľa a označenie NEPLATNÝ DOKLAD pri cenách.
Zdroj: https://ekasa.ninedigit.sk/docs/nonfiscal-receipt
Nefiškálny doklad je ľubovoľný text, ktorý eKasa vytlačí mimo evidencie tržieb: objednávka pre kuchyňu, účet pred
zaplatením, ponuka a podobne. Do systému eKasa sa neodosiela, ale ako každý
tlačový výstup sa zapíše do úložiska CHDÚ, ak tlač ide cez neho.
Doklad sa vytlačí na predvolenej tlačiarni. Pri úložisku In-Memory na počítači sa uloží do PDF, rovnako ako ukážky
nižšie. Nefiškálny doklad sa dá vytlačiť aj bez inicializačného balíka, preto sa hodí na prvý test tlačiarne.
## Požiadavka
**HTTP API:**
```http
POST http://localhost:3010/api/v1/printers/print
```
| Vlastnosť | Povinná | Popis |
|---|---|---|
| `text` | áno, ak chýba `cashRegisterCode` | text dokladu, riadky oddelené `\n` |
| `cashRegisterCode` | nie | kód pokladnice: pred text sa vytlačí hlavička podnikateľa |
| `contentFlags` | vždy uveďte | čo text obsahuje: `[]` alebo `["priceInformation"]`, ak obsahuje ceny |
**.NET knižnica:**
```csharp
var result = await client.PrintTextAsync(context, cancellationToken);
```
| Parameter `TextPrintContext` | Povinný | Popis |
|---|---|---|
| `Text` | áno | text dokladu, riadky oddelené `\n` |
| `ContentFlags` | áno | čo text obsahuje: `None` alebo `PriceInformation`, ak obsahuje ceny |
| `CashRegisterCode` | nie | kód pokladnice: pred text sa vytlačí hlavička podnikateľa |
## Text dokladu
Najjednoduchší nefiškálny doklad je samotný text, napríklad objednávka pre kuchyňu:
**HTTP API:**
```json
{
"text": "Objednávka č. 42\nStôl 5\n\n2x Káva\n1x Koláč",
"contentFlags": []
}
```
**.NET knižnica:**
```csharp
var context = new TextPrintContext(
"Objednávka č. 42\nStôl 5\n\n2x Káva\n1x Koláč",
NonfiscalReceiptContentFlags.None);
var result = await client.PrintTextAsync(context, cancellationToken);
```
[Obrázok: Nefiškálny doklad s objednávkou: Objednávka č. 42, Stôl 5, 2x Káva, 1x Koláč]
Text nesmie obsahovať riadiace znaky okrem konca riadku. V .NET to overíte metódou `ReceiptText.IsValid(text)`.
## Hlavička podnikateľa
S kódom pokladnice v `cashRegisterCode` vytlačí eKasa pred text hlavičku s identifikačnými údajmi podnikateľa:
názov, adresu, IČO, DIČ, IČ DPH a kód pokladnice.
**HTTP API:**
```json
{
"text": "Objednávka č. 42\nStôl 5\n\n2x Káva\n1x Koláč",
"cashRegisterCode": "88812345678900001",
"contentFlags": []
}
```
**.NET knižnica:**
```csharp
var context = new TextPrintContext(
"Objednávka č. 42\nStôl 5\n\n2x Káva\n1x Koláč",
NonfiscalReceiptContentFlags.None,
CashRegisterCode: "88812345678900001");
```
[Obrázok: Nefiškálny doklad s hlavičkou podnikateľa nad textom objednávky]
## Údaje o cene
Ak text obsahuje ceny tovaru alebo služieb, napríklad účet pred zaplatením, zákon vyžaduje, aby bol doklad
v každom treťom riadku označený slovami „NEPLATNÝ DOKLAD“
([§ 5 ods. 3 písm. t) zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-t)).
Zákazník tak nezamení takýto doklad s pokladničným dokladom. eKasa označenie doplní sama, keď v `contentFlags` uvediete
`priceInformation`.
**HTTP API:**
```json
{
"text": "Účet pred zaplatením\nStôl 5\n\n2x Káva 8,00\n1x Koláč 3,00\n\nSpolu 11,00 EUR",
"cashRegisterCode": "88812345678900001",
"contentFlags": ["priceInformation"]
}
```
**.NET knižnica:**
```csharp
var context = new TextPrintContext(
"Účet pred zaplatením\nStôl 5\n\n2x Káva 8,00\n1x Koláč 3,00\n\nSpolu 11,00 EUR",
NonfiscalReceiptContentFlags.PriceInformation,
CashRegisterCode: "88812345678900001");
```
[Obrázok: Nefiškálny doklad s cenami, v každom treťom riadku je text NEPLATNÝ DOKLAD]
| `contentFlags` | Kedy | Výsledok |
|---|---|---|
| `[]` | text bez cien: objednávka, poznámka, potvrdenie | text bez označenia |
| `["priceInformation"]` | text s cenami: účet pred zaplatením, ponuka | v každom treťom riadku „NEPLATNÝ DOKLAD“ |
| chýba alebo `null` | | ako pri `priceInformation`, aby označenie nechýbalo omylom |
Vlastnosť `contentFlags` je k dispozícii od verzie 8.
## Formátovanie
eKasa zalamuje text podľa počtu znakov na riadok tlačiarne tak, aby zlom nevznikol v strede slova. Ak skladáte
stĺpce, napríklad názov a cenu, zistite si počet znakov na riadok vopred:
**HTTP API:**
```http
GET http://localhost:3010/api/v1/printers/pos/info
```
**.NET knižnica:**
```csharp
PrinterInfo printerInfo = await client.GetPrinterInfoAsync(PrinterName.Pos, cancellationToken);
```
Nastavenia eKasy na to nestačia. Skutočný počet znakov závisí od šírky papiera vstavanej tlačiarne alebo modelu
zariadenia a pri automatickej voľbe tlačiarne aj od toho, či je pripojená externá tlačiareň. Podrobnosti sú v článku
[Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info).
Text môže obsahovať aj tučné písmo, zarovnanie, QR kódy či čiarové kódy. Vkladajú sa takzvanými tokenmi, pozri
[Tokeny a formátovanie textu](https://ekasa.ninedigit.sk/docs/token-syntax).
## Kam ďalej
- [Tokeny a formátovanie](https://ekasa.ninedigit.sk/docs/token-syntax): Tučné písmo, zarovnanie, QR a čiarové kódy.
- [Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info): Počet znakov na riadok a pripojenie tlačiarne.
- [Poukazy](https://ekasa.ninedigit.sk/docs/receipt-registration/vouchers): Potvrdenie o predaji viacúčelového poukazu s označením NEPLATNÝ DOKLAD.
---
# Informácie o tlačiarni
> Ako zistiť, akou tlačiarňou a s koľkými znakmi na riadok eKasa skutočne tlačí, a prečo sa hodnota môže líšiť od nastavení.
Dostupné od verzie: Windows 9.0.6, macOS 9.0.6, Linux 9.0.6, Android 9.0.10, .NET knižnica (PPEKK) 9.0.6
Zdroj: https://ekasa.ninedigit.sk/docs/printer-info
Pri tlači vlastných textov na doklade, napríklad stĺpcov s názvom a cenou, potrebujete vedieť, koľko znakov sa zmestí
na jeden riadok. Táto hodnota sa môže líšiť od hodnoty v nastaveniach eKasy, nižšie je vysvetlené prečo.
V nastaveniach aplikácie je uchované, **čo si používateľ zvolil**; `info` endpoint indikuje, **čím sa tlač skutočne riadi**.
Preto v prípade, ak vaša aplikácia zasiela voliteľné texty na doklad, alebo realizujete tlač nefiskálneho dokladu a váš tlačový výstup závisí od maximálneho počtu znakov na riadok, odporúčame načítavať informácie o tlačiarni pred kompozíciou vlastných textov. Hodnota z nastavení nemusí stačiť.
## Získanie informácií o tlačiarni
**HTTP API:**
```http
GET {server_address}/api/v1/printers/pos/info
```
**.NET knižnica:**
```csharp
PrinterInfo printerInfo = await client.GetPrinterInfoAsync(PrinterName.Pos, cancellationToken);
```
Príklad odpovede:
```json
{
"connection": "Internal",
"text": {
"layout": "Monospace",
"charactersPerLine": 42
}
}
```
## Prečo sa hodnoty líšia od nastavení
Hodnoty v nastaveniach sa môžu líšiť od skutočne použitých vlastností tlačiarne, ak eKasa beží na zariadení s Androidom so vstavanou tlačiarňou a tlačí sa na nej. Vstavané tlačiarne majú šírku riadku pevne danú, takže eKasa uprednostní túto hodnotu pred nastaveniami aplikácie.
Niektoré príklady vlastných hodnôt podľa modelu zariadenia:
| výrobca | model | počet znakov na riadok |
|---|---|---|
| Sunmi | P3 MIX s 80 mm tlačiarňou | 48 |
| Sunmi | P3 MIX s 58 mm tlačiarňou | 32 |
| Sunmi | D3 mini s 80 mm tlačiarňou | 48 |
| Sunmi | D3 mini s 58 mm tlačiarňou | 32 |
| Sunmi | D3 | 48 |
| Sunmi | V3, P2-EU, P3h Dual | 32 |
| Ingenico | DX4000, DX8000 | 27 alebo 38 podľa písma |
| PAX | A920 Pro | 32 |
Na Sunmi P3h Dual teda môže byť v nastaveniach iná hodnota (predvolených 42 znakov alebo iná), ale doklad sa tlačí na 32 znakov.
Pri zariadeniach Sunmi sa počet znakov na riadok zisťuje priamo od vstavanej tlačiarne podľa šírky papiera: 58 mm tlačiareň (384 bodov) dáva 32 znakov, 80 mm tlačiareň (576 bodov) 48 znakov. Model zariadenia totiž šírku neurčuje spoľahlivo. Napríklad Sunmi P3 MIX aj D3 mini sa predávajú v 58 mm aj 80 mm verzii a obe verzie sa hlásia rovnakým názvom modelu. Hodnota podľa modelu sa použije len vtedy, keď tlačiareň šírku neohlási (napríklad tesne po štarte zariadenia) alebo ohlási šírku, ktorú aplikácia nepozná.
**Pri automatickej voľbe tlačiarne sa hodnoty menia za behu.** Ak je v nastaveniach zapnuté automatické prepínanie medzi internou a externou USB tlačiarňou, tlačí sa na externú tlačiareň vždy, keď je pripojená. Externá tlačiareň môže mať inú šírku riadku, než vstavaná tlačiareň. Pripojenie alebo odpojenie externej tlačiarne teda zmení efektívny počet znakov na riadok. A to aj bez toho, aby boli zmenené nastavenia aplikácie.
## Vlastnosť `connection`
Spôsob pripojenia tlačiarne. Na rozdiel od rovnomenného nastavenia nikdy nenadobúda význam „zvoliť automaticky“, voľba je v tejto chvíli už vykonaná.
| Hodnota | Popis |
|---|---|
| `Internal` | Vstavaná tlačiareň zariadenia, alebo tlačiareň pripojená k dátovému úložisku. |
| `Usb` | Externá tlačiareň pripojená k zariadeniu cez USB. |
| `null` | Tlačiareň, ktorej sa toto delenie netýka, napríklad pri vyhotovení e-dokladu. |
## Vlastnosť `text`
Popis textu, ktorý tlačiareň vyhotoví. Hodnota `null` znamená, že tlačiareň text nevyhotovuje.
### `text.layout`
| Hodnota | Popis |
|---|---|
| `Monospace` | Neproporcionálne písmo: každý znak je rovnako široký, takže riadok sa dá skladať počítaním znakov. |
| `Proportional` | Proporcionálne písmo: šírka znaku závisí od znaku samotného, takže počet znakov na riadok určený nie je a zalomenie textu je na tlačiarni. |
### `text.charactersPerLine`
Počet znakov na riadok, ktorým sa tlač skutočne riadi, teda po zohľadnení šírky papiera vstavanej tlačiarne alebo úprav podľa modelu zariadenia. Uvedený je práve vtedy, keď je `layout` rovné `Monospace`; pri proporcionálnom (`Proportional`) písme je `null`.
Chýbajúci `text` a chýbajúci `charactersPerLine` neznamenajú to isté. Prvé hovorí, že sa nič netlačí; druhé, že sa text tlačí, ale nedá sa skladať počítaním znakov.
## Príklady podľa situácie
Externá USB tlačiareň s neproporcionálnym písmom:
```json
{
"connection": "Usb",
"text": {
"layout": "Monospace",
"charactersPerLine": 42
}
}
```
Vstavaná tlačiareň zariadenia Sunmi P3h Dual, nastavenia hlásia 42, tlačí sa na 32:
```json
{
"connection": "Internal",
"text": {
"layout": "Monospace",
"charactersPerLine": 32
}
}
```
E-doklad, ktorého sa spôsob pripojenia netýka:
```json
{
"connection": null,
"text": {
"layout": "Monospace",
"charactersPerLine": 42
}
}
```
Zariadenie bez podporovanej tlačiarne (nič sa nevyhotovuje):
```json
{
"connection": "Internal",
"text": null
}
```
## Názvy tlačiarní
Názov tlačiarne (`{printerName}` v ceste `/api/v1/printers/{printerName}/info`) je povinný, pretože odpoveď sa pre každú tlačiareň líši.
| Názov | Popis |
|---|---|
| `pos` | Tlačiareň papierových dokladov. |
| `pdf` | Vyhotovenie e-dokladu vo forme PDF súboru. |
| `email` | Vyhotovenie e-dokladu vo forme e-mailovej správy s prílohou. |
Neplatný názov skončí odpoveďou `400`.
---
# Kópia a vyhľadanie dokladu
> Vyhľadanie zaevidovaného dokladu a tlač jeho kópie podľa čísla dokladu, externého alebo interného identifikátora.
Zdroj: https://ekasa.ninedigit.sk/docs/receipt-lookup
Zaevidovaný doklad môžete neskôr **vyhľadať**, napríklad keď sa odpoveď na registráciu stratila alebo potrebujete
identifikátor dokladu pri vrátení tovaru, alebo **vytlačiť jeho kópiu**, keď zákazník pôvodný doklad stratil.
Do systému eKasa sa pri tom nič neodosiela, eKasa doklad načíta z úložiska.
Doklad nájdete jedným z troch identifikátorov. Vždy uveďte aj kód pokladnice (`cashRegisterCode`).
| Identifikátor | Kde ho máte |
|---|---|
| číslo dokladu (rok, mesiac, poradové číslo) | vytlačené na doklade, vo výsledku `request.data.receiptNumber` |
| externý identifikátor `externalId` | váš vlastný, poslali ste ho pri registrácii |
| interný identifikátor `id` | vo výsledku registrácie `request.id` |
Podľa tých istých identifikátorov si stiahnete aj PDF súbor dokladu vyhotoveného ako `pdf`
([Získanie PDF súboru](https://ekasa.ninedigit.sk/docs/receipt-registration/printing#z%C3%ADskanie-pdf-s%C3%BAboru)).
## Vyhľadanie dokladu
Vyhľadanie vráti uložený doklad s rovnakým výsledkom ako pri registrácii (pozri
[Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result)). Ak doklad neexistuje, API vráti `404 Not Found`
a .NET knižnica `null`.
### Vyhľadanie podľa čísla dokladu
Číslo dokladu je identifikované trojicou informácií: rokom, mesiacom a poradovým číslom v mesiaci.
**HTTP API:**
```http
GET {server_address}/api/v1/requests/receipts/receipt?cashRegisterCode=88812345678900001&year=2026&month=4&receiptNumber=83
```
**.NET knižnica:**
```csharp
var filter = new SingleReceiptRegistrationFilter(
cashRegisterCode: "88812345678900001",
receiptNumberId: new ReceiptNumberId(year: 2026, month: 4, number: 83u));
RegisterReceiptResult? receipt = await client.FindReceiptAsync(filter, cancellationToken);
```
### Vyhľadanie podľa externého identifikátora
Externý identifikátor (`externalId`) uvádza nadradená aplikácia pri registrácii dokladu.
**HTTP API:**
```http
GET {server_address}/api/v1/requests/receipts/receipt?cashRegisterCode=88812345678900001&externalId=5cb23300ce3ccc2d38ccdbde
```
**.NET knižnica:**
```csharp
var filter = new SingleReceiptRegistrationFilter(
cashRegisterCode: "88812345678900001",
externalId: new ID("5cb23300ce3ccc2d38ccdbde"));
RegisterReceiptResult? receipt = await client.FindReceiptAsync(filter, cancellationToken);
```
### Vyhľadanie podľa interného identifikátora
Interný identifikátor (`id`) generuje eKasa. Nejde o unikátny identifikátor dokladu (UID) zo systému eKasa.
**HTTP API:**
```http
GET {server_address}/api/v1/requests/receipts/receipt?cashRegisterCode=88812345678900001&id=2d419057-807c-41be-a5d6-aafea8eba13e
```
**.NET knižnica:**
```csharp
var filter = new SingleReceiptRegistrationFilter(
cashRegisterCode: "88812345678900001",
id: new Guid("2d419057-807c-41be-a5d6-aafea8eba13e"));
RegisterReceiptResult? receipt = await client.FindReceiptAsync(filter, cancellationToken);
```
## Tlač kópie dokladu
Kópia sa vytlačí s označením „KÓPIA DOKLADU“ a bez unikátneho identifikátora dokladu, QR kódu a overovacieho kódu
(OKP), ako to vyžaduje
[§ 5 ods. 3 písm. e) zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-e).
Ak doklad neexistuje, tlač skončí chybou [`-104: ReceiptNotFound`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-104-receiptnotfound).
[Obrázok: Pôvodný doklad: Cappuccino a Croissant, suma 5,70 EUR, rekapitulácia DPH, QR kód, UID a OKP]
Originál
[Obrázok: Kópia toho istého dokladu: zvýraznené označenie KÓPIA DOKLADU, bez QR kódu, UID a OKP]
Kópia
### Tlač kópie podľa čísla dokladu
Číslo dokladu je identifikované trojicou informácií: rokom, mesiacom a poradovým číslom v mesiaci.
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&year=2026&month=4&receiptNumber=83
```
**.NET knižnica:**
```csharp
var receiptId = new ReceiptId(cashRegisterCode: "88812345678900001", year: 2026, month: 4, number: 83u);
PrintResult result = await client.PrintReceiptCopyAsync(receiptId, cancellationToken);
```
### Tlač kópie podľa externého identifikátora
Externý identifikátor (`externalId`) uvádza nadradená aplikácia pri registrácii dokladu.
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&externalId=5cb23300ce3ccc2d38ccdbde
```
**.NET knižnica:**
```csharp
PrintResult result = await client.PrintReceiptCopyAsync(
"88812345678900001", new ID("5cb23300ce3ccc2d38ccdbde"), cancellationToken);
```
### Tlač kópie podľa interného identifikátora
Interný identifikátor (`id`) generuje eKasa. Nejde o unikátny identifikátor dokladu (UID) zo systému eKasa.
**HTTP API:**
```http
POST {server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&id=2d419057-807c-41be-a5d6-aafea8eba13e
```
**.NET knižnica:**
```csharp
PrintResult result = await client.PrintReceiptCopyAsync(
"88812345678900001", new Guid("2d419057-807c-41be-a5d6-aafea8eba13e"), cancellationToken);
```
## Kam ďalej
- [Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id): externalId, podľa ktorého doklad nájdete.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Čo obsahuje nájdený doklad.
- [Storno a vrátenie](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections): Oprava dokladu s odkazom na pôvodný.
---
# Peňažná zásuvka
> Kedy eKasa otvára peňažnú zásuvku, ktoré zostavy ju podporujú, ako ju otvoriť pri doklade alebo kedykoľvek a ako nastaviť pin konektora.
Zdroj: https://ekasa.ninedigit.sk/docs/drawer
Peňažnú zásuvku ovláda tlačiareň: zásuvka sa pripája do tlačiarne a eKasa jej pošle príkaz na otvorenie. Váš softvér
so zásuvkou priamo nekomunikuje.
## Ktoré zostavy zásuvku podporujú
| Zostava | Otvorenie pri doklade | Otvorenie kedykoľvek | Pin konektora |
|---|:---:|:---:|:---:|
| CHDU Lite alebo CHDU-SK, tlačiareň pripojená k úložisku | áno | áno | áno |
| Platobný terminál Sunmi | áno | áno | nie |
| Platobný terminál PAX alebo Ingenico | na požiadanie | áno | nie |
| Platobný terminál s externou USB tlačiarňou | áno | áno | áno |
| In-Memory (PDF) | nie | nie | nie |
Na platobných termináloch zásuvku podporuje len časť modelov a príslušenstva. Ak ju terminál nepodporuje, otvorenie
sa nepodarí, ale doklad sa vytlačí.
## Otvorenie pri doklade
Zásuvka sa otvorí pri vytlačení pokladničného dokladu, ak je v nastaveniach eKasy zapnuté
**Otvárať peňažnú zásuvku** (záložka **Tlač**, časť **Papierový doklad**). Predvolene je zapnuté.
Pre konkrétny doklad to nastavenie prebijete voľbou `OpenDrawer` v `print.options`, napríklad aby sa zásuvka otvorila
len pri platbe v hotovosti:
```json
{
"request": { "data": { } },
"print": {
"printerName": "pos",
"options": {
"OpenDrawer": false
}
}
}
```
Na termináloch PAX a Ingenico sa zásuvka pri doklade otvorí len vtedy, keď ju vyžiadate voľbou `"OpenDrawer": true`.
Pri nefiškálnom doklade sa zásuvka neotvára. Podrobnosti o voľbách tlače sú v článku
[Vyhotovenie dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/printing#pos---papierov%C3%BD-doklad).
## Otvorenie kedykoľvek
Zásuvku otvoríte aj bez dokladu, napríklad pri výmene peňazí alebo kontrole hotovosti:
**HTTP API:**
```http
POST http://localhost:3010/api/v1/printers/open_drawer
```
**.NET knižnica:**
```csharp
await client.OpenDrawerAsync(cancellationToken);
```
## Pin konektora
Tlačiarne majú konektor zásuvky s dvoma možnými pinmi. Pri tlačiarni pripojenej k úložisku alebo cez USB zvoľte
pin podľa zásuvky v nastaveniach eKasy, pole **Pin konektora** (**Pin č.2** alebo **Pin č.5**). Predvolený je pin 2.
Ak sa zásuvka neotvára, skúste druhý pin.
## Kam ďalej
- [Vyhotovenie dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration/printing): Voľby tlače vrátane otvorenia zásuvky.
- [Úložisko a zostavy](https://ekasa.ninedigit.sk/docs/storage-and-hardware): Ako zapojiť tlačiareň a úložisko.
- [Stav tlačiarne](https://ekasa.ninedigit.sk/docs/printer-status): Pripravenosť tlačiarne a papier.
---
# Informácie o produkte
> Ako zistiť názov a verziu pokladničného programu, API služby, pripojeného úložiska, SWID a operačný systém, na ktorom eKasa beží.
Zdroj: https://ekasa.ninedigit.sk/docs/product-info
Informácie o produkte vrátia názov a verziu pokladničného programu (PPEKK), API služby a pripojeného chráneného
dátového úložiska, identifikátor SWID a operačný systém. Hodia sa na diagnostiku a na zobrazenie v informáciách
o vašom softvéri.
## Získanie informácií o produkte
**HTTP API:**
```http
GET {server_address}/api/v1/product/info
```
**.NET knižnica:**
```csharp
EKasaProductInfo productInfo = await client.GetProductInfoAsync(cancellationToken);
```
Knižnica vracia rovnaké údaje okrem `api` (verzia API služby).
Príklad odpovede z API služby, ktorá je nasadená na operačnom systéme Android 14:
```json
{
"vendorName": "Nine Digit, s. r. o.",
"swid": "d1e080d619fcbecc06d8e3d34cbc736a7b1dad47",
"api": {
"name": "Portos eKasa API",
"version": "9.0.9"
},
"ppekk": {
"name": "Nine Digit eKasa",
"version": "9.0.9"
},
"chdu": {
"name": "CHDU Lite",
"version": "v1.0 - v1.5"
},
"operatingSystem": {
"platform": "Android",
"architecture": "Arm64",
"description": "Android 14",
"version": "14"
}
}
```
Príklad odpovede z API služby, ktorá je nasadená na 64-bitovom operačnom systéme Windows 10:
```json
{
"vendorName": "Nine Digit, s. r. o.",
"swid": "d1e080d619fcbecc06d8e3d34cbc736a7b1dad47",
"api": {
"name": "Portos eKasa API",
"version": "9.0.9"
},
"ppekk": {
"name": "Nine Digit eKasa",
"version": "9.0.9"
},
"chdu": {
"name": "CHDU Lite",
"version": "v1.0 - v1.5"
},
"operatingSystem": {
"platform": "Windows",
"architecture": "X64",
"description": "Microsoft Windows 10.0.26200",
"version": "Microsoft Windows NT 10.0.26200.0"
}
}
```
Príklad odpovede staršej verzie API služby (9.0.5 a staršej), ktorá vlastnosť `operatingSystem` ešte neuvádza:
```json
{
"vendorName": "Nine Digit, s. r. o.",
"swid": "806c3e0728bb5e0bd096d651d4e65372752d8490",
"api": {
"name": "Portos eKasa API",
"version": "9.0.5"
},
"ppekk": {
"name": "Nine Digit eKasa",
"version": "9.0.3+256a161235f18034e859989e16795c38410607c0"
},
"chdu": {
"name": "CHDU Lite",
"version": "v1.0 - v1.5"
}
}
```
## Vlastnosti odpovede
| Vlastnosť | Popis |
|---|---|
| `vendorName` | Názov výrobcu pokladničného programu. |
| `swid` | Jedinečný identifikátor pokladničného programu (SHA-1). Je odvodený od názvu výrobcu, od názvu a verzie pokladničného programu, od názvu a verzie chráneného dátového úložiska. Týmto identifikátorom sú označené všetky doklady odosielané do systému eKasa Finančnej správy SR. |
| `api` | Názov a verzia API služby. Ide o vrstvu nad certifikovaným pokladničným programom, ktorý sprístupňuje webové API rozhranie. |
| `ppekk` | Názov a verzia vstavaného certifikovaného pokladničného programu. |
| `chdu` | Názov a verzia pripojeného chráneného dátového úložiska. |
| `operatingSystem` | Popis operačného systému, na ktorom API služba beží. |
Verzie `api` a `ppekk` sú navzájom nezávislé a nemusia sa zhodovať. API služba pre Android a API služba pre desktop sa vydávajú samostatne, takže rovnaké číslo verzie v `api` neznamená rovnaké vydanie.
## Vlastnosť `operatingSystem`
*Dostupné od verzie `9.0.6`.*
Popisuje operačný systém zariadenia, na ktorom je API služba nasadená.
### `operatingSystem.platform`
Operačný systém. Ak ide o systém, ktorý API služba nepozná, hodnota nie je uvedená.
| Hodnota | Popis |
|---|---|
| `Windows` | Windows. |
| `Linux` | Linux. |
| `MacOS` | macOS. |
| `Android` | Android. |
| `null` | Systém sa nepodarilo rozpoznať. |
### `operatingSystem.architecture`
Architektúra procesu API služby. Uvádza architektúru **procesu**, nie systému: 32-bitová služba na 64-bitovom systéme uvedie 32-bitovú hodnotu.
Medzi bežné hodnoty patria `X86`, `X64`, `Arm` a `Arm64`.
### `operatingSystem.description`
Ľudsky čitateľný popis systému, určený na zobrazenie obsluhe a na diagnostiku. Napríklad `Microsoft Windows 10.0.26200` alebo `Android 14`.
Formát popisu nie je fixný a môže sa medzi verziami a platformami líšiť.
V prípade ošetrenia správania nadradenej aplikácie odporúčame použiť hodnotu `platform`.
### `operatingSystem.version`
Verzia systému tak, ako ju uvádza sám systém. Na Androide ide o verziu Androidu (napríklad `14`).
V prípade, ak ju systém neposkytne, je uvedená hodnota `null`.
---
# Chybové kódy
> Význam chybových kódov (vlastnosť code) v chybových odpovediach HTTP API eKasy a ich príklady.
Zdroj: https://ekasa.ninedigit.sk/docs/rest-api/error-codes
Chybová odpoveď HTTP API obsahuje okrem stavového kódu HTTP (`status`) aj kód chyby eKasy (`code`, vždy záporné číslo).
Podľa neho chybu spracujte vo vašom softvéri. Formát odpovede popisuje [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api#chybov%C3%A9-odpovede).
## Príklad chybovej odpovede
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-104-receiptnotfound",
"title": "Doklad sa nenašiel",
"status": 403,
"detail": "Dopytu nevyhovuje žiaden záznam.",
"code": -104,
"traceId": "0HNQ3QM5ML2BK:00000001",
"instance": "/api/v1/requests/receipts/print_copy"
}
```
V závislosti od chybového kódu (vlastnosť `code`) sa v chybovej odpovedi môžu nachádzať ďalšie parametre, bližšie popisujúce chybový stav.
Napríklad pole `key` v prípade [-403: StorageDuplicateKey](#-403-storageduplicatekey)
## Kategórie chybových kódov
### Všeobecné (-1XX)
Čas, číslo dokladu, prostredie a dostupnosť služby.
- [-100 GeneralError](#-100-generalerror): Všeobecná chyba
- [-101 ClientLocked](#-101-clientlocked): Klient je uzamknutý
- [-102 InvalidTime](#-102-invalidtime): Neplatný čas
- [-103 InvalidReceiptNumber](#-103-invalidreceiptnumber): Neplatné číslo dokladu
- [-104 ReceiptNotFound](#-104-receiptnotfound): Doklad sa nenašiel
- [-105 InvalidEKasaEnvironment](#-105-invalidekasaenvironment): Nesprávne prostredie eKasa
- [-106 ServiceUnavailable](#-106-serviceunavailable): Služba je dočasne nedostupná
### Identifikačné údaje (-2XX)
Chýbajúce alebo chybné údaje podnikateľa a pokladnice.
- [-200 IdentityError](#-200-identityerror): Chyba identifikačných údajov
- [-201 IdentityNotFound](#-201-identitynotfound): Identita sa nenašla
### Autentifikačné údaje (-3XX)
Certifikát chýba, je neplatný alebo exspiroval.
- [-300 CertificateError](#-300-certificateerror): Chyba certifikátu
- [-301 CertificateNotFound](#-301-certificatenotfound): Certifikát sa nenašiel
- [-302 CertificateExpired](#-302-certificateexpired): Certifikát exspiroval
### Úložisko (-4XX)
Pripojenie úložiska CHDÚ, kapacita a duplicitné záznamy.
- [-400 StorageError](#-400-storageerror): Chyba pri práci s úložiskom
- [-401 StorageInsufficientSpace](#-401-storageinsufficientspace): Úložisko je plné
- [-402 StorageDICMismatch](#-402-storagedicmismatch): Nezhoda DIČ
- [-403 StorageDuplicateKey](#-403-storageduplicatekey): Duplicitný identifikátor
- [-404 StorageNotFound](#-404-storagenotfound): Úložisko sa nenašlo
- [-405 StorageAmbiguity](#-405-storageambiguity): Nejednoznačné úložisko
- [-406 StorageForbiddenEKasaEnvironment](#-406-storageforbiddenekasaenvironment): Nesprávne prostredie úložiska
- [-407 StorageForbiddenDeviceModel](#-407-storageforbiddendevicemodel): Nepodporovaný model zariadenia
### Tlač (-5XX)
Tlačiareň chýba, nie je pripravená alebo tlač zlyhala.
- [-500 PrinterError](#-500-printererror): Tlačiareň ohlásila chybu
- [-501 PrinterNotFound](#-501-printernotfound): Tlačiareň sa nenašla
- [-502 PrintReceiptError](#-502-printreceipterror): Tlač dokladu zlyhala
- [-503 PrinterNotReady](#-503-printernotready): Tlačiareň nie je pripravená
### Licencia (-6XX)
Licencia eKasy je neplatná alebo neaktivovaná.
- [-600 LicenseError](#-600-licenseerror): Chyba licencie
- [-601 LicenseInvalidError](#-601-licenseinvaliderror): Licencia je neplatná
- [-602 LicenseNotActivated](#-602-licensenotactivated): Licencia nie je aktivovaná
- [-603 LicenseVerificationInProgress](#-603-licenseverificationinprogress): Prebieha overovanie licencie
### QR platby (-7XX)
Vytvorenie a vyhľadanie QR platby.
- [-700 QrPaymentError](#-700-qrpaymenterror): Chyba QR platby
- [-701 QrPaymentInitializationError](#-701-qrpaymentinitializationerror): Chyba vytvorenia QR platby
- [-702 QrPaymentNotFoundError](#-702-qrpaymentnotfounderror): QR platba sa nenašla
### Validácia (-900)
Neplatné údaje v požiadavke.
- [-900 ValidationError](#-900-validationerror): Validácia zlyhala
### Prihlásenie (-1000)
Neplatné prihlasovacie údaje alebo bezpečnostný kód Expose.
- [-1000 Unauthenticated](#-1000-unauthenticated): Nie ste prihlásený
## Popis chybových kódov
−1XXVšeobecné
### `-100: GeneralError`
Všeobecná chyba
Bližšie nešpecifikovaná chyba. Konkrétnu príčinu chyby popisujú vlastnosti chybovej odpovede `title` a `detail`.
### `-101: ClientLocked`
Klient je uzamknutý
Počas registrácie dátovej správy, došlo k chybe, ktorá zabraňuje spracovaniu takejto požiadavky v systéme finančnej správy eKasa. EKasa klient nemôže pokračovať v registrácii ďalších dátových správ.
Riešením je odstránenie príčiny, ktorá zabraňuje úspešnému odoslaniu dátovej správy a následné reštartovanie aplikácie. Takéto správanie eKasa klienta je vyžadované finančnou správou.
Príčina, pre ktorú eKasa server odmietol spracovať požiadavku, je spolu s identifikátorom požiadavky uvedená v odpovedi v poli `registration.error`.
Vzor poľa registration:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-101-clientlocked",
"title": "Klient je uzamknutý",
"status": 403,
"detail": "EKasa klient je pozastavený, pretože počas registrácie dátovej správy s identifikátorom '0826db63-a26a-450f-8502-68543b4378be' došlo k chybe -2: Zlé vstupné hodnoty. Pre registráciu ďaľších dátových správ odstráňte príčinu chyby a odošlite neodoslané dátové správy.",
"code": -101,
"traceId": "0HLMCMV49LEUT:00000001",
"registration": {
"request": {
"id": "0826db63-a26a-450f-8502-68543b4378be",
"externalId": "objednavka-2026-000123",
"originUUID": "f7f5e7c8-2598-4dfb-a0f1-d07e6207e53e"
},
"error": {
"message": "Zlé vstupné hodnoty.",
"code": -2
}
},
"instance": "/api/v1/requests/receipts/cash_register"
}
```
Napríklad, pre chybu s kódom `-10`, "Chyba v podpise dátovej správy.", je potrebné nastaviť správne prostredie eKasa klienta (integračné vs. produkčné).
### `-102: InvalidTime`
Neplatný čas
Čas počítača je neplatný. Táto chyba nastane, ak rozdiel medzi lokálnym časom počítača a eKasa serverom prekročí stanovenú hodnotu `serverTimeThresholdSeconds`, nastavenú v konfigurácií klienta.
Chybu možno odstrániť úpravou lokálneho času na počítači: odporúča sa synchronizácia s internetovým časom.
Kým čas nebude opravený, skončí touto chybou každá požiadavka vyžadujúca aktuálny čas, vrátane
registrácie dokladu. Lokálny čas je overený so serverom vždy, keď dôjde k posunu systémových hodín
väčšiemu, ako `timeShiftThresholdMilliseconds`, a priebežne aj bez zaznamenaného posunu.
Úprava parametra `serverTimeThresholdSeconds` nie je odporúčaná.
### `-103: InvalidReceiptNumber`
Neplatné číslo dokladu
Číslo dokladu nie je platné. Chyba nastane v prípade, že systémový číselník dokladu nie je synchronizovaný s úložiskom a dokladu bolo systémom priradené číslo, ktoré sa už na úložisku nachádza. Dôvodom môže byť napr. zmazanie systémového súboru (ten je určený v konfiguračnom poli `dataFilePath`).
### `-104: ReceiptNotFound`
Doklad sa nenašiel
Doklad nebol nájdený. Upravte potrebné parametre v predmetnom dopyte volania a akciu zopakujte.
### `-105: InvalidEKasaEnvironment`
Nesprávne prostredie eKasa
Vykonanie požiadavky vyžaduje e-Kasa prostredie, ktoré je iné, ako aktuálne prednastavené.
Táto chyba môže nastať, ak napr. požiadavka na registráciu dokladu alebo polohy používa ORP kód viazaný na
prostredie iné, ako prednastavené alebo ak sa nahrávané identifikačné údaje viažu na rozdielne e-Kasa prostredie.
### `-106: ServiceUnavailable`
Služba je dočasne nedostupná
Služba sa reštartuje alebo zastavuje a požiadavku nedokončila. Nastane napríklad vtedy, keď sa po zmene nastavení
klient eKasa vytvára znova alebo sa API zastavuje, a požiadavka na registráciu dokladu práve čakala na vybavenie
predchádzajúceho dokladu alebo na dokončenie registrácie s rovnakým `externalId`.
Požiadavka, ktorá čakala na vybavenie predchádzajúceho dokladu, sa do úložiska nezapísala. Ak likvidácia ukončila
registráciu až po zápise do úložiska (napr. počas odosielania na server finančnej správy), požiadavka v úložisku je.
Volajúci ju preto má po chvíli zopakovať s rovnakým `externalId`: ak sa požiadavka do úložiska zapísala alebo sa doklad
medzitým zaevidoval, API vráti výsledok pôvodnej registrácie a nový doklad nevytvorí. Doklad, ktorého registráciu
likvidácia ukončila až po zápise do úložiska, sa však nevytlačil a opakovaná požiadavka ho nevytlačí. Ak likvidácia
preruší až tlač dokladu, API vráti chybu tlače, nie tento kód.
Kód vráti aj zoznam neodoslaných požiadaviek a zistenie nasledujúceho čísla dokladu. Iné požiadavky môžu pri
likvidácii klienta skončiť aj chybou [-100: GeneralError](#-100-generalerror).
Chybový kód je podporovaný od verzie 9.1.0. Staršie verzie v takom prípade vrátili chybu
[-100: GeneralError](#-100-generalerror).
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-106-serviceunavailable",
"title": "Služba je dočasne nedostupná",
"status": 503,
"detail": "Služba sa reštartuje alebo zastavuje. Požiadavku zopakujte neskôr.",
"code": -106,
"traceId": "0HLMCMV49LEUT:00000001"
}
```
−2XXIdentifikačné údaje
### `-200: IdentityError`
Chyba identifikačných údajov
*Rezervované pre budúce použitie.*
### `-201: IdentityNotFound`
Identita sa nenašla
Identita s kódom on-line registračnej pokladne, uvedenom v poli `cashRegisterCode`, nebola nájdená. Táto chyba nastane, ak sa v úložisku nenachádza žiaden záznam identity (identifikačný údaj) s daným kódom on-line registračnej pokladne - `cashRegisterCode`. Nahratie požadovaných identifikačných údajov do úložiska odstráni vzniknutý problém.
−3XXAutentifikačné údaje
### `-300: CertificateError`
Chyba certifikátu
Chyba certifikátu indikuje problém týkajúci sa certifikátu, ktorého presná príčina je uvedená v poli `detail`.
Príčiny:
- nesprávne heslo uvedené v procese nahrávania nového certifikátu do úložiska
- nesprávne alebo poškodené údaje certifikátu
Riešením je opakované nahratie certifikátu so správnym heslom, resp. so správnymi údajmi o certifikáte (pole `data`).
### `-301: CertificateNotFound`
Certifikát sa nenašiel
Nebol nájdený žiaden (platný) certifikát pre identitu, uvedenú v poli `cashRegisterCode`. Táto chyba nastane v prípade, že do úložiska nebol doposiaľ nahratý žiaden certifikát (autentifikačný údaj) alebo existujúci certifikát už vypršal.
V oboch prípadoch sa vyžaduje nahratie nového certifikátu.
### `-302: CertificateExpired`
Certifikát exspiroval
Certifikát, pre kód on-line registračnej pokladne s číslom uvedeným v `cashRegisterCode` chybovej odpovedi, exspiroval. Pred registráciou ďalšieho dokladu alebo polohy je nutné nahrať nový platný certifikát.
−4XXÚložisko
### `-400: StorageError`
Chyba pri práci s úložiskom
Bližšie nešpecifikovaná chyba, ktorá nastala v súvislosti s prácou s chráneným dátovým úložiskom (čítanie resp. zápis na dátové úložisko alebo čítanie resp. zápis do pomocnej tabuľky indexov dátového úložiska).
Najbežnejšie príčiny sú, že dátové úložisko nie je pripojené k systému, alebo je v konfigurácii uvedený nesprávny názov sériového portu.
### `-401: StorageInsufficientSpace`
Úložisko je plné
Zázam sa nepodarilo uložiť s dôvodu nedostatočnej voľnej kapacity dátového média chráneného dátového úložiska.
### `-402: StorageDICMismatch`
Nezhoda DIČ
Do úložiska bol vykonaný pokus o zápis záznamu s DIČ hodnotou inou, ako je DIČ hodnota úložiska.
Úložisko je viazané na jeden podnikateľský subjekt, identifikovaný pomocou DIČ.
Pokus o vloženie identifikačných alebo autentifikačných údajov, prípadne dátovej správy (dokladu alebo polohy), ktorá neprislúcha tomuto podnikateľskému subjektu bude zamietnutý touto chybou.
### `-403: StorageDuplicateKey`
Duplicitný identifikátor
Zápis do úložiska zlyhal, nakoľko pre daný kód on-line registračnej pokladne už v úložisku existuje záznam s rovnakým identifikátorom a tieto záznamy sú po svojej obsahovej stránke rôzne.
Vzor odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-403-storageduplicatekey",
"title": "Duplicitný identifikátor",
"status": 500,
"detail": "Záznam s externým identifikátorom 'objednavka-2026-000123' už existuje.",
"code": -403,
"traceId": "0HLMDGC781MUH:00000002",
"cashRegisterCode": "88812345678900001",
"key": {
"name": "RegistrationRequestExternalId",
"value": "objednavka-2026-000123"
},
"instance": "/api/v1/requests/receipts/cash_register"
}
```
Úložisko si pred zápisom požiadavky overí unikátnosť:
- identifikátora požiadavky (`id`)
- externého identifikátora požiadavky: (`externalId`)
- v prípade registrácie dokladu aj unikátnosť čísla dokladu (`receiptNumber`)
Za účelom bližšej identifikácie indexu, ktorého unikátnosť je porušená, sa v tele odpovede nachádza pole `key`.
Pole `key` obsahuje názov indexu porušujúceho unikátnosť (`name`) a jeho hodnotu (`value`).
Pole `name` nadobúda v závislosti od typu indexu tieto hodnoty:
| Index | Hodnota `key.name` | Riešenie |
| ------------- | ------------------------------------- | -------- |
| Interné id | `RegistrationRequestId` | Pravdepodobnosť duplicitnej hodnoty pre interný identifikátor (`Id`) je extrémne nízka. V prípade výskytu je riešením opakovanie požiadavky. |
| Externé id | `RegistrationRequestExternalId` | V prípade duplicitnej hodnoty pre externý identifikátor (`ExternalId`) je potrebné hľadať príčinu v nadradenej aplikácií. Riešením je zopakovať požiadavku s novou hodnotou externého identifikátora. |
| Číslo dokladu | `ReceiptRegistrationRequestReceiptId` | Zhoda `ReceiptNumber` indikuje nezosynchronizovaný číselník dokladov s úložiskom. V tomto prípade ide o zlyhanie eKasa aplikácie. Odporúča sa aktualizovať eKasa API na najnovšiu dostupnú verziu. |
Konkrétnu príčinu chyby popisujú vlastnosti chybovej odpovede `title` a `detail`.
### `-404: StorageNotFound`
Úložisko sa nenašlo
Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu `StorageModel` alebo `ChduSerialPortName` a zároveň nebolo k zariadeniu pripojené žiadne z kompatibilných dátových úložísk.
### `-405: StorageAmbiguity`
Nejednoznačné úložisko
Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu `StorageModel` alebo `ChduSerialPortName` a zároveň bolo k zariadeniu pripojených viacero kompatibilných dátových úložísk.
### `-406: StorageForbiddenEKasaEnvironment`
Nesprávne prostredie úložiska
Chyba nastane, ak úložisko bolo použité na nepodporované e-Kasa prostredie, napr. `InMemory` úložisko bolo použité na produkčné (`Production`) prostredie.
### `-407: StorageForbiddenDeviceModel`
Nepodporovaný model zariadenia
Táto chyba vznikne v prípade, že úložisko je použité na nepodporovanom modeli zariadenia.
Najčastejšie sa týka úložiska `SwissBit`, ktorého použitie je povolené výhradne na zariadeniach, ktoré absolvovali certifikačné konanie v súvislosti s aplikáciou eKasa na Finančnej správe SR.
Použitie úložiska SwissBit na inom než certifikovanom modeli zariadenia nie je povolené a vedie k vzniku tejto chyby.
Výnimku tvorí režim tzv. technického dema, kedy je aplikácia viazaná výhradne na integračné prostredie systému eKasa za účelom overenia kompatibility zariadenia.
−5XXTlač
### `-500: PrinterError`
Tlačiareň ohlásila chybu
Všeobecná chyba tlače na tlačiarni s názvom uvedeným v poli `printerName`. Presné príčiny zlyhania tlače sú uvedené v poli `detail` chybovej odpovede.
### `-501: PrinterNotFound`
Tlačiareň sa nenašla
Tlačiareň s názvom, uvedeným v premennej `printerName` chybovej odpovedi, nebola nájdená a doklad nemôže byť vytlačený. Riešením je použiť, v každej ďalšiej požiadavke o zaevidovanie dokladu alebo polohy, jeden z platných názvov tlačiarní a to buď `pos`, `pdf` alebo `email`.
### `-502: PrintReceiptError`
Tlač dokladu zlyhala
Tlač dokladu zlyhala. Ak chyba nastala počas požiadavky evidencie dokladu, doklad možno považovať za zaevidovaný eKasa serverom. Neposielajte ho preto na registráciu znova. Zákazníkovi môžete vytlačiť kópiu dokladu, pričom v požiadavke sa uvedie jeden z jeho identifikátorov, uvedený v chybovej odpovedi a to buď `requestExternalId`, ak bol uvedený, alebo `receiptId`. Ak zákazník trvá na origináli, pôvodný doklad [stornujte](https://ekasa.ninedigit.sk/docs/receipt-registration/corrections#storno-dokladu) a zaregistrujte nový.
Príklad chybovej odpovede zlyhanej požiadavky spracovania dokladu:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-502-printreceiptererror",
"title": "Tlač dokladu zlyhala",
"status": 500,
"detail": "Tlač dokladu č. 21 z 6/2026 pokladne 88812345678900001 na tlačiarni 'pos' zlyhala.",
"code": -502,
"traceId": "0HLNDFM9VMUHB:00000001",
"printerName": "pos",
"receiptId": {
"cashRegisterCode": "88812345678900001",
"year": 2026,
"month": 6,
"receiptNumber": 21
},
"requestExternalId": null,
"instance": "/api/v1/requests/receipts/cash_register"
}
```
Následná požiadavka o vytlačenie kópie dokladu môže vyzerať nasledovne:
`{server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&year=2026&month=6&receiptNumber=21`
### `-503: PrinterNotReady`
Tlačiareň nie je pripravená
Tlačiareň s názvom, uvedeným v premennej `printerName` chybovej odpovedi, nie je pripojená a akcia súvisiaca s tlačiarňou nemôže byť dokončená. Riešením je overiť, či je tlačiareň fyzicky pripojená k úložisku a zapnutá.
Niektoré modely chráneného dátového úložiska (napríklad `CHDU-SK`) však umožňujú vykonanie akcie súvisiacej s tlačou aj napriek nepripravenej tlačiarni. Z tohto dôvodu majú niektoré akcie (tlač nefiskálneho dokladu, tlač kópie dokladu, tlač neodoslaných dátových správ, otvorenie peňažnej zásuvky, ...) vo svojich návratových modeloch vlastnosť `printed`.
−6XXLicencia
### `-600: LicenseError`
Chyba licencie
*Pridané od verzie eKasa API 7.0.0.*
Chyba licencie indikuje problém týkajúci sa licencie, ktorého presná príčina je uvedená v poli detail.
### `-601: LicenseInvalidError`
Licencia je neplatná
Licencia je neplatná. Táto chyba nastane, ak licencia pre úložisko nie je platná alebo ak niektoré z používaných
rozšírení nie sú platné.
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-601-licenseinvaliderror",
"title": "Licencia je neplatná",
"status": 500,
"detail": "Licencia pre balík 'ekasa' vo verzii '9.0.7' nie je pre toto úložisko platná.",
"code": -601,
"traceId": "0HLNDIHB0GA61:00000001",
"storage": {
"isValid": true,
"customerWarranty": {
"start": "2025-10-01T00:00:00",
"end": "2026-10-31T23:59:59"
},
"error": {
"message": "Úložisko nie je v záruke",
"code": -104
}
},
"features": [
{
"sku": "ekasa",
"isValid": false,
"version": "9.0.7",
"validity": {
"start": "2025-10-01T00:00:00",
"end": "2026-10-31T23:59:59"
},
"error": {
"message": "Licencia pre balík 'ekasa' vo verzii '9.0.7' nie je pre toto úložisko platná",
"code": -203
}
}
]
}
```
### `-602: LicenseNotActivated`
Licencia nie je aktivovaná
API odmietlo obslúžiť požiadavku, pretože zariadenie nemá aktivovanú licenciu. Aktivácia licencie nastáva pri prvom spustení aplikácie a jej priebeh či inštrukcie možno sledovať na obrazovke zariadenia.
Volajúci by mal používateľa nasmerovať na dokončenie aktivačného procesu v
samotnej aplikácii (QR kód alebo ručné zadanie kódu od technika).
Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-602-licensenotactivated",
"title": "Licencia nie je aktivovaná",
"status": 503,
"detail": "Licencia nie je aktivovaná.",
"code": -602,
"traceId": null
}
```
### `-603: LicenseVerificationInProgress`
Prebieha overovanie licencie
Lokálne API je dočasne nedostupné, pretože práve prebieha štartovacie overovanie
stavu zariadenia voči onboarding backendu. Ide o prechodný stav, ktorý typicky
trvá iba prvé sekundy po spustení aplikácie — kým sa dokončí kontrola licencie.
Volajúci by mal požiadavku po krátkej pauze zopakovať (napr. 3–5 sekúnd).
Po úspešnom overení API automaticky prejde do režimu obsluhy požiadaviek;
pri neúspechu sa stav zmení na `-602 LicenseNotActivated`.
Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-603-licenseverificationinprogress",
"title": "Prebieha overovanie licencie",
"status": 503,
"detail": "Prebieha overovanie licencie.",
"code": -603,
"traceId": null
}
```
−7XXQR platby
### `-700: QrPaymentError`
Chyba QR platby
Nastala chyba súvisiaca so spracovaním QR platby.
Bližšiu príčinu určuje správa v tele odpovede.
### `-701: QrPaymentInitializationError`
Chyba vytvorenia QR platby
Nastala chyba pri vytváraní QR platby.
Medzi možné príčiny patrí:
- Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb
- z dôvodu výpadku sieťového pripojenia na eKasa zariadení
- z dôvodu výpadku služby finančnej správy
- Nadviazanie zabezpečeného sietoťového spojenia bolo zamietnuté službou okamžitých platieb
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-701-qrpaymentinitializationerror",
"title": "Chyba vytvorenia QR platby",
"status": 500,
"detail": "Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb.",
"code": -701,
"traceId": "0HNGIPOQC63UF:00000002",
"instance": "/api/v1/payments/qr"
}
```
### `-702: QrPaymentNotFoundError`
QR platba sa nenašla
QR platba s daným identifikátorom nebola nájdená.
Medzi možné príčiny patrí:
- eKasa aplikácia bola od momentu vytvorenia QR platby reštartovaná
- QR platba exspirovala a po uplynutí časového limitu bola vyradená z evidencie.
HTTP kód odpovede je 404.
Príklad chybovej odpovede:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-702-qrpaymentnotfoundnerror",
"title": "QR platba nebola nájdená",
"status": 404,
"detail": "QR platba s identifikátorom '00000000-0000-0000-0000-000000000000' nebola nájdená.",
"code": -702,
"traceId": null
}
```
−900Validácia
### `-900: ValidationError`
Validácia zlyhala
Validácia zlyhala. Server nemôže spracovať požiadavku, nakoľko obsahuje neplatné dáta. Chybné polia a ich príčiny sú uvedené v poli `errors`.
Príklad chybovej odpovede požiadavky s neplatnými údajmi:
```json
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#900-validationerror",
"title": "Validácia zlyhala",
"status": 400,
"traceId": "0HNQ3QM5ML2AH:00000001",
"code": -900,
"errors": {
"Request.Data.CashRegisterCode": [
"Pole 'Cash Register Code' nemá správny formát."
]
},
"instance": "/api/v1/requests/receipts/cash_register"
}
```