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
text Formátovaný textTučné, podčiarknuté, dvojitá výška, invertovaná tlač a zarovnanie.
barcode Čiarový kódEAN-8, EAN-13, Code 128, Code 39 a Code 93.
qr QR kódOdkaz alebo ľubovoľný text ako QR kód.
logo LogoLogo uložené v pamäti tlačiarne.
pagebreak Zlom stranyOdstrihnutie papiera alebo nová strana PDF.
Kde tokeny fungujú
| Text | Vlastnosť | Zlom strany |
|---|---|---|
| nefiškálny doklad | 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.
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.
- 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 (
centeraj1), 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
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:
POST {server_address}/api/v1/printers/print
{
"text": "\u001atext\u001econtent\u001fObjednávka č. 42\u001eformat\u001f1\u001a\n\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk\u001a",
"contentFlags": []
}
V knižnici riadiace znaky nepíšete. Pre každý token je trieda, ktorej metóda ToString() vráti hotový token:
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, CRLF 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, inak sa text môže nečakane zalomiť.
Zápis: SUBtextRScontentUSNa stredRSalignmentUScenterSUB
"\u001atext\u001econtent\u001fTučné a podčiarknuté\u001eformat\u001f3\u001ealignment\u001fcenter\u001a"
string token = TextToken.Create(
"Tučné a podčiarknuté",
TextFormats.Bold | TextFormats.Underlined,
TextAlignment.Center).ToString();
Príklad

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).
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: SUBbarcodeRStypeUSean13RScontentUS858123456789RShriPositionUSbelowSUB
"\u001abarcode\u001etype\u001fean13\u001econtent\u001f858123456789\u001ehriPosition\u001fbelow\u001a"
string ean = BarcodeToken.Create(
"858123456789", BarcodeType.EAN13, BarcodeHriPosition.Below).ToString();
string code128 = BarcodeToken.Create(
"OBJ-2026-0042", BarcodeType.Code128, height: 80).ToString();
Príklad

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: SUBqrRScontentUShttps://ekasa.ninedigit.skSUB
"\u001aqr\u001econtent\u001fhttps://ekasa.ninedigit.sk\u001a"
string qr = QrCodeToken.Create("https://ekasa.ninedigit.sk").ToString();
Príklad

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: SUBlogoRSaddressUS1RSsizeUSquadrupleSUB
"\u001alogo\u001eaddress\u001f1\u001esize\u001fquadruple\u001a"
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: SUBpagebreakSUB
"Objednávka pre kuchyňu\nStôl 5: 2x Káva\n\u001apagebreak\u001a\nObjednávka pre bar\nStôl 5: 1x Džús"
string pageBreak = new PageBreakToken().ToString();
Príklad

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, 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.

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.

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.

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 a zákazníkovi treba vytlačiť
kópiu dokladu. Obsah čiarových kódov preto kontrolujte vo svojom softvéri
ešte pred odoslaním dokladu.