Registrácia dokladu

Úvod

Tip

Vzorové riešenie s použitím knižnice nájdete na našom GitHub projekte.

Čo znamená "Registrácia dokladu"?

Pod pojmom registrácia dokladu sa rozumie proces, kedy nadradená aplikácia (ak ste programátor, tak je to tá, ktorú vyvíjate) odošle do systému PORTOS eKasa informácie o doklade, na ktoré systém PORTOS eKasa zareaguje vykonaním nasledovných krokov:

1. zvaliduje údaje z nadradenej aplikácie (overí matematické náležitosti, prítomnosť povinných parametrov a iné pravidlá alebo podmienky).
2. výpočíta výšku obratov v jednotlivých daňových hladinách.
3. uloží všetky potrebné údaje v dátovom úložisku.
4. odošle údaje v podobe dátovej správy do systému finančnej správy eKasa.
5. vyhotoví doklad v požadovanej podobe: papierový doklad, PDF súbor alebo odošle doklad ako PDF prílohu e-mailom.
6. vráti nadradenej aplikácii všetky relevantné informácie súvisiace s registráciou dokladu.

Ako zaregistrujem doklad?

• HTTP WEB API
• Knižnica

Registrácia dokladu pomocou HTTP WEB API je realizovaná volaním

POST {{server_address}}/api/v1/requests/receipts/{{typ_dokladu}}.

Všetky údaje, ktoré aplikácia PORTOS eKasa pri registrácii dokladu potrebuje prijať od vašej nadradenej aplikácie sú, spoločne s príkladmi, vysvetlené v nasledujúcich častiach.

1. Typy dokladu

Systém PORTOS eKasa rozlišuje nasledovné typy dokladov:

Typ dokladu	Identifikátor typu dokladu
Pokladničný doklad	CashRegister
Neplatný doklad	Invalid
Paragón	Paragon
Faktúra	Invoice
Paragón pri úhrade faktúry	InvoiceParagon
Doklad označený slovom „Vklad“	Deposit
Doklad označený slovom „Výber“	Withdraw

V ďalších častiach dokumentácie si vysvetlíme, pri akých príležitostiach je vhodné vytvárať každý z týchto dokladov a ako má takýto doklad byť vytvorený. V závislosti od typu dokladu sa totiž mení rozsah povinných informácií, ktoré musí nadradená aplikácia pri registrácii dokladu uviesť.

1.1 Pokladničný doklad

Bežný pokladničný doklad, ktorý je vyhotovovaný pri predaji, prípadne pri vráteni tovaru alebo dobropisovaní faktúry.

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Platobná karta",
          "amount": 2.98
        }
      ]
    }
  }
}

1.2 Pokladničný doklad - paragón

Dodatočné zaregistrovanie pokladničného dokladu, ktorý bol vyhotovený vo forme paragónu.

Paragón je pokladničný doklad, ktorý bol vyhotovený v čase poruchy registračnej pokladnice. Po odstránení závady pokladnice je obsluha povinná bez zbytočného odkladu dodatočne zaevidovať tržbu.

Oproti bežnemu typu dokladu je tak potrebné uviesť dve dodatočné vlastnosti:

• issueDate: dátum a čas vyhotovenia paragónu počas poruchy registračnej pokladnice.
• paragonNumber: poradové číslo paragónu

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/paragon

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "issueDate": "2020-02-05T12:30:40.858278+01:00",
      "paragonNumber": 1,
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

1.3 Úhrada faktúry

Úhrada faktúry v hotovosti.

Oproti bežnemu dokladu úhrada faktúr neobsahuje zoznam položiek (items), navyše obsahuje vlastnosti:

• invoiceNumber: číslo faktúry
• amount: celková sumu faktúry s DPH

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/invoice

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "invoiceNumber": "FA-0001",
      "amount": 189.90
    }
  }
}

1.4 Úhrada faktúry - paragón

Hotovostná úhrada faktúry, pričom príjmový pokladničný doklad bol vyhotovený vo forme paragónu.

Oproti bežnemu dokladu úhrada faktúr neobsahuje zoznam položiek (items), navyše obsahuje vlastnosti:

• issueDate: dátum a čas vyhotovenia paragónu počas poruchy registračnej pokladnice.
• paragonNumber: poradové číslo paragónu
• invoiceNumber: číslo faktúry
• amount: celková suma faktúry s DPH

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/invoice_paragon

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "issueDate": "2019-02-15T12:30:40.858278+01:00",
      "invoiceNumber": "FA-0001",
      "paragonNumber": 1,
      "amount": 189.90
    }
  }
}

1.5 Neplatný doklad

Doklad je vhodné vyhotovovať v tzv. tréningovom režime, napríklad pre zaškolenie obsluhy alebo overenie funkčnosti on-line pokladnice.

Vlastnosťami sa nelíši oproti bežnému pokladničnému dokladu. Papierový doklad však v každom treťom riadku obsahuje slová "Neplatný doklad", aby nedošlo k zámene s platným (ostrým) dokladom.

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/invalid

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

1.6 Vklad

Doklad, ktorý sa vystavuje pri vklade hotovosti do on-line pokladnice, ktorá nebola prijatá na základe vyhotoveného dokladu.

Vklad je nutné zadávať do systému v momente, kedy obsluha vkladá do peňažnej zásuvky (alebo peňaženky) hotovosť, ktorá nie je tržbou - napríklad doplnenie hotovosti určenej na rozmieňanie.

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/deposit

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "amount": 10.00
    }
  }
}

1.7 Výber

Doklad, ktorý sa vystavuje pri výbere hotovosti z on-line pokladnice.

Výber je nutné zadávať do systému v momente, kedy obsluha vyberá z peňažnej zásuvky (alebo peňaženky) hotovosť - napríklad pre účely vyplatenia dodaného tovaru, alebo po ukončení predaja (napr. po uzávierke systému).

Tip

Znamienko sumy výberu nie je finančnou správou usmernené. Doklad typu výber je tak možné zaregistrovať s kladným aj záporným znamienkom. Doklady typu výber však odporúčame evidovať so záporným znamienkom, nakoľko pri prípadnom exporte údajov z portálu finančnej správy sa v tabuľkovom editore jednoduchšie spočítavajú celkové obraty.

Warning

Nakoľko systém finančnej správý eKasa pri registrácii dokladu nerozlišuje platidlá, je potrebné pri výbere uvádzať celkovú prijatu tržbu v hotovosti, ako aj sumu prijatú prostredníctvom platobného terminálu.

• HTTP WEB API
• Knižnica

URL: POST {{server_address}}/api/v1/requests/receipts/withdraw

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "amount": -10.00
    }
  }
}

2. Items - Položky dokladu

Vlastnosť dokladu items reprezentuje zoznam položiek dokladu.

Uvádzať položky dokladu je možné iba pri niektorých typoch dokladov. Viac v tabuľke nižšie.

Typ dokladu	Identifikátor typu dokladu	Doklad obsahuje položky
Pokladničný doklad	CashRegister	Áno
Neplatný doklad	Invalid	Áno
Paragón	Paragon	Áno
Faktúra	Invoice	Nie
Paragón pri úhrade faktúry	InvoiceParagon	Nie
Doklad označený slovom „Vklad“	Deposit	Nie
Doklad označený slovom „Výber“	Withdraw	Nie

Každá položka dokladu sa skladá z nasledujúcich (povinných aj nepovinných) vlastností:

2.1 Type - Typ položky

Povinný parameter.

Typ položky nadobúda jeden z nasledovných typov položiek dokladu:

Identifikátor	Názov	Typ položky	Popis
positive	Kladná položka	Kladná	Predaj tovaru alebo poskytnutie služby
returnedContainer	Vrátené obaly	Záporná	Vykúpené zálohované obaly.
returned	Vrátená	Záporná	Zrušenie evidovanej položky po jej vystavení na pokladničnom doklade pri vrátení tovaru alebo služby. Napríklad pri reklamácii.
correction	Opravná	Kladná alebo záporná	Negácia položky už zaevidovaného dokladu v systéme e-kasa v prípade jej opravy. Napríklad pri omyle obsluhy.
discount	Zľava	Záporná	Poskytnutá zľava
advance	Odpočítaná záloha	Záporná	Suma prijatého preddavku uvedená na doklade vystavenom v čase úhrady doplatku ceny za predaný tovar alebo poskytnutú službu. Používa sa, ak bola za tovar už v minulosti obdržaná záloha.
voucher	Výmena poukazu	Záporná	Suma jednoúčelového poukazu pri jeho výmene za tovar alebo poskytnutú službu. Používa sa pri samotnom uplatnení vopred zakúpeného poukazu.

2.2 Name - Označenie tovaru alebo služby

Povinný parameter.

Označenie tovaru alebo sužby je neprázdny textový reťazec maximálnou dĺžkou 255 znakov.

Niektoré symboly (najmä netlačiteľné) sú však sytémom eKasa zakázané. Viac v článku Kódovanie a špeciálne znaky.

2.3 Price - Celková cena tovaru alebo služby

Povinný parameter.

Celková cena tovaru alebo služby v rozsahu -10000000 až 10000000, s presnosťou na dve desatinné miesta.

Celková cena musí byť rovná súčinu jednotkovej ceny a množstva, teda: unitPrice * quantity = price

2.4 UnitPrice - Jednotková cena tovaru alebo služby

Povinný parameter.

Jednotková cena tovaru alebo služby v EUR v rozsahu -10000000 až 10000000 s presnosťou na šesť desatinných miest.

Položka kladného typu, musí mať kladnú jednotkovú cenu. Položka záporného typu musí mať zápornú jednotkovú cenu. Položka opravného typu môže nadobúdať kladné aj záporné hodnoty.

Typ položky	Typy položiek	Povolený rozsah hodnôt
Kladná	positive	Kladné hodnoty: 0 až 10000000
Záporná	returnedContainer, returned, discount, advance a voucher	Záporné hodnoty: -10000000 až 0
-	correction	Plný rozsah: -10000000 až 10000000

2.5 Quantity - Množstvo tovaru alebo rozsah služby

Povinný parameter.

Obsahuje dve polia: amount a unit.

Názov	Povinné pole	Popis
amount	Áno	Hodnota v rozsahu 0 až 10000000 s presnosťou na štyri desatinné miesta.
unit	Nie	Nepovinná množstevná jednotka na 1 až 3 znakov. Ak nie je uvedená, predvolená hodnota je x.

2.6 ReferenceReceiptId - Číslo dokladu

Ide o povinný parameter iba v prípade, ak sa jedná o položku typu correction alebo returned.

V opačnom prípade ide o nepovinný parameter, ktorý musí mať hodnotu null (teda nesmie byť uvedený).

V prípade, ak pôvodný doklad obsahuje unikátny identifikátor dokladu (bol zaregistrovaný v online režime), ako referenčné číslo dokladu sa uvedie tento identifikátor (pole response.data.id).

V prípade, ak pôvodný doklad neobsahuje unikátny identifikátor dokladu (bol zaregistrovaný v offline režime), ako referenčné číslo dokladu sa uvedie OKP (pole request.data.okp).

V prípade pôvodného dokladu vyhotoveného elektronickou registračnou pokladnicou (ERP - teda pokladnicou, ktorá bola používaná pred uvedením súčasnej eKasa legislatívy) ako referenčné číslo dokladu je uvedené poradové číslo pokladničného dokladu.

2.7 VatRate - Sadzba dane z pridanej hodnoty

Povinný parameter.

Sadzba dane s presnosťou na 2 desatinné miesta.

Musí nadobúdať jednu z hodnôt:

• 20
• 10
• 0

2.8 SpecialRegulation - Dôvod priradenia sadzby dane s hodnotou 0

Príznak, ktorý bližšie špecifikuje „dôvod“ priradenia dane s hodnotou 0, ak takáto bola položke priradená.

Ide o nepovinný atribút, ktorý je nepovinný aj pre položky s 0% sadzbou dane.

Hodnota musí byť uvedená iba pre tie položky s nulovou sadzbou dane, ktoré reprezentujú niektorú z nižšie uvedených možností:

Identifikátor	Popis
VATReverseCharge	Prenesenie daňovej povinnosti
VATExemptionGood	Oslobodenie položky od dane
TravelAgency	Osobitná úprava uplatňovania dane pri cestovných kanceláriách
UsedGood	Osobitná úprava uplatňovania dane pri použitom tovare
Artwork	Osobitná úprava uplatňovania dane pri umeleckých dielach
CollectiblesAndAntiques	Osobitná úprava uplatňovania dane pri zberateľských predmetoch a starožitnostiach.

2.9 Seller - Predávajúci

Nepovinný parameter.

Uvádza sa iba v prípade, ak predávajúci, v ktorého mene bol predaný tovar alebo poskytnutá služba je iný, ako podnikateľský subjekt priradený k on-line registračnej pokladnici.

Obsahuje dve polia: id a type.

Názov	Povinné pole	Popis
id	Áno	Identifikátor predávajúceho, v ktorého mene bol predaný tovar alebo poskytnutá služba.
type	Áno	Typ identifikátora predávajúceho, v ktorého mene bol predaný tovar alebo poskytnutá služba. Povolené hodnoty sú v tabuľke nižšie.

Povolené hodnoty vlastnosti type:

Hodnota type	Popis	Formát hodnoty id
DIC	DIČ	^[0-9]{8,10}$ - 8 až 10 číselných znakov.
ICDPH	IČ DPH	^SK[0-9]{8,10}$ - písmena SK následované 8 až 10 číselnými znakmi.

2.10 VoucherNumber - Číslo jednoúčelového poukazu

Číslo jednoúčelového poukazu pri jeho výmene za tovar alebo poskytnutú službu.

Hodnota môže byť uvedená iba pre položky s typom voucher a musí obsahovať textový reťazec s dĺžkou 1 až 50 znakov.

Pre položky iného typu musí byť hodnota rovná null.

2.11 Description - Dodatočný popis položky

Nepovinný parameter.

Nepovinný dodatočný popis položky dokladu, vyobrazený na doklade. Slúži pre umiestnenie informácie o dátume spotreby, sériovom čísle výrobku a podobne. Tlačí sa hneď za názvom produktu a informáciami o množstve a cenách.

Tento textový reťazec nie je odosielaný do finančnú správu, systému eKasa.

Tento parameter podporuje použitie tzv. token-ov pre formátovanie, tlač QR kódov a čiarových kódov. Viac nájdete v článku Tokeny a formátovanie textu.

3. Payments - Zoznam platieb dokladu

Kolekcia payments reprezentuje platby dokladu. Ide o nepovinné pole dokladu, ktoré nadradená aplikácia nemusí vypĺňať - na servery finančnej správy nie sú odoslané. V prípade, ak ale nadradená aplikácia platby uvedie, je potrebné, aby sa ich celková suma rovnala, alebo prevyšovala celkovú sumu dokladu, ktorá je daná súčtom položiek dokladu (items).

Počet platieb nachádzajúcich sa v zozname platieb dokladu je limitovaný na 50.

Každá platba dokladu pozostáva z dvojice vlastností amount a name.

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 10.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 19.90,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 20.00
        },
        {
          "name": "Hotovosť",
          "amount": -0.10
        }
      ]
    }
  }
}

3.1 Amount - Peňažný obnos platby

Peňažný obnos platby s presnosťou na 2 desatinné miesta.

3.2 Name - Názov platidla

Názov (slovný popis) platidla s dĺžkou v rozmedzí 1 až 255 znakov.

4. Customer - Informácia o kupujúcom

Warning

V zmysle rozhodnutia Ústavného súdu SR č. 492/2021 Z. z., Nález Ústavného súdu Slovenskej republiky č. k. PL. ÚS 25/2019-117 z 10. novembra 2021 vo veci vysloveniu nesúladu ustanovenia § 8a ods. 1 zákona č. 289/2008 Z. z. o používaní elektronickej registračnej pokladnice a o zmene a doplnení zákona Slovenskej národnej rady č. 511/1992 Zb. o správe daní a poplatkov a o zmenách v sústave územných finančných orgánov v znení neskorších predpisov v časti „unikátny identifikátor kupujúceho, ak je predložený kupujúcim pred zaevidovaním prijatej tržby“ s čl. 16 ods. 1, čl. 19 ods. 2 a 3 Ústavy Slovenskej republiky (https://www.slov-lex.sk/pravne-predpisy/SK/ZZ/2021/492/vyhlasene_znenie.html), bola zrušená existencia unikátneho identifikátora kupujúceho.

K dokladu (okrem neplatného dokladu - teda dokladu s typom Invalid) je možné uviesť aj informácie o kupujúcom.

Informácia o kupujúcom je reprezentovaná dvoma vlastnosťami:

1. id: identifikátor
2. typ: typ identifikátora kupujúceho.

Obsahuje dve polia: id a type.

Názov	Povinné pole	Popis
id	Áno	Identifikátor kupjúceho.
type	Áno	Typ identifikátora kupjúceho. Povolené hodnoty sú v tabuľke nižšie.

Povolené hodnoty vlastnosti type:

Hodnota type	Popis	Formát hodnoty id
DIC	DIČ	^[0-9]{10}$ - 10 číselných znakov.
ICDPH	IČ DPH	^SK[0-9]{8,10}$ - písmena SK následované 8 až 10 číselnými znakmi.
ICO	IČO	^[0-9]{6}$ alebo ^(?:[0-9]{8}\|[0-9]{12})$ - 6, 8 alebo 12 číselných znakov. V prípade skráteného 6-miestneho formátu budú automaticky doplnené dve nuly pre docielenie 8-miestneho formátu.
Other	Iný typ identifikátora kupujúceho

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "customer": {
        "id": "2004567890",
        "type": "DIC"
      },
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 20.00
        }
      ]
    }
  }
}

5. Určenie spôsobu vyhotovenia dokladu

Nadradená aplikácia má pri registrácii dokladu možnosť uviesť spôsob, akým bude doklad vyhotovený.

Určenie spôsobu vyhotovenia však nie je zákonom dovolené pri všetkých typoch dokladov, túto skutočnosť popisuje tabuľka nižšie.

Typ dokladu	Identifikátor typu dokladu	možnosť určiť spôsob vyhotovenia
Pokladničný doklad	CashRegister	Áno
Neplatný doklad	Invalid	Áno
Paragón	Paragon	Nie
Faktúra	Invoice	Áno
Paragón pri úhrade faktúry	InvoiceParagon	Nie
Doklad označený slovom „Vklad“	Deposit	Nie
Doklad označený slovom „Výber“	Withdraw	Nie

Spôsob vyhotovenia je možné úrčiť pomocou vlastnosti print.printerName.

Podporované sú celkom tri možnosti:

1. pos - papierový doklad
2. pdf - elektronický doklad - PDF súbor
3. email - elektronický doklad - email s PDF súborom v prílohe

Ak nie je objekt print špecifikovaný, predvoleným spôsobom vyhotovenia dokladu je papierový doklad (pos).

Warning

Ak je doklad zaevidovaný v offline režime, v zmysle pokynov finančnej správy musí eKasa klient (knižnica PORTOS eKasa) vyhotoviť doklad v papierovej podobe. A to bez ohladu na to, či bolo nadradenou aplikáciou indikované vyhotovenie dokladu elektronickou formou.

• HTTP WEB API
• Knižnica

Kontext požiadavky evidencie pokladničného dokladu, zasielaný do HTTP WEB API nadradenou aplikáciou, obsahuje dve vlastnosti:

1. request: informácie týkajúce sa samotného dokladu
2. print: informácie týkajúce sa spôsobu vyhotovenia dokladu

Vlastnosť print umožnuje špecifikovať spôsob vyhotovenia dokladu podľa vlastností:

• printerName: určuje typ vyhotovenia dokladu.
• options: určuje povinné aj voliteľné prepínače ovplyvňujúce vyhotovenie dokladu, formou dvojíc kľúč - hodnota (hodnota je vždy textovým reťazcom).

Príklad:

"request": {
  "data": { ... } // informácie o doklade
},
"print": { // nepovinný objekt upresňujúci spôsob vyhotovenia dokladu
  "printerName": "pos", // spôsob vyhotovenia dokladu
  "options": { ... } // dodatočné nastavenia
}

5.1 pos - Papierový doklad

Predvolený spôsob vyhotovenia dokladu.

Pre vyhotovenie dokladu vo forme papierového účtu je potrebné zašpecifikovať v poli printerName hodnotu pos.

V objekte options je možné uviesť nasledovné hodnoty:

Názov	Povinné pole	Popis
OpenDrawer	Nie	Umožňuje určiť, či sa pre tento konkrétny doklad otvorí (hodnota true), prípadne neotvorí (hodnota false) peňažná zásuvka. Toto nastavenie umožňuje nadradenej aplikácii variabilne určovať, pri ktorých typoch dokladov, prípadne pri ktorých platidlách je vhodné otvárať peňažnú zásuvku. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie.
PrintLogo	Nie	Umožňuje určiť, či sa pre tento doklad vytlačí (hodnota true), prípadne nevytlačí (hodnota false) grafické logo. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie.
LogoMemoryAddress	Nie	Umožňuje určiť, aké logo sa pre tento doklad vytlačí. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácií aplikácie.

• HTTP WEB API
• Knižnica

{
  "request": {
    "print": {
      "printerName": "pos",
      "options": {
        "OpenDrawer": false,
        "PrintLogo": true,
        "LogoMemoryAddress": 1
      }
    },
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 20.00
        }
      ]
    }
  }
}

5.2 pdf - Elektronický doklad vo forme PDF súboru

Pre vyhotovenie dokladu vo forme PDF súboru je potrebné zašpecifikovať v poli printerName hodnotu pdf. Tento spôsob vyhotovenia neposkytuje žiadne dodatočné nastavenia v poli options.

PDF súbory aplikácia vytvára na lokálnom disku počitača, na ktorom je PORTOS nainštalovaný. Cesta k adresáru, kde PDF súbory vznikajú, je možné upraviť v nastaveniach aplikácie, určená je konkrétne v poli printers.pdf.outputDirectory.

Vlastnosť v nastaveniach môže mať cestu vyjadrenú:

• absolútne
• relatívne - vtedy sa odvíja od pracovného adresára, ktorý je štandardne C:/ProgramData/NineDigit/Portos.eKasa/.

Predvolená hodnota v nastaveniach je nastavená na receipts. Nakoľko ide o relatívne určenú cestu, cieľový priečinok je odvodený od pracovného adresára aplikácie a výsledná cesta je C:/ProgramData/NineDigit/Portos.eKasa/receipts/.

Názov PDF súboru je určený podľa formátu {orp_code}_{yyyyMM}_{cislo_dokladu}.pdf, kde:

• orp_code: číslo online registračnej pokladnice
• yyyy: rok vytvorenia dokladu
• MM: mesiac vytvorenia dokladu
• cislo_dokladu: podarové číslo dokladu (unikátne v rámci kalendárneho mesiaca)

Príklad cesty k súboru: C:/ProgramData/NineDigit/Portos.eKasa/receipts/88812345678900001_202012_000123.pdf

Tip

Pre zabránenie hromadenia PDF súborov je od verzie 6.4 v konfigurácii aplikácie možné uviesť časový interval (v dňoch), po ktorých bude súbor autamticky odstránený.

• HTTP WEB API
• Knižnica

{
  "request": {
    "print": {
      "printerName": "pdf"
    },
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 20.00
        }
      ]
    }
  }
}

5.2.1 Získanie PDF súboru

Od verzie 6.2 je možné získať obsah PDF súboru.

Táto funkcionalita nezávisí od kompletnosti indexovacej tabuľky, požadovaný doklad dokáže vyhľadať aj bez prítomnosti záznamu index tabuľky.

• HTTP WEB API
• Knižnica

Vyvolaním požiadavky GET {{server_address}}/api/v1/printers/pdf/receipt je vrátený obsah PDF súboru. V prípade, ak nie je nájdený doklad alebo súbor patriaci k tomuto dokladu, vrátená je odpoveď s HTTP stavom 404.

Doklad je možné zašpecifikovať:

• použitím externého identifikátora, ktorý bol uvedený pri registrácii (parameter externalId). Napríklad: GET {{server_address}}/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&externalId=this-is-generated-by-your-app
• použitím unikátneho ID dokladu, ktorý prideľuje aplikácia Portos eKasa (parameter id). Napríklad: GET {{server_address}}/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&id=unique-id-generated-by-portos-ekasa
• uvedením roku, mesiacu a poradového čísla dokladu v mesiaci. Napríklad: GET {{server_address}}/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&year=2023&month=1&receiptNumber=1

5.3 email - Elektronický doklad vo forme e-mailu

Pre vyhotovenie dokladu vo forme emailu je potrebné zašpecifikovať v poli printerName hodnotu email.

V objekte options je možné uviesť nasledovné hodnoty:

Názov	Povinné pole	Popis
To	Áno	E-mailová adresa adresáta (e-mail, na ktorý má byť doklad odoslaný)
Subject	Nie	Umožňuje určiť predmet e-mailu, ktorý sa použije pre tento konkrétny doklad. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácii aplikácie (printers.email.subject).
Body	Nie	Umožňuje určiť telo e-mailu, ktorý sa použije pre tento konkrétny doklad. Ak je toto nastavenie uvedené, získava prioritu nad nastavením uvedeným v konfigurácii aplikácie (printers.email.body).
RecipientDisplayName	Nie	Umožňuje určiť zobrazovacie meno adresáta e-mailu.

Tip

Možnosť uvedenia viacerých adresátov emailu (napríklad prostredníctvom tzv. carbon copy CC) nie je v súlade s legislatívou, nakoľko zákon nepozná viac ako jeden originál pokladničného dokladu. Každý elektronický doklad je preto možné poslať iba na jednu emailovú adresu.

• HTTP WEB API
• Knižnica

{
  "request": {
    "print": {
      "printerName": "email",
      "options" : {
        "To" : "john.doe@example.com", // required
        "Subject" : "Váš e-doklad!", // optional
        "Body" : "Ďakujeme za nákup.", // optional
        "RecipientDisplayName": "Mr. John Doe" // optional
      }
    },
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 20.00
        }
      ]
    }
  }
}

Správanie systému po zlyhanom odoslaní e-mailu

Ak sa doklad podarí úspešne zaregistrovať na finančnej správe a uložiť všetky potrebné údaje do úložiska a zlyhá až samotné odoslanie e-mailu obsahujúci doklad, túto skutočnosť indikuje aplikácia vrátením:

• HTTP WEB API
• Knižnica

chyby z rozsahu -5XX teda kategória označená ako "Chyby tlače".

V takomto prípade je príloha e-mailu, teda samotný PDF súbor reprezentujúci e-doklad, uchovaný v rovnakom adresári, aký je použitý pri vyhotovovaní elektronického dokladu v režime PDF súboru (pozri sekciu "Elektronický doklad vo forme PDF súboru").

Takéto správanie vyplýva z metodických pokynov finančnej správy sa online registračná pokladnica (v tomto prípade systém PORTOS eKasa) nesmie pokúsiť o viacnásobné zaslanie rovnakého dokladu.

Proces odoslania emailu má 3 fázy:

1. nadviazanie sieťového spojenia s emailovým serverom: Ak tento krok zlyhá, aplikácia vyhlási chybu Spojenie s emailovým serverom sa nepodarilo nadviazať. Skontrolujte nastavenia e-mailového servera.. Ak systém hlási túto chybu, skúste v nastaveniach aplikácie vypnúť kontrolu SSL tak, že v "Typ pripojenia" zvolíte "Použiť TLS, ak je k dispozícii". Taktiež overte ostatné SMTP nastavenia.
2. autentikácia emailového klienta (ak je v nastaveniach zapnuté, že je potrebné sa autentifikovať): Ak tento krok zlyhá, aplikácia vyhlási chybu Prihlásenie na emailovom serveri nebolo úspešné. Skontrolujte nastavenia e-mailového konta.. V tomto prípade sú pravdepodobne zle nastavené prihlasovacie údaje v nastaveniach aplikácie.
3. samotné odoslanie emailu: Ak zlyhá s SMTP chybovým kódom RecipientNotAccepted, aplikácia vyhlási chybu Odoslanie e-mailu zlyhalo. E-mailová adresa príjemcu nebola akceptovaná.. Ak zlyhá s iným SMTP chybovým kódom, aplikácia vyhlási chybu Odoslanie e-mailu zlyhalo. Skontrolujte e-mailové nastavenia..

6. Ochrana proti duplicitnému zaevidovaniu dokladu

Uvažujme nasledovný scenár:

1. nadradená aplikácia zašle do systému PORTOS eKasa pokladničný doklad.
2. PORTOS eKasa doklad odošle na server finančnej správy - tržba tak je už zaevidovaná.
3. Pri zasielaní odpovede naspäť do nadradenej aplikácie však dojde k nečakanej poruche, ktorá zabráni tomu, aby nadradená aplikácia dokázala vyhodnotiť odpoveď zo systému PORTOS eKasa.

V tomto bode nie je z pohľadu nadradenej aplikácie zrejmé, či sa doklad skutočne podarilo zaregistrovať.

Nadradená aplikácia by teda mohla doklad poslať znovu, čím by ale mohlo dôjsť k viacnasobnému zaevidovaniu tržby na serveroch finančnej správy, čo je neželaný efekt.

Ochrana proti duplicnému zaevidovaniu tržby spočíva v uvedení unikátneho identifikátora externalId, ktorý generuje nadradená aplikácia pri registrácii dokladu.

{
  "request": {
    "data": { ... }, // údaje o pokladničnom doklade
    "externalId": "this-is-generated-by-your-app" // unikátny identifikátor, ktorý generuje nadradená aplikácia
  }
}

Pole externalId je nepovinné. Ak je však uvedené, systém PORTOS eKasa kontroluje unikátnosť tohto identifikátora nasledovne:

Ak je v systéme PORTOS eKasa už nájdená registrácia s rovnakým externalId, systém PORTOS eKasa:

• vráti výsledok pôvodnej registrácie dokladu (nevzniká tak duplicitná tržba), ak ide o registráciu identického dokladu (teda práve registrovaný doklad sa presne zhoduje s nájdeným dokladom naprieč všetkými vlastnosťami).
• vráti chybovú odpoveď, ak ide o registráciu dokladu, ktorý sa odlišuje od nájdeného, už zaregistrovaného dokladu.

7. Analýza výsledku zaevidovania dokladu

Po zaregistrovaní dokladu je vrátený objekt informujúci o výsledku registrácie dokladu, ktorý obsahuje:

• isSuccessful: indikuje, či doklad bol úspešne zaregistrovaný v online režime (hodnota true), či registrácia dokladu bola prijatá v offline režime (hodnota null), alebo či registrácia dokladu bola vybavená v online režime, ale zároveň bola odmietnutá systémom eKasa (hodnota false).
• request: Informácie o požiadavke odosielanej na systém eKasa, ktorá pozostáva z pôvodných údajov zaslaných nadradenou aplikáciou, ako aj doplnených údajov, ako napríklad číslo dokladu (receiptNumber), overovací kód podnikateľa (okp) a podobne.
• response: Výsledok spracovania dokladu, obsahujúci informácie zo systému finančnej správy eKasa. Toto pole nadobúda hodnotu (nie je null) iba v prípade, ak je pole isSuccessful rovné true.
• error: Chybový objekt obsahujúci informácie zo systému finančnej správy eKasa. Toto pole nadobúda hodnotu (nie je null) iba v prípade, ak je pole isSuccessful rovné false.

Príklad výsledku evidencie požiadavky, ktorá bola úspešne zaevidovaná v online režime:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0",
      ... // ostatné informácie o doklade
    },
    ... // ostatné informácie o požiadavke do systému eKasa
  },
  "response": {
    "data": {
      "id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A"
    },
    "processDate": "2019-04-27T20:57:42+02:00"
  },
  "isSuccessful": true,
  "error": null,
  "$type": "Receipt"
}

Príklad výsledku evidencie požiadavky, ktorá bola zaevidovaná v offline režime:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0",
      ... // ostatné informácie o doklade
    },
    ... // ostatné informácie o požiadavke do systému eKasa
  },
  "response": null, // požiadavka vybavená v offline režime - žiadne dáta zo systému eKasa
  "isSuccessful": null,
  "error": null,
  "$type": "Receipt"
}

Príklad výsledku evidencie požiadavky zamietnutej serverom finančnej správy:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0",
      ... // ostatné informácie o doklade
    },
    ... // ostatné informácie o požiadavke do systému eKasa
  },
  "response": null, // požiadavka nebola prijatá systémom eKasa
  "isSuccessful": false, // požiadavka bola zamietnutá systémom eKasa
  "error": { // informácie o zamietnutí požiadavky zo systému finančnej správy eKasa
    "message": "Chyba v podpise dátovej správy.", // chybová správa zo serveru eKasa
    "code": -10 // chybový kód zo serveru eKasa
  },
  "$type": "Receipt"
}

Príklad požiadavky a odpovede

Požiadavka:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "headerText": "Nine Digit, s.r.o.",
      "footerText": "Otvorené non-stop.",
      "customer": {
        "id": "2004567890",
        "type": "DIC"
      },
      "items": [
        {
          "type": "returnedContainer",
          "name": "Coca Cola 0.25l",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": -0.445000,
          "price": -0.45,
          "vatRate": 20.00
        }
      ],
      "payments": []
    }
  }
}

Odpoveď:

{
  "request": {
    "data": {
      "receiptType": "CashRegister",
      "amount": -0.45,
      "issueDate": "2020-02-05T14:47:38+01:00",
      "receiptNumber": 10,
      "invoiceNumber": null,
      "paragonNumber": null,
      "icdph": "SK1234567890",
      "ico": "76543210",
      "customer": {
        "id": "2004567890",
        "type": "DIC"
      },
      "basicVatAmount": -0.08,
      "reducedVatAmount": null,
      "taxFreeAmount": null,
      "taxBaseBasic": -0.37,
      "taxBaseReduced": null,
      "items": [
        {
          "type": "ReturnedContainer",
          "name": "Coca Cola 0.25l",
          "price": -0.45,
          "unitPrice": -0.445000,
          "quantity": {
            "amount": 1.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": 20.00,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        }
      ],
      "okp": "65f0936f-a4c82f9e-0b4c0239-60c7d20c-84637367",
      "pkp": "C/A3hXBy27gLntkD9VPtGQq0xdylvgcpgVkw0hlToXaVuKRK9GkdDrw30b0d5hNioeFQRdwO6UQJ9ZdVRpjY9bOTLu/LTCE+bqgDMRyD8RzSz6buQ6WlYqIHnVegZbRF1QN7uWvu/ZRKyWjjW3OKUMCQ35XPuVXV+NpfN1DGzpaVw6GkXgXZnZ0mLrWHPkCwBqpQFRmIwMbv3BXbAUxyJFDAwnCdWHlTORZD21j5plmwdu1l6FTC6tArOzqyInkpHsbpL2cofJvQQzOPoS6Wo7WgkYLaSbGAV5ONuHJlwrd5UQULFKgDGqnyRaAhJjHo+kE7RaNy0v7yovOCU4XhnA==",
      "payments": [],
      "headerText": "Nine Digit, s.r.o.",
      "footerText": "Otvorené non-stop.",
      "createDate": "2020-02-05T14:47:38+01:00",
      "dic": "1234567890",
      "cashRegisterCode": "88812345678900001"
    },
    "id": "ddd26335-bb43-492a-9d56-3a7d7e89da1c",
    "externalId": null,
    "date": "2020-02-05T14:47:38+01:00",
    "sendingCount": 1
  },
  "response": {
    "data": {
      "id": "O-5687FF5863BE4C6587FF5863BE0-TEST"
    },
    "processDate": "2020-02-05T14:47:39+01:00"
  },
  "isSuccessful": true,
  "error": null,
  "$type": "Receipt"
}

7.1 Získanie čísla dokladu

Číslo dokladu je unikátne číslo v rámci kalendárneho mesiaca.

Ide o súvislú číselnú radu, ktorá je spoločná pre všetky typy pokladničných dokladov.

Číslo dokladu sa nachádza v poli request.data.receiptNumber.

7.2 Získanie unikátneho identifikátora dokladu

Unikátny identifikátor dokladu je vhodné si v nadradenej aplikácii pamätať pre účely prípadného dodatočného stornovania dokladu, prípadne pri vrátení tovaru (reklamácia, ...).

Ak je požiadavka vybavená v online režime (isSuccessful nadobúda hodnotu true), k dispozícií je unikátny identifikátor dokladu pridelený systémom eKasa, ktorý sa nachádza v poli response.data.id.

Ak je požiadavka vybavená v offline režime (isSuccessful nadobúda hodnotu null), unikátny identifikátor dokladu pridelený systémom eKasa nie je k dispozícii. V takomto prípade sa miesto unikátneho identifikátora používa overovací kód podnikateľa, ktorý sa nachádza v poli request.data.okp.

Jeden z týchto dvoch identifikátorov je pri korekcii dokladu potrebné uvádzať do poľa referenceReceiptId položky dokladu.

8. Oprava dokladu

Oprava dokladu môže mať rôzne príčiny a preto aj registrácia takejto operácie v systéme eKasa sa môže líšiť.

Táto sekcia popisuje viaceré situácie, ktoré v súvislosti s opravami dokladov môžu nastať:

Situácia	Riešenie
Obsluha pokladnice vykonala omyl	Storno dokladu
Zákazník vracia tovar zakúpený tovar	Vrátenie dokladu
Zakazník uhradil faktúru v hotovosti a následne túto úhradu potrebujeme vrátiť	Vrátenie úrady faktúry
Dobropisovanie faktúry uhradenej inak, ako v hotovosti (napr. prevodom na účet)	Dobropis faktúry

8.1 Storno dokladu

Ak je potreba opraviť už vyhotovený doklad (storno dokladu, vrátenie tovaru a podobne), je potrebné zaregistrovať nový doklad, v ktorom sa budú nachádzať tie položky dokladu, ktoré majú byť opravené, s nasledovnými rozdielmi:

• jednotkové ceny a celkové ceny položiek sa násobia konštantou -1, aby sme docielili opačný obrat.
• typ položky dokladu sa z pôvodného typu mení na typ correction.
• v každej položke je treba uviesť v poli referenceReceiptId unikátny identifikátor (alebo OKP) pôvodného dokladu.

Príklad

Pôvodný doklad:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

Storno doklad:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "correction",
          "referenceReceiptId" : "O-15FEDE7682064367BEDE7682064-TEST",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": -1.99,
          "price": -3.98,
          "vatRate": 20.00
        },
        {
          "type": "correction",
          "referenceReceiptId" : "O-15FEDE7682064367BEDE7682064-TEST",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": 1.00,
          "price": 1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": -2.98
        }
      ]
    }
  }
}

8.2 Vrátenie tovaru

V prípade, že zákazník vráti zakúpený tovar, je potrebné zaregistrovať nový doklad, v ktorom sa budú nachádzať tie položky dokladu, ktoré sú vrátené:

• do množstva sa vkladá počet vrátených jednotiek (ide o kladnú číselnú hodnotu)
• typ položky dokladu sa z pôvodného typu mení na typ returned.
• v každej položke je treba uviesť v poli referenceReceiptId unikátny identifikátor (alebo OKP) pôvodného dokladu.

Ak sa na položku vzťahuje zľava, je možné tovar vrátiť spojením pôvodnej kladnej položky a prislúchajúcej zľavy do jednej položky, ktorej celková suma bude rovná súčtu ceny kladnej položky a výške prislúchajúcej zľavy (príklad č. 1).

Alternatívne je možné položku zľavy zaregistrovať ako kladnú položku (príklad č. 2).

Príklad č.1

Pôvodný doklad:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

Doklad s vrátením tovaru:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "returned",
          "referenceReceiptId" : "O-15FEDE7682064367BEDE7682064-TEST",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": -1.49,
          "price": -2.98,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": -2.98
        }
      ]
    }
  }
}

Príklad č.2

Pôvodný doklad:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

Doklad s vrátením tovaru:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "returned",
          "referenceReceiptId" : "O-15FEDE7682064367BEDE7682064-TEST",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": -1.99,
          "price": -3.98,
          "vatRate": 20.00
        },
        {
          "type": "positive",
          "name": "Vrátenie zľavy",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": 1.00,
          "price": 1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": -2.98
        }
      ]
    }
  }
}

8.3 Vrátenie úhrady faktúry

V prípade, ak je potrebné vratiť zaevodovanú hotovostnú úhradu faktúry, ktorá bola zargistrovaná cez systém eKasa prostredníctvom dokladu typu invoice, postup je podobný, ako pri vrátení tovaru - vrátenie realizujete vytvorením pokladničného dokladu (doklad typu cash_register), do ktorého vložite nasledovnú položku:

• typ položky bude correction
• cena tejto položky bude rovná zápornej sume pôvodnej hotovostnej úhrady faktúry
• do poľa referenceReceiptId vložíme identifikátor pôvodného dokladu - faktúry
• v názve položky uvediete napríklad "Dobropis faktúry číslo ...".

Príklad hotovostnej úhrady faktúry:

URL: POST {{server_address}}/api/v1/requests/receipts/invoice

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "invoiceNumber": "FA-0001",
      "amount": 189.90
    }
  }
}

Príklad vrátenia hotovostnej úhrady faktúry:

URL: POST {{server_address}}/api/v1/requests/receipts/cash_register

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "correction",
          "referenceReceiptId" : "O-15FEDE7682064367BEDE7682064-TEST",
          "name": "Dobropis faktúry číslo FA-0001",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": -189.90,
          "price": -189.90,
          "vatRate": 0.00
        }
      ]
    }
  }
}

8.4 Dobropis faktúry

V prípade, ak je potrebné dobropisovať faktúru, ktorá nebola uhradená prostredníctvom systému eKasa a teda neexistuje k nej pokladničný doklad úhrady faktúry s unikátnym identifikátorom, možné je dobropis zaregistrovať vo forme hotovostnej úhrady faktúry (doklad typu invoice) so záporným znamienkom:

Príklad dobropisovania faktúry zápornou úhradou:

URL: POST {{server_address}}/api/v1/requests/receipts/invoice

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "invoiceNumber": "FA-0001",
      "amount": -189.90
    }
  }
}

9. Zľava na doklade

Pre zníženie celkovej sumy dokladu je možné používať položky typu zľava. V nasledujúcich odsekoch sú uvedené príklady na aplikovanie zľavy na jednu položku účtu a aplikovanie zľavy na celý doklad.

Pri komponovaní položky zľavy je potrebné zabezpečiť, aby celková suma zliav (v absolútnej hodnote) nepresiahla sumu ostatných evidovaných položiek dokladu v rovnakej sadzbe DPH. Napríklad, ak doklad obsahuje jednu kladnú položku s hodnotou 10 eur, na doklad je možné aplikovať iba zľavu v rovnakej sadzbe DPH, v akej je evidovaná kladná položka dokladu a zároveň suma zľavy nesmie presiahnúť 10 eur.

Ak by doklad pozostával z troch položiek v rôznych sadzbách DPH, pričom každá má hodnotou 1 euro, na doklad je možné aplikovať iba zľavu vo výške 1 euro za každú sadzbu DPH.

Ak toto pravidlo nebude dodržané, zo systému je vrátená chybová hláška so znením Doklad je nevalídny: 'Suma zliav nesmie presiahnúť sumu ostatných evidovaných položiek dokladu v rovnakej sadzbe DPH.' (platí od verzie 5.4).

9.1 Zľava na položku účtu

Ak je na položku dokladu aplikovaná zľava, je potrebné ju v zozname položiek evidovať ako ďalšiu položku, ktorá:

• má typ položky discount
• má rovnakú sadzbu DPH, ako pôvodná položka

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 3.98,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Vernostná zľava",
          "quantity": {
            "amount": 1.00
          },
          "unitPrice": -1.00,
          "price": -1.00,
          "vatRate": 20.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 2.98
        }
      ]
    }
  }
}

9.2 Zľava na celý doklad

Ak chceme aplikovať zľavu na celý doklad, je potrebné pre každú použitú sadzbu DPH vytvoriť jednu zľavovú položku. To znamená, že doklad bude obsahovať najmenej toľko položiek typu discount, koľko je v doklade použitých rôznych sadzieb DPH.

Príklad: Doklad s 3 položkami v rôznych sadzbách DPH, na ktorý chceme aplikovať 50% zľavu. Z pôvodných 16 EUR tak suma zliav tvorí 8 EUR.

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Položka v základnej sadzbe DPH",
          "quantity": {
            "amount": 10
          },
          "unitPrice": 1.00,
          "price": 10.00,
          "vatRate": 20.00
        },
        {
          "type": "positive",
          "name": "Položka v zníženej sadzbe DPH",
          "quantity": {
            "amount": 5
          },
          "unitPrice": 1.00,
          "price": 5.00,
          "vatRate": 10.00
        },
        {
          "type": "positive",
          "name": "Položka v nulovej sadzbe DPH",
          "quantity": {
            "amount": 1
          },
          "unitPrice": 1.00,
          "price": 1.00,
          "vatRate": 0.00
        },
        {
          "type": "discount",
          "name": "Zľava 50% na celý doklad",
          "quantity": {
            "amount": 1
          },
          "unitPrice": -5.00,
          "price": -5.00,
          "vatRate": 20.00
        },
        {
          "type": "discount",
          "name": "Zľava 50% na celý doklad",
          "quantity": {
            "amount": 1
          },
          "unitPrice": -2.50,
          "price": -2.50,
          "vatRate": 10.00
        },
        {
          "type": "discount",
          "name": "Zľava 50% na celý doklad",
          "quantity": {
            "amount": 1
          },
          "unitPrice": -0.50,
          "price": -0.50,
          "vatRate": 0.00
        }
      ]
    }
  }
}

10. Predaj a uplatnenie poukazu

Pri predaji a uplatňovaní poukážok je potrebné rozlišovať medzi "jednoúčelovými" a "viacúčelovými" poukážkami.

• Jednoúčelový poukaz: poukaz, pri ktorom je vopred známe miesto dodania tovaru alebo služby, na ktorý bude poukaz uplatnený, ako aj hladina DPH daného tovaru alebo služby.
• Viacúčelový poukaz: poukaz iný, ako jednoúčelový. Teda poukaz, pri ktorom nie je vopred jasný typ, prípadne miesto dodania tovaru alebo služby, a teda hladina DPH nie je vopred známa.

V závislosti od typu poukazu sa uplatňovanie poukazu v eKase líši, viac v odstavcoch nižšie.

10.1 Jednoúčelový poukaz

Pre uplatnenie vopred zakúpeného jednoúčelového poukazu je potrebné do dokladu vložiť položku typu Voucher (jednoúčelový poukaz).

Ak je celková hodnota tohto poukazu vyššia, ako suma ostatných položiek dokladu v rovnakej sadzbe DPH, výsledná suma dokladu je 0 €, nakoľko z hodnoty poukazu nie je možné vrátiť finančný rozdiel. (platí od verzie 5.4)

Ak sa okrem jednoúčelového poukazu na doklade nenachádza iná kladná položka v rovnakej sadzbe DPH, aplikácia vráti chybové hlásenie: "Uplatnenie jednoúčelového poukazu nie je možné, nakoľko v rovnakej sadzbe DPH nebola nájdená žiadna položka s kladnou cenou, na ktorú sa poukaz uplatňuje." (platí od verzie 5.6.3).

Príklad 1: Podnikateľ prijal jednoúčelový poukaz na výmenu vo výške 20 € na nákup produktov. Kupujúci si za daný poukaz kúpil produkty v hodnote 18 €. V tomto prípade je hodnota zakúpeného tovaru nižšia ako hodnota poukazu a nakoľko z hodnoty poukazu nie je možné vrátiť finančný rozdiel, výsledná suma dokladu je 0 €.

Príklad 2: Podnikateľ prijal jednoúčelový poukaz na výmenu vo vyške 100 € na nákup produktov v sadzbe DPH 20%. Kupujúci nakúpil dva produkty, prvý v cene 60 € a sadzbe DPH 20% a druhý v cene 40 € a sadzbe DPH 10%. Výsledná suma dokladu je 40 €, nakoľko jednoúčelový poukaz za uplatňuje len na rovnakú sadzbu DPH.

Predaj jednoúčelového poukazu:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Predaj jednoúčelového poukazu",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": 20.00,
        "price": 20.00,
        "vatRate": 20.00 // poukaz sa predáva v rovnakej sadzbe DPH, v ktorej bude uplatňovaný
      }],
      "payments": [{
        "name": "Hotovosť",
        "amount": 20
      }]
    }
  }
}

Uplatnenie jednoúčelového poukazu:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Produkt",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": 18.00,
        "price": 18.00,
        "vatRate": 20.00
      }, {
        "type": "voucher",
        "name": "Uplatnenie poukazu 20 EUR",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": -20.00,
        "price": -20.00,
        "vatRate": 20.00, // poukaz je uplatňovaný v rovnakej sadzbe DPH, v ktorej bol predaný 
          "voucherNumber": "123456"
      }],
      "payments": [{
        "name": "Hotovosť",
        "amount": 0 // výsledná suma dokladu je 0 eur
      }]
    }
  }
}

10.2 Viacúčelový poukaz

Warning

Uvedené riešenie predaja a uplatnenia viacúčelového poukazu je iba ilustračné a nepokrýva všetky prípady uvedené v metodickom pokyne finančnej správy. V prípade nejasností sa obráťte na podporu finančnej správy.

Pri predaji viacúčelového poukazu sa v doklade môže evidovať kladná položka (typ positive) v nulovej sadzbe DPH.

Tip

V zmysle § 9a ods. 5 zákona o DPH na rozdiel od prevodu jednoúčelového poukazu, ktorý sa považuje za dodanie tovaru alebo dodanie služby, na ktoré sa poukaz vzťahuje, prevod viacúčelového poukazu sa nepovažuje za dodanie tovaru alebo služby a nie je predmetom dane.

Zdroj: Metodický pokyn k uplatňovaniu dane z pridanej hodnoty v prípade dodania tovaru a služby pri použití poukazu podľa § 9a zákona č. 222/2004 Z. z. o dani z pridanej hodnoty v znení neskorších predpisov

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Predaj viacúčelového poukazu",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": 100.00,
        "price": 100.00,
        "vatRate": 0.00
      }],
      "payments": [{
        "name": "Hotovosť",
        "amount": 100
      }]
    }
  }
}

Pri uplatnení (spotrebe) viacúčelového poukazu sa v doklade v súvislosti s uplatnením viacúčelového poukazu môžu aplikovať dva spôsoby:

10.2.1. uplatnenie viacúčelového poukazu vo forme položky

Prvým spôsobom je vloženie položky dokladu typu advance v nulovej sadzbe DPH a s negatívnou sumou, ktorá tak znižuje výslednú sumu za doklad.

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Televízor",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": 800.00,
        "price": 800.00,
        "vatRate": 20.00
      }, {
        "type": "advance",
        "name": "Uplatnenie viacúčelového poukazu",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": -100.00,
        "price": -100.00,
        "vatRate": 0.00
      }],
      "payments": [{
        "name": "Hotovosť",
        "amount": 700 // kupujúcemu ostáva uhradiť sumu zníženú o cenu poukazu
      }]
    }
  }
}

10.2.2. uplatnenie viacúčelového poukazu ako platidlo

V tomto prípade sa v doklade nenachádza žiadna položka popisujúca uplatnenie viacúčelového poukazu. Naopak, spotrebovaný poukaz sa eviduje ako platidlo. Celková suma za doklad ostáva teda neovplyvnená, klientovi však k úhrade zostáva čiastka znížená o sumu poukazu, nakoľko poukaz je premietnutý do platidiel.

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Televízor",
        "quantity": {
          "amount": 1.00,
          "unit": "ks"
        },
        "unitPrice": 800.00,
        "price": 800.00,
        "vatRate": 20.00
      }],
      "payments": [{
        "name": "Uplatnenie viacúčelového poukazu",
        "amount": 100
      }, {
        "name": "Hotovosť",
        "amount": 700 // kupujúcemu ostáva uhradiť sumu zníženú o cenu poukazu
      }]
    }
  }
}

11. Dodatočné texty na doklade

Doklad obsahuje dodatočné vlastnosti pre vloženie dodatočných textov na doklad.

Názov	Popis	Poznámka
headerText	Text tlačený hneď za identifikačnými údajmi	V prípade použitia tokenov nie je aplikovaný pageBreak token
footerText	Text tlačený na konci dokladu, za QR kódom

Obe vlastnosti podporujú použitie tzv. token-ov pre formátovanie, tlač QR kódov a čiarových kódov. Viac nájdete v článku Tokeny a formátovanie textu.

Príklad:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "invoiceNumber": "FA-0001",
      "amount": 189.90,
      "headerText": "Nine Digit, s.r.o.\r\nweb: www.ninedigit.sk",
      "footerText": "Otvorené non-stop."
    }
  }
}

12. Overenie dokladu

V prípade, že testujete integráciu na integračnom prostredí systému eKasa, Vaše doklady si môžete overiť na adrese: https://iekasa.financnasprava.sk/opd/#!/check.

13. Zaokrúhľovanie

Od 1.7.2022 nadobúda účinnosť zmena v zákone o cenách, ktorá prináša povinné zaokrúhľovanie za účelom obmedzenia používania 1 eurocentových a 2 eurocentových mincí.

Cena platená v hotovosti sa zaokrúhľuje na 5 eurocentov. Celkový zvyšok nezaokrúhlenej ceny platenej v hotovosti, ktorý je nižší ako polovica hodnoty 5 eurocentov, sa zaokrúhľuje nadol a celkový zvyšok nezaokrúhlenej ceny platenej v hotovosti, ktorý je rovný alebo vyšší ako polovica hodnoty 5 eurocentov, sa zaokrúhľuje nahor. Cena platená v hotovosti vo výške 1 eurocent alebo 2 eurocenty sa zaokrúhľuje na 5 eurocentov.

Tá časť dokladu, ktorá je hradená bezhotovostne (platobnou kartou, stravnými lístkami, atď.) nie je predmetom zaokrúhľovania. Zaokrúhľuje sa iba čiastka platená v hotovosti.

Výpočet DPH bude zo sumy pred zaokrúhlením. Zaokrúhľovanie pri platbe nákupu v hotovosti tak nebude mať vplyv na výpočet DPH z nákupu tovaru.

13.1 Vlastnosť roundingAmount

Pole pre uvedenie čiastky na zaokrúhlenie (vlastnosť roundingAmount) je k dispozícii pre tie typy dokladov, kde nadradená aplikácia priamo neuvádza celkovú sumu za doklad (teda neobsahujú pole amount). Ide o pokladničný doklad (cashRegister), neplatný doklad (invalid) a paragón (paragon).

Pre ostatné typy dokladov (úhrada faktúry invoice, vklad deposit a výber withdraw) platí, že nadradená aplikácia uvádza celkovú sumu za doklad (pole amount) vyjadrenú po zaokrúhlení.

Typ dokladu	Identifikátor typu dokladu	Obsahuje vlastnosť roundingAmount
Pokladničný doklad	CashRegister	Áno
Neplatný doklad	Invalid	Áno
Paragón	Paragon	Áno
Faktúra	Invoice	Áno (od verzie 5.24)
Paragón pri úhrade faktúry	InvoiceParagon	Áno (od verzie 5.24)
Doklad označený slovom „Vklad“	Deposit	Nie
Doklad označený slovom „Výber“	Withdraw	Nie

13.2. Príklady

Príklad 1: úhrada v hotovosti

Ak je nákupu hradený v hotovosti, suma je predmetom zaokrúhlenia. K sume 0.08 doplníme zaokrúhlenie (vlastnosť roundingAmount) vo výške 0.02 eur. Výsledná suma účtu je 0.10 eur.

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Pečivo",
        "quantity": {
          "amount": 1,
          "unit": "ks"
        },
        "unitPrice": 0.08,
        "price": 0.08,
        "vatRate": 20.00
      }],
      "roundingAmount": 0.02,
      "payments": [{
        "name": "Hotovosť",
        "amount": 0.10
      }]
    }
  }
}

Príklad 2: úhrada bezhotovostne

Ak je celková cena nákupu hradená bezhotovostne, cena sa nezaokrúhľuje.

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Pečivo",
        "quantity": {
          "amount": 1,
          "unit": "ks"
        },
        "unitPrice": 0.08,
        "price": 0.08,
        "vatRate": 20.00
      }],
      "roundingAmount": 0,
      "payments": [{
        "name": "Platobná karta",
        "amount": 0.08
      }]
    }
  }
}

Príklad 3: úhrada kombináciou platidiel

Ak je nákup hradený kombináciou hotovostných a iných platidiel, zaokrúhľuje sa iba cena hradená v hotovosti.

Kupujúci chce zaplatiť dvomi stravnými lístkami v hodnote 3,83€, spolu 7,66 € a zvyšok doplatiť v hotovosti. Hodnota stravných lístkov, nakoľko nie je hotovosťou, sa odpočíta z výslednej nezaokrúhlenej ceny nákupu. Zaokrúhli sa až zvyšná cena nákupu platená v hotovosti, čiže 48,33 – 7,66 = 40,68 €, a to matematicky nahor, na 40,70 €. Kupujúci doplatí v hotovosti 40,70 €. Výsledná cena nákupu po zaokrúhlení bude 48,36 €.

Požiadavka:

{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [{
        "type": "positive",
        "name": "Pečivo",
        "quantity": {
          "amount": 1,
          "unit": "ks"
        },
        "unitPrice": 48.34,
        "price": 48.34,
        "vatRate": 20.00
      }],
      "roundingAmount": 0.02,
      "payments": [{
        "name": "Stravné lístky",
        "amount": 7.66
      },
      {
        "name": "Hotovosť",
        "amount": 40.70
      } ]
    }
  }
}

Odpoveď:

{
  "request": {
    "data": {
      "amount": 48.36,
      "roundingAmount": 0.02,
      ...
    },
    ...
  },
  ...
}

13.3. Tabuľka s príkladmi zaokrúhľovania platených cien:

Platená cena v € pred zaokrúhlením	Platená cena v € po zaokrúhlení	Poznámka
0,01	0,05	Cena do 0,02 € vrátane, ktorá by sa matematicky zaokrúhlila na 0,00 €, sa zaokrúhli nahor, na 0,05 €.
0,02	0,05	Cena do 0,02 € vrátane, ktorá by sa matematicky zaokrúhlila na 0,00 €, sa zaokrúhli nahor, na 0,05 €.
0,03	0,05	Matematické zaokrúhlenie.
0,04	0,05	Matematické zaokrúhlenie.
0,05	0,05	Cena sa nezaokrúhľuje.
0,06	0,05	Matematické zaokrúhlenie.
0,07	0,05	Matematické zaokrúhlenie.
0,08	0,10	Matematické zaokrúhlenie.
0,09	0,10	Matematické zaokrúhlenie.
0,10	0,10	Cena sa nezaokrúhľuje.
0,11	0,10	Matematické zaokrúhlenie.
0,12	0,10	Matematické zaokrúhlenie.
0,13	0,15	Matematické zaokrúhlenie.
0,14	0,15	Matematické zaokrúhlenie.
0,15	0,15	Cena sa nezaokrúhľuje.
0,16	0,15	Matematické zaokrúhlenie.
0,17	0,15	Matematické zaokrúhlenie.
0,18	0,20	Matematické zaokrúhlenie.
0,19	0,20	Matematické zaokrúhlenie.
0,20	0,20	Suma sa nezaokrúhľuje.
...	...	...

Viac informácii o zaokrúhľovaní nájdete tu:

• Tlačová správa ministerstva financií
• Návrh zákona