# 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).

## <span id="pos" class="anchor"></span><span id="pos---papierový-doklad" class="anchor"></span><code class="heading-tag">pos</code> 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);
```

## <span id="pdf" class="anchor"></span><span id="pdf---elektronický-doklad-vo-forme-pdf-súboru" class="anchor"></span><code class="heading-tag">pdf</code> 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.

## <span id="email" class="anchor"></span><span id="email---elektronický-doklad-vo-forme-e-mailu" class="anchor"></span><code class="heading-tag">email</code> 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`).

## <span id="offline" class="anchor"></span>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<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](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.
