# Migration to Version 8

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

Source: https://ekasa.ninedigit.sk/en/docs/migration/v8

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

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

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

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

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

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

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

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

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

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

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

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

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:

```csharp
EmailPrintingOptions printOptions = new EmailPrintingOptions()
{
    To = "example@example.com",
    Subject = "Your receipt"
};
```

Since version 8:

```csharp
EmailPrintingOptions printOptions = new EmailPrintingOptions("example@example.com")
{
    Subject = "Your receipt"
};
```

Calling `PrintingOptions.CreateDefault(PrinterName.Email)` will throw an `InvalidOperationException`.

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

## 4. Changes in the Configuration File

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

```json
{
  "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, carried in the QR payment link (at most 140 characters). 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.*

## 5. Changes in `/api/v1/settings`

Sensitive data is masked with a `null` value in every response. Its availability is indicated by a corresponding paired property.

| Sensitive property                    | Sensitive property availability indicator |
|---------------------------------------|-------------------------------------------|
| `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`     |

Example part of the `GET /api/v1/settings` response:

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

In this example, `hasPassword` indicates that a password has been set for the user `edoklad@ninedigit.sk`.

An unset password would be indicated by the value false for the `hasPassword` property.

Setting a new password in the `PUT /api/v1/settings` request will look as follows:

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

The password property contains the new password and `hasPassword` indicates that a new password is being set.

For backward compatibility, the `hasPassword` property may be omitted. In that case, the server detects a password 
change because password does not contain `null` value. However, using these indicator properties is recommended.

If the current password should remain unchanged, the `PUT /api/v1/settings` request will look as follows:

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

For backward compatibility, the `hasPassword` property may be omitted. In that case, the server does not detect 
a password change because password contains `null` value. However, using these indicator properties is recommended.

> Be careful with so-called *round-trip* requests. Performing a `GET api/v1/settings` request and then sending its 
> response back in a `PUT api/v1/settings` request may result in a validation error.
> **Example:** The response contains `"printers.email.credentials.password": null`
> and `"printers.email.credentials.hasPassword": true`. If these values are sent back to the server, it interprets them 
> as an attempt to set a new password that was not provided. Therefore, the response must be processed immediately 
> after retrieval by setting all indicator properties to `false`. If a sensitive value is changed before submission, its
> corresponding indicator should be set to `true`.
