Migrácia na verziu 8

Pri prechode z verzie 7 na verziu 8 je potrebné pri práci s knižnicou adaptovať niektoré spätne nekompatibilné zmeny.

1. Konfigurácia je súčasťou knižnice `NineDigit.eKasa`

Tip

Táto zmena sa týka iba integrácie prostredníctvom DLL knižnice. Integrácia prostredníctvom HTTP REST API nie je dotknutá.

Po aktualizácii knižnice NineDigit.eKasa na verziu 8 a novšiu odinštalujte knižnicu NineDigit.eKasa.Configuration.

2. Určenie obsahu nefiskálneho dokladu

Pri tlači nefiskálneho dokladu je potrebné vlastnosťou ContentFlags indikovať, či text obsahuje informáciu o cene tovaru alebo cene služby. Ak je tento príznak nastavený, na doklade sa zobrazí text „NEPLATNÝ DOKLAD“ v každom treťom riadku, pre splnenie §5 ods. 3 písm. t) zákona o evidencii tržieb.

2.1 Príklady použitia (HTTP REST API)

Príklady API volania POST api/v1/printers/print:

Tlač textu obsahujúceho informáciu o cene tovaru alebo cene služby musí byť sprevádzaná vyplnením vlastnosti contentFlags s uvedenou hodnotou priceInformation.

{
  "text" : "Suma za tovar alebo službu je 12,34 EUR.",
  "cashRegisterCode" : "88812345678900001",
  "contentFlags": [ "priceInformation" ]
}

Pri tlači textu neobsahujúceho informáciu o cene tovaru alebo cene služby je vlastnosť contentFlags nastavená na hodnotu prázdneho zoznamu.

{
  "text" : "Tento nefiskálny doklad neobsahuje informáciu o cene tovaru alebo cene služby.",
  "cashRegisterCode" : "88812345678900001",
  "contentFlags": []
}

V prípade, ak nebude vlastnosť contentFlags uvedená, alebo bude nastavená na hodnotu null, aplikácia vytlači text „NEPLATNÝ DOKLAD“ v každom treťom riadku.

2.2 Príklady použitia (DLL knižnica)

Tlač textu obsahujúceho informáciu o cene tovaru alebo cene služby:

ReceiptText receiptText = new ReceiptText(
    "Suma za tovar alebo službu je 12,34 EUR.");

TextPrintContext context = new TextPrintContext(
    receiptText, NonfiscalReceiptContentFlags.PriceInformation);

this.client.PrintTextAsync(context, CancellationToken.None);

Tlač textu neobsahujúceho informáciu o cene tovaru alebo cene služby:

ReceiptText receiptText = new ReceiptText(
    "Tento nefiskálny doklad neobsahuje informáciu " + 
    "o cene tovaru alebo cene služby.");

TextPrintContext context = new TextPrintContext(
    receiptText, NonfiscalReceiptContentFlags.None);

this.client.PrintTextAsync(context, CancellationToken.None);

3. Úprava kompozície nastavení e-mailového dokladu

Tip

Táto zmena sa týka iba integrácie prostredníctvom DLL knižnice. Integrácia prostredníctvom HTTP REST API nie je dotknutá.

Dátový typ EmailPrintingOptions odteraz v konštruktore prijíma povinný parameter to, reprezentujúci e-mailovú adresu kupujúceho.

Predtým:

EmailPrintingOptions printOptions = new EmailPrintingOptions()
{
    To = "example@example.com",
    ...
}

Od verzie 8:

EmailPrintingOptions printOptions = new EmailPrintingOptions("example@example.com")
{
    ...
}

⚠️ Pozor, volanie PrintingOptions.CreateDefault(PrinterName.Email) skončí výnimkou typu InvalidOperationException.

PrintingOptions.CreateDefault(PrinterName.Email); // InvalidOperationException

4. Zmeny v konfiguračnom súbore

Warning

V prípade návratu z verzie 8 na staršiu verziu nemusí byť súbor settings.json kompatibilný.

V rámci doplnenia automatickej detekcie modelu úložiska, umiestnenia úložiska (sériový port) či eKasa prostredia, sú v konfiguračnom súbore (settings.json) vykonané nasledovné zmeny:

názov	vlastnosť	popis zmeny
Model úložiska	`storage.storageModel`	Povolená je aj hodnota `null` označujúca automatickú detekciu modelu úložiska.
Sériový port úložiska	`storage.serialPortName`	Hodnota bola odstránená. Je nahradená vlastnosťou `storage.location`
Umiestnenie úložiska	`storage.location`	Nahrádza vlastnosť `serialPortName`. Povolená je aj hodnota `null` označujúca automatickú detekciu umiestnenia úložiska.
eKasa prostredie	`eKasaClient.environment`	Povolená je aj hodnota `null` označujúca automatickú detekciu prostredia.

V rámci implementácie QR platieb sa v konfiguračnom súbore nachádza nová sekcia qrPayments.

Príklad:

...
"qrPayments":
{
    "merchant":
    {
        "iban": "SK4811000000002944116480",
        "name": "Merchant Name, s.r.o."
    },
    "paymentTimeoutSeconds": 120,
    "environment": null,
    "recipientMessage": null
}

vlastnosť	dátový typ	popis
`merchant.iban`	`string?`	Číslo účtu obchodníka v tvare IBAN. Predvolená hodnota je `null`.
`merchant.name`	`string?`	Meno obchodníka prijímajúceho platby, pod ktorým je účet obchodníka evidovaný v banke za účelom overenia prijímateľa okamžitej platby. Maximálna dĺžka je 70 znakov. Hodnota nesmie obsahovať mäkčene ani dĺžne. Zo špeciálnych znakov je možné použiť len: `+`, `?`, `/`, `-`, `(`, `)`, `.`, `,`, `:` a `'`. Predvolená hodnota je `null`.
`paymentTimeoutSeconds`	`int`	Časový interval v sekundách, po ktorého uplynutí bude platna označená ako exspirovaná. Predvolená hodnota je 120.
`environment`	`string?`	Prostredie služby QR platieb. Povolené hodnoty: `production` (produkčné prostredie), `integration` (integračné prostredie) alebo `null` pre automatickú detekciu (odporúčané).
`recipientMessage`	`string?`	Prostredie služby QR platieb. Povolené hodnoty: `production` (produkčné prostredie), `integration` (integračné prostredie) alebo `null` pre automatickú detekciu (odporúčané).

V prípade, ak niektorá z vlastností merchant.iban a merchant.name nadobúda hodnotu null, pokus o realizáciu QR platby skončí chybou Údaje obchodníka nie sú nastavené. Overte nastavenia QR platieb..

Migration to Version 8

When upgrading from version 7 to version 8, some backward-incompatible changes must be adapted when working with the library.

1. Configuration Is Part of the `NineDigit.eKasa` Library

Tip

This change applies only to integration via the DLL library. Integration via the HTTP REST API is not affected.

After updating the NineDigit.eKasa library to version 8 or newer, uninstall the NineDigit.eKasa.Configuration library.

2. Defining the Content of a Non-Fiscal Receipt

When printing a non-fiscal receipt, the ContentFlags property must be used to indicate whether the text contains information about the price of goods or services. If this flag is set, the text “INVALID RECEIPT” will be printed on every third line of the receipt in order to comply with §5 section 3 letter t) of the Act on the Registration of Sales.

2.1 Usage Examples (HTTP REST API)

Examples of the POST api/v1/printers/print API call:

Printing text that contains information about the price of goods or services must include the contentFlags property with the value priceInformation.

{
  "text": "The total price for goods or services is 12.34 EUR.",
  "cashRegisterCode": "88812345678900001",
  "contentFlags": ["priceInformation"]
}

When printing text that does not contain information about the price of goods or services, the contentFlags property must be an empty list.

{
  "text": "This non-fiscal receipt does not contain price information for goods or services.",
  "cashRegisterCode": "88812345678900001",
  "contentFlags": []
}

If the contentFlags property is omitted or set to null, the application will print the text “INVALID RECEIPT” on every third line.

2.2 Usage Examples (DLL Library)

Printing text that contains information about the price of goods or services:

ReceiptText receiptText = new ReceiptText(
    "The total price for goods or services is 12.34 EUR.");

TextPrintContext context = new TextPrintContext(
    receiptText, NonfiscalReceiptContentFlags.PriceInformation);

this.client.PrintTextAsync(context, CancellationToken.None);

Printing text that does not contain information about the price of goods or services:

ReceiptText receiptText = new ReceiptText(
    "This non-fiscal receipt does not contain information " +
    "about the price of goods or services.");

TextPrintContext context = new TextPrintContext(
    receiptText, NonfiscalReceiptContentFlags.None);

this.client.PrintTextAsync(context, CancellationToken.None);

3. Changes to the Composition of E-mail Receipt Settings

Tip

This change applies only to integration via the DLL library. Integration via the HTTP REST API is not affected.

The EmailPrintingOptions data type now requires a mandatory to parameter in its constructor, representing the buyer’s e-mail address.

Previously:

EmailPrintingOptions printOptions = new EmailPrintingOptions()
{
    To = "example@example.com",
    ...
}

Since version 8:

EmailPrintingOptions printOptions = new EmailPrintingOptions("example@example.com")
{
    ...
}

⚠️ Warning: Calling PrintingOptions.CreateDefault(PrinterName.Email) will throw an InvalidOperationException.

PrintingOptions.CreateDefault(PrinterName.Email); // InvalidOperationException

4. Changes in the Configuration File

Warning

In the event of a downgrade from version 8 to an earlier version, the settings.json file may not be compatible.

As part of adding automatic detection of the storage model, storage location (serial port), and eKasa environment, the following changes were made to the configuration file (settings.json):

Name	Property	Description
Storage model	`storage.storageModel`	The value `null` is now allowed and indicates automatic detection of the storage model.
Storage serial port	`storage.serialPortName`	This property was removed and replaced by `storage.location`.
Storage location	`storage.location`	Replaces `serialPortName`. The value `null` is allowed and indicates automatic detection of the storage location.
eKasa environment	`eKasaClient.environment`	The value `null` is allowed and indicates automatic environment detection.

As part of the implementation of QR payments, a new qrPayments section has been added to the configuration file.

Example:

"qrPayments": {
    "merchant": {
        "iban": "SK4811000000002944116480",
        "name": "Merchant Name, s.r.o."
    },
    "paymentTimeoutSeconds": 120,
    "environment": null,
    "recipientMessage": null
}

Property	Data type	Description
`merchant.iban`	`string?`	Merchant’s bank account number in IBAN format. Default value is `null`.
`merchant.name`	`string?`	Name of the merchant receiving payments, as registered with the bank for recipient verification of instant payments. Maximum length is 70 characters. The value must not contain diacritics. Allowed special characters are: `+`, `?`, `/`, `-`, `(`, `)`, `.`, `,`, `:` and `'`. Default value is `null`.
`paymentTimeoutSeconds`	`int`	Time interval in seconds after which the payment will be marked as expired. Default value is 120.
`environment`	`string?`	QR payment service environment. Allowed values: `production`, `integration`, or `null` for automatic detection (recommended).
`recipientMessage`	`string?`	Optional message for the payment recipient. Default value is `null`.

If either merchant.iban or merchant.name is set to null, any attempt to perform a QR payment will fail with the error: Merchant data is not configured. Please verify the QR payment settings.

Migrácia na verziu 8

1. Konfigurácia je súčasťou knižnice NineDigit.eKasa

Tip

2. Určenie obsahu nefiskálneho dokladu

2.1 Príklady použitia (HTTP REST API)

2.2 Príklady použitia (DLL knižnica)

3. Úprava kompozície nastavení e-mailového dokladu

Tip

4. Zmeny v konfiguračnom súbore

Warning

1. Konfigurácia je súčasťou knižnice `NineDigit.eKasa`