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.). 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:
posPapierový dokladDoklad vytlačí tlačiareň pokladnice.
pdfPDF súboreKasa vytvorí PDF súbor, zákazníkovi ho doručí váš softvér.
emailE-maileKasa 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) 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á.
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:
request: informácie týkajúce sa samotného dokladuprint: 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:
{
"request": {
"data": { /* … údaje dokladu */ }
},
"print": {
"printerName": "pos",
"options": { /* … prepínače vyhotovenia */ }
}
}
Funkcia knižnice client.RegisterReceiptAsync()
RegisterCashRegisterReceiptRequest request: informácie týkajúce sa samotného dokladuRegisterReceiptPrintContext 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. |
{
"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
}
]
}
}
}
// 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:
- Doklad zaregistrujte s
"printerName": "pdf". - PDF súbor si stiahnite cez API.
- 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. |
{
"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
}
]
}
}
}
// 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. Vždy uveďte aj
kód pokladnice (cashRegisterCode). Doklad sa nájde aj vtedy, keď chýba v tabuľke indexov.
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.
| Doklad určíte | Parametre |
|---|---|
| externým identifikátorom | externalId |
| interným identifikátorom | id |
| číslom dokladu | year, month a receiptNumber |
curl -o doklad.pdf "http://localhost:3010/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&externalId=objednavka-1024"
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.
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 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. |
{
"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
}
]
}
}
}
// 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). 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.
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í:
flowchart TD
A{printerName} -->|pos| P1[Papierový doklad]
A -->|pdf alebo email| B{Systém eKasa<br/>odpovedal?}
B -->|áno, online| E[PDF súbor alebo e-mail]
B -->|nie, offline| P2[Papierový doklad<br/>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 žiadalipdfaleboemail. 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. 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. 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. Ak zákazník trvá na origináli, pôvodný doklad
stornujte a zaregistrujte nový.
Celý priebeh offline režimu popisuje Ako funguje eKasa.
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.
Príklad:
{
"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:
