Tokeny a formátovanie textu

Integrujem cez

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

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 (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

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

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

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

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

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

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

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

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

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

Ukážka tokenu pagebreak: dve objednávky oddelené zlomom strany

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.

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

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.

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

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.

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

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.

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.