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:
- zvaliduje údaje z nadradenej aplikácie (overí matematické náležitosti, prítomnosť povinných parametrov a iné pravidlá alebo podmienky).
- výpočíta výšku obratov v jednotlivých daňových hladinách.
- uloží všetky potrebné údaje v dátovom úložisku.
- odošle údaje v podobe dátovej správy do systému finančnej správy eKasa.
- vyhotoví doklad v požadovanej podobe: papierový doklad, PDF súbor alebo odošle doklad ako PDF prílohu e-mailom.
- vráti nadradenej aplikácii všetky relevantné informácie súvisiace s registráciou dokladu.
Ako zaregistrujem doklad?
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.
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
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úryamount
: celková sumu faktúry s DPH
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ónuinvoiceNumber
: číslo faktúryamount
: celková suma faktúry s DPH
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.
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.
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.
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
Customer
- Informácia o kupujúcomWarning
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:
id
: identifikátortyp
: 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:
pos
- papierový dokladpdf
- elektronický doklad - PDF súboremail
- 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.
Kontext požiadavky evidencie pokladničného dokladu, zasielaný do HTTP WEB API nadradenou aplikáciou, obsahuje dve vlastnosti:
request
: informácie týkajúce sa samotného dokladuprint
: 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. |
{
"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 pokladniceyyyy
: rok vytvorenia dokladuMM
: mesiac vytvorenia dokladucislo_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ý.
{
"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.
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.
{
"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:
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:
- 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.
- 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.
- 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:
- nadradená aplikácia zašle do systému PORTOS eKasa pokladničný doklad.
- PORTOS eKasa doklad odošle na server finančnej správy - tržba tak je už zaevidovaná.
- 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 (hodnotatrue
), či registrácia dokladu bola prijatá v offline režime (hodnotanull
), alebo či registrácia dokladu bola vybavená v online režime, ale zároveň bola odmietnutá systémom eKasa (hodnotafalse
).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 jenull
) iba v prípade, ak je poleisSuccessful
rovnétrue
.error
: Chybový objekt obsahujúci informácie zo systému finančnej správy eKasa. Toto pole nadobúda hodnotu (nie jenull
) iba v prípade, ak je poleisSuccessful
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 (aleboOKP
) 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 (aleboOKP
) 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.
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: