Vyhotovenie dokladu

Integrujem cez

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:

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:

  1. request: informácie týkajúce sa samotného dokladu
  2. 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:

{
  "request": {
    "data": { /* … údaje dokladu */ }
  },
  "print": {
    "printerName": "pos",
    "options": { /* … prepínače vyhotovenia */ }
  }
}

Funkcia knižnice client.RegisterReceiptAsync()

  1. RegisterCashRegisterReceiptRequest request: informácie týkajúce sa samotného dokladu
  2. 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.
{
  "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:

  1. Doklad zaregistrujte s "printerName": "pdf".
  2. PDF súbor si stiahnite cez API.
  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.
{
  "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 ž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. 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:

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

Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.