# Tokeny a formátovanie textu

> Tučné písmo, zarovnanie, čiarové a QR kódy, logo a zlom strany v texte dokladu: stavba tokenu, parametre a podpora podľa tlačiarne.

Zdroj: https://ekasa.ninedigit.sk/docs/token-syntax

Token je značka v texte, ktorú eKasa pri tlači nahradí formátovaným textom, čiarovým alebo QR kódom, logom alebo
zlomom strany. Takto si do hlavičky, päty či nefiškálneho dokladu vložíte napríklad tučný nadpis alebo QR kód
s odkazom na hodnotenie.

## Načo sú tokeny

eKasa tlačí na veľmi rozdielne zariadenia. Externá tlačiareň dostáva príkazy ESC/POS, elektronický doklad vzniká ako
PDF a vstavané tlačiarne platobných terminálov Sunmi, PAX a Ingenico sa ovládajú cez knižnice (SDK) ich výrobcov.
Každé zariadenie zapisuje tučné písmo, čiarový kód či odstrihnutie papiera inak.

Tokeny sú preto jednotný zápis, ktorý nezávisí od zariadenia. Váš softvér napíše token raz a eKasa ho pri tlači
preloží do jazyka konkrétnej tlačiarne: do príkazov ESC/POS, do PDF alebo do volaní SDK terminálu. Nemusíte poznať
príkazy jednotlivých tlačiarní a ten istý text sa vytlačí na všetkých podporovaných zariadeniach.

## Tokeny

- [<code>text</code> Formátovaný text](#formátovaný-text-text): Tučné, podčiarknuté, dvojitá výška, invertovaná tlač a zarovnanie.
- [<code>barcode</code> Čiarový kód](#čiarový-kód-barcode): EAN-8, EAN-13, Code 128, Code 39 a Code 93.
- [<code>qr</code> QR kód](#qr-kód-qr): Odkaz alebo ľubovoľný text ako QR kód.
- [<code>logo</code> Logo](#logo-logo): Logo uložené v pamäti tlačiarne.
- [<code>pagebreak</code> Zlom strany](#zlom-strany-pagebreak): Odstrihnutie papiera alebo nová strana PDF.

## Kde tokeny fungujú

| Text | Vlastnosť | Zlom strany |
|---|---|:---:|
| [nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt) | `text` | áno |
| päta dokladu | `footerText` | áno |
| hlavička dokladu | `headerText` | ignoruje sa |
| popis položky | `description` | ignoruje sa |

Dĺžka hlavičky, päty ani popisu položky nie je obmedzená. Text však nesmie obsahovať riadiace znaky okrem `<SUB>`,
`<RS>`, `<US>`, `<CR>` a `<LF>`. Napríklad tabulátor eKasa odmietne chybou
[`-900 ValidationError`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-900-validationerror).

Ako sa token vytlačí, závisí od tlačiarne:

| Token | Externá tlačiareň (`pos`) | Terminál Sunmi, PAX, Ingenico | PDF a e-mail |
|---|:---:|:---:|:---:|
| `text` | áno | áno | áno, bez dvojitej šírky |
| `barcode` | áno | áno, Ingenico len Code 128 | áno, bez textu pod kódom |
| `qr` | áno | áno | áno |
| `logo` | áno | nie | nie |
| `pagebreak` | áno | áno | áno |

Token, ktorý tlačiareň nepodporuje, sa vynechá a zvyšok textu sa vytlačí.

## Stavba tokenu

Token začína aj končí riadiacim znakom `<SUB>`. Za úvodným `<SUB>` je identifikátor tokenu, za ním parametre.
Každý parameter začína znakom `<RS>`, kľúč a hodnotu oddeľuje `<US>`.

`<SUB>qr<RS>content<US>https://ekasa.ninedigit.sk<RS>alignment<US>center<SUB>`

- **Identifikátor a kľúče** píšte presne ako v tomto článku (`pagebreak`, `hriPosition`). Na veľkosti písmen záleží.
- **Hodnoty** môžete zadať názvom alebo číslom (`center` aj `1`), na veľkosti písmen pri nich nezáleží.
- **Poradie parametrov** je ľubovoľné. Nepovinný parameter môžete vynechať.
- **Neznámy alebo chybný token** sa nevytlačí a text okolo neho sa vytlačí bežne. Ak chýba koncový `<SUB>`,
  zvyšok textu za tokenom sa nevytlačí.

### Riadiace znaky

V zápise tokenov používame pre čitateľnosť značky. V skutočnom texte ich nahraďte znakmi:

| Značka | Znak | V JSON a C# |
|---|---|---|
| `<SUB>` | `0x1A` | `\u001a` |
| `<RS>` | `0x1E` | `\u001e` |
| `<US>` | `0x1F` | `\u001f` |
| `<LF>` | `0x0A`, nový riadok | `\n` |
| `<CR>` | `0x0D`, návrat vozíka | `\r` |

### V HTTP API a v .NET knižnici

**HTTP API:**

V JSON zapíšete riadiace znaky ako `\u001a`, `\u001e` a `\u001f`. Napríklad tučný nadpis a QR kód
v [nefiškálnom doklade](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt):

```http
POST {server_address}/api/v1/printers/print
```

```json
{
  "text": "\u001atext\u001econtent\u001fObjednávka č. 42\u001eformat\u001f1\u001a\n\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk\u001a",
  "contentFlags": []
}
```

**.NET knižnica:**

V knižnici riadiace znaky nepíšete. Pre každý token je trieda, ktorej metóda `ToString()` vráti hotový token:

```csharp
var sb = new StringBuilder();
sb.AppendLine(TextToken.Create("Objednávka č. 42", TextFormats.Bold).ToString());
sb.AppendLine(QrCodeToken.Create("https://ekasa.ninedigit.sk").ToString());

var context = new TextPrintContext(sb.ToString(), NonfiscalReceiptContentFlags.None);
PrintResult result = await client.PrintTextAsync(context, cancellationToken);
```

## Formátovaný text (`text`)

Vytlačí text s formátovaním a zarovnaním. Text je vždy na samostatnom riadku, `<CR><LF>` za ním netreba.

| Parameter | Povinný | Hodnoty | Predvolená |
|---|:---:|---|---|
| `content` | áno | text, môže obsahovať nový riadok `<LF>` | |
| `format` | nie | súčet hodnôt z tabuľky nižšie | `0` |
| `alignment` | nie | `left` (`0`), `center` (`1`), `right` (`2`) | `left` |

Formátovanie skladáte sčítaním hodnôt. Napríklad `3` = tučné (1) + podčiarknuté (2).

| Hodnota | Formát |
|---|---|
| `0` | bez formátovania |
| `1` | tučné |
| `2` | podčiarknuté |
| `4` | dvojitá šírka |
| `8` | dvojitá výška |
| `16` | invertovaná tlač (biely text na čiernom) |

Pri dvojitej šírke sa na riadok zmestí polovica znakov. Počet znakov na riadok zistíte v článku
[Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info), inak sa text môže nečakane zalomiť.

**Zápis:** `<SUB>text<RS>content<US>Na stred<RS>alignment<US>center<SUB>`

**HTTP API:**

```json
"\u001atext\u001econtent\u001fTučné a podčiarknuté\u001eformat\u001f3\u001ealignment\u001fcenter\u001a"
```

**.NET knižnica:**

```csharp
string token = TextToken.Create(
    "Tučné a podčiarknuté",
    TextFormats.Bold | TextFormats.Underlined,
    TextAlignment.Center).ToString();
```

**Príklad**

[Obrázok: Ukážka tokenu text: tučné, podčiarknuté, dvojitá výška, invertovaná tlač, text na stred a vpravo]

```http
POST {server_address}/api/v1/printers/print

{
  "text": "\u001atext\u001econtent\u001fTučné písmo\u001eformat\u001f1\u001a\n\u001atext\u001econtent\u001fPodčiarknuté\u001eformat\u001f2\u001a\n\u001atext\u001econtent\u001fDvojitá výška\u001eformat\u001f8\u001a\n\u001atext\u001econtent\u001f Invertovaná tlač \u001eformat\u001f16\u001a\n\u001atext\u001econtent\u001fNa stred\u001ealignment\u001fcenter\u001a\n\u001atext\u001econtent\u001fVpravo, tučne\u001eformat\u001f1\u001ealignment\u001fright\u001a",
  "contentFlags": []
}
```

## Čiarový kód (`barcode`)

| Parameter | Povinný | Hodnoty | Predvolená |
|---|:---:|---|---|
| `type` | áno | `ean8`, `ean13`, `code128`, `code39`, `code93` | |
| `content` | áno | obsah kódu, pozri pravidlá nižšie | |
| `height` | nie | výška v bodoch tlačiarne, 1 až 255 | `60` (asi 7,5 mm) |
| `hriPosition` | nie | text pod alebo nad kódom: `none` (`0`), `above` (`1`), `below` (`2`), `both` (`3`) | `none` |
| `elementWidth` | nie | šírka čiar od `1` (najužšie) po `6` (najširšie) | `3` |

Obsah kódu:

- **EAN-13:** 12 číslic, kontrolnú číslicu doplní eKasa. Ak zadáte 13 číslic, posledná musí byť platná kontrolná číslica.
- **EAN-8:** 7 číslic, alebo 8 s platnou kontrolnou číslicou.
- **Code 128, Code 39, Code 93:** len znaky ASCII, bez diakritiky.

Neplatný obsah spôsobí, že tlač zlyhá (pozri [Token sa nevytlačil](#token-sa-nevytlačil)).

`hriPosition` a `elementWidth` platia len pre externú tlačiareň (`pos`). Užšie čiary (`1`, `2`) zmestia do kódu viac
znakov, staršie tlačiarne ich však nemusia podporovať. Pri výške `0` sa kód nevytlačí.

**Zápis:** `<SUB>barcode<RS>type<US>ean13<RS>content<US>858123456789<RS>hriPosition<US>below<SUB>`

**HTTP API:**

```json
"\u001abarcode\u001etype\u001fean13\u001econtent\u001f858123456789\u001ehriPosition\u001fbelow\u001a"
```

**.NET knižnica:**

```csharp
string ean = BarcodeToken.Create(
    "858123456789", BarcodeType.EAN13, BarcodeHriPosition.Below).ToString();

string code128 = BarcodeToken.Create(
    "OBJ-2026-0042", BarcodeType.Code128, height: 80).ToString();
```

**Príklad**

[Obrázok: Ukážka tokenu barcode: čiarový kód EAN-13 a Code 128]

```http
POST {server_address}/api/v1/printers/print

{
  "text": "EAN-13:\n\u001abarcode\u001etype\u001fean13\u001econtent\u001f858123456789\u001a\n\nCode 128:\n\u001abarcode\u001etype\u001fcode128\u001econtent\u001fOBJ-2026-0042\u001eheight\u001f80\u001a",
  "contentFlags": []
}
```

## QR kód (`qr`)

| Parameter | Povinný | Hodnoty | Predvolená |
|---|:---:|---|---|
| `content` | áno | obsah QR kódu, napríklad adresa stránky | |
| `alignment` | nie | `left` (`0`), `center` (`1`), `right` (`2`) | `center` |

**Zápis:** `<SUB>qr<RS>content<US>https://ekasa.ninedigit.sk<SUB>`

**HTTP API:**

```json
"\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk\u001a"
```

**.NET knižnica:**

```csharp
string qr = QrCodeToken.Create("https://ekasa.ninedigit.sk").ToString();
```

**Príklad**

[Obrázok: Ukážka tokenu qr: QR kód s odkazom pod textom Hodnoťte nás]

```http
POST {server_address}/api/v1/printers/print

{
  "text": "Hodnoťte nás:\n\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk\u001a",
  "contentFlags": []
}
```

## Logo (`logo`)

Vytlačí logo uložené v pamäti tlačiarne. Funguje len na externej tlačiarni (`pos`), logo do nej nahráte nástrojom
výrobcu tlačiarne.

| Parameter | Povinný | Hodnoty | Predvolená |
|---|:---:|---|---|
| `address` | nie | číslo pozície loga v pamäti tlačiarne | `1` |
| `size` | nie | `normal` (`0`), `doublewidth` (`1`), `doubleheight` (`2`), `quadruple` (`3`, dvojnásobná šírka aj výška) | `normal` |
| `alignment` | nie | `left` (`0`), `center` (`1`), `right` (`2`) | `center` |

**Zápis:** `<SUB>logo<RS>address<US>1<RS>size<US>quadruple<SUB>`

**HTTP API:**

```json
"\u001alogo\u001eaddress\u001f1\u001esize\u001fquadruple\u001a"
```

**.NET knižnica:**

```csharp
string logo = LogoToken.Create(1, LogoSize.Quadruple).ToString();
```

## Zlom strany (`pagebreak`)

Na papierovom doklade tlačiareň papier odstrihne (tlačiareň bez noža len posunie papier), v PDF pokračuje text
na novej strane. Token nemá parametre.

Zlom strany funguje v nefiškálnom doklade a v päte dokladu. V hlavičke a v popise položky sa ignoruje, aby doklad
nerozdelil.

**Zápis:** `<SUB>pagebreak<SUB>`

**HTTP API:**

```json
"Objednávka pre kuchyňu\nStôl 5: 2x Káva\n\u001apagebreak\u001a\nObjednávka pre bar\nStôl 5: 1x Džús"
```

**.NET knižnica:**

```csharp
string pageBreak = new PageBreakToken().ToString();
```

**Príklad**

[Obrázok: Ukážka tokenu pagebreak: dve objednávky oddelené zlomom strany]

```http
POST {server_address}/api/v1/printers/print

{
  "text": "Objednávka pre kuchyňu\nStôl 5: 2x Káva\n\u001apagebreak\u001a\nObjednávka pre bar\nStôl 5: 1x Džús",
  "contentFlags": []
}
```

## Príklady z praxe

Tokeny sa najčastejšie používajú v päte dokladu a v popise položky. Ukážky sú celé požiadavky na
[registráciu dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration), obrázky vznikli presne z nich.

### Poďakovanie a QR kód na hodnotenie v päte

Tučné poďakovanie na stred a pod ním QR kód s odkazom na hodnotenie prevádzky. QR kód v ukážke vedie na tento článok.

[Obrázok: Doklad s poďakovaním a QR kódom na hodnotenie v päte; zvýraznená je päta]

```http
POST {server_address}/api/v1/requests/receipts/cash_register

{
  "print": {
    "printerName": "pdf"
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Cappuccino",
          "quantity": {
            "amount": 1,
            "unit": "ks"
          },
          "unitPrice": 3.2,
          "price": 3.2,
          "vatRate": 23
        },
        {
          "type": "positive",
          "name": "Croissant",
          "quantity": {
            "amount": 1,
            "unit": "ks"
          },
          "unitPrice": 2.5,
          "price": 2.5,
          "vatRate": 19
        }
      ],
      "footerText": "\u001atext\u001econtent\u001fĎakujeme za návštevu!\u001eformat\u001f1\u001ealignment\u001fcenter\u001a\n\u001atext\u001econtent\u001fOhodnoťte nás:\u001ealignment\u001fcenter\u001a\n\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk/docs/token-syntax\u001a",
      "payments": [
        {
          "name": "Karta",
          "amount": 5.7
        }
      ]
    }
  }
}
```

### Sériové číslo výrobku v popise položky

Pri elektronike sa hodí vytlačiť sériové číslo aj ako čiarový kód, napríklad pre reklamáciu.

[Obrázok: Doklad so sériovým číslom Apple AirPods Pro ako textom a čiarovým kódom Code 128 pod položkou; zvýraznený je popis položky]

```http
POST {server_address}/api/v1/requests/receipts/cash_register

{
  "print": {
    "printerName": "pdf"
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Apple AirPods Pro",
          "quantity": {
            "amount": 1,
            "unit": "ks"
          },
          "unitPrice": 279.0,
          "price": 279.0,
          "vatRate": 23,
          "description": "Sériové číslo: H6KX2A1B9Q\n\u001abarcode\u001etype\u001fcode128\u001econtent\u001fH6KX2A1B9Q\u001eheight\u001f50\u001a"
        }
      ],
      "payments": [
        {
          "name": "Karta",
          "amount": 279.0
        }
      ]
    }
  }
}
```

### Čiarový kód objednávky v päte

Číslo objednávky ako čiarový kód, ktorý pri výdaji alebo vrátení tovaru načítate čítačkou.

[Obrázok: Doklad s číslom objednávky a čiarovým kódom Code 128 v päte; zvýraznená je päta]

```http
POST {server_address}/api/v1/requests/receipts/cash_register

{
  "print": {
    "printerName": "pdf"
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Tričko, veľkosť M",
          "quantity": {
            "amount": 1,
            "unit": "ks"
          },
          "unitPrice": 19.9,
          "price": 19.9,
          "vatRate": 23
        }
      ],
      "footerText": "\u001atext\u001econtent\u001fObjednávka OBJ-2026-0042\u001ealignment\u001fcenter\u001a\n\u001abarcode\u001etype\u001fcode128\u001econtent\u001fOBJ-2026-0042\u001eheight\u001f60\u001a",
      "payments": [
        {
          "name": "Karta",
          "amount": 19.9
        }
      ]
    }
  }
}
```

## Token sa nevytlačil

| Čo sa stalo | Príčina |
|---|---|
| token chýba, okolitý text sa vytlačil | identifikátor alebo kľúč s inými veľkými písmenami (`pageBreak` namiesto `pagebreak`), chýba povinný parameter (`content`, `type`) alebo je hodnota neplatná |
| chýba token aj všetok text za ním | chýba koncový `<SUB>` |
| chýba logo | logo funguje len na externej tlačiarni (`pos`), na termináli a v PDF sa vynechá |
| zlom strany v hlavičke alebo v popise položky nič neurobil | v hlavičke a v popise položky sa zlom strany ignoruje |
| čiarový kód chýba | výška `height` je `0` |
| tlač zlyhala s chybou | neplatný obsah čiarového kódu: zlá kontrolná číslica alebo dĺžka EAN, diakritika v Code 128 |

Ak tlač zlyhá pri registrácii dokladu, **doklad je už zaevidovaný**. eKasa vráti chybu
[`-502 PrintReceiptError`](https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-502-printreceipterror) a zákazníkovi treba vytlačiť
[kópiu dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup#tla%C4%8D-k%C3%B3pie-dokladu). Obsah čiarových kódov preto kontrolujte vo svojom softvéri
ešte pred odoslaním dokladu.

## Kam ďalej

- [Nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt): Tlač vlastného textu s tokenmi.
- [Kódovanie a špeciálne znaky](https://ekasa.ninedigit.sk/docs/encoding): Ktoré znaky sa v texte smú použiť.
- [Informácie o tlačiarni](https://ekasa.ninedigit.sk/docs/printer-info): Počet znakov na riadok.
