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

Zdroj: https://ekasa.ninedigit.sk/docs/migration/v8

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`

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](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-t).

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

```json
{
  "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.

```json
{
  "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čí 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:

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

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

PrintResult result = await client.PrintTextAsync(context, cancellationToken);
```

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

```csharp
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);

PrintResult result = await client.PrintTextAsync(context, cancellationToken);
```

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

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:

```csharp
EmailPrintingOptions printOptions = new EmailPrintingOptions()
{
    To = "example@example.com",
    Subject = "Váš doklad"
};
```

Od verzie 8:

```csharp
EmailPrintingOptions printOptions = new EmailPrintingOptions("example@example.com")
{
    Subject = "Váš doklad"
};
```

Volanie `PrintingOptions.CreateDefault(PrinterName.Email)` skončí výnimkou typu `InvalidOperationException`.

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

## 4. Zmeny v konfiguračnom súbore

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

```json
{
  "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 platba 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?`   | Voliteľná správa pre príjemcu platby, prenášaná v platobnom odkaze QR platby (najviac 140 znakov). Predvolená hodnota je `null`. |

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

## 5. Zmeny v `/api/v1/settings`

Citlivé údaje sú v každej odpovedi maskované `null` hodnotou. Ich dostupnosť je indikovaná párovou vlastnosťou.

| citlivý údaj                   | indikácia citlivého údaja |
|--------------------------------|---------------------------|
| `authentication.users[].password` | `authentication.users[].hasPassword`    | 
| `printers.email.credentials.password`          | `printers.email.credentials.hasPassword`  |
| `extensions["Expose"].privateKey`           | `extensions["Expose"].hasPrivateKey`        | 
| `extensions["Expose"].accessToken`                | `extensions["Expose"].hasAccessToken` |

Príklad časti odpovede `GET /api/v1/settings` požiadavky:

```json
{
  "printers": {
    "email": {
      "credentials": {
        "userName": "edoklad@ninedigit.sk",
        "hasPassword": true
      }
    }
  }
}
```

V tomto príklade `hasPassword` indikuje, že pre daného používateľa `edoklad@ninedigit.sk` bolo nastavené heslo.
Nenastavené heslo by bolo indikované hodnotou `false` pre vlastnosť `hasPassword`. 

Nastavenie nového hesla bude v požiadavke `PUT /api/v1/settings` vyzerať nasledovne:

```json
{
  "printers": {
    "email": {
      "credentials": {
        "userName": "edoklad@ninedigit.sk",
        "password": "Heslo123!",
        "hasPassword": true
      }
    }
  }
}
```

Vlastnosť `password` bude obsahovať nové heslo a `hasPassword` indikuje nastavenie nového hesla.
Kvôli spätnej kompatibilite je možné vynechať vlastnosť `hasPassword`. Server v tomto prípade deteguje zmenu hesla,
nakoľko `password` neobsahuje hodnotu `null`. Odporúča sa však používať tieto indikačné vlastnosti.

Ak má byť aktuálne heslo nezmenené, požiadavka `PUT /api/v1/settings` bude vyzerať nasledovne:

```json
{
  "printers": {
    "email": {
      "credentials": {
        "userName": "edoklad@ninedigit.sk",
        "password": null,
        "hasPassword": false
      }
    }
  }
}
```

Kvôli spätnej kompatibilite je možné vynechať vlastnosť `hasPassword`. Server v tomto prípade nedeteguje zmenu hesla,
nakoľko `password` obsahuje hodnotu `null`. Odporúča sa však používať tieto indikačné vlastnosti.

> Dajte si pozor na takzvané *round-trip* požiadavky. Vykonaním `GET api/v1/settings` požiadavky a jej následným odoslaním 
> v požiadavke `PUT api/v1/settings`, môže dôjsť k validačnej chybe.
> **Príklad:** Odpoveď obsahuje `"printers.email.credentials.password": null` 
> a `"printers.email.credentials.hasPassword": true`. Ak budú tieto údaje zaslané na server, ten ich interpretuje, ako 
> snahu o nastavenie nového hesla, ktoré však nebolo uvedené. Odpoveď je preto potrebné bezprostredne po získaní ošetriť
> a to plošným nastavením všetkých indikácií na `false`. Ak pred odoslaním dôjde k zmene citlivého údaja, nastavte
> jeho indikáciu na hodnotu `true`.
