Migrácia na verziu 8

Integrujem cez

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.

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čí 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);

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

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

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:

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

Od verzie 8:

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

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

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:

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

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

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

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

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.