Výsledok registrácie

Integrujem cez

Po každej registrácii dokladu dostane váš softvér výsledok. Z neho zistíte, ako registrácia dopadla: doklad je zaregistrovaný online, prijatý v offline režime, alebo ho systém eKasa odmietol. Zároveň v ňom sú údaje, ktoré váš softvér potrebuje ďalej: číslo dokladu, unikátny identifikátor pre neskoršie storno alebo vrátenie tovaru a rekapitulácia DPH.

Pred registráciou si prečítajte Ochrana pred duplicitou: externalId zabráni dvojitej evidencii tržby, keď sa odpoveď stratí.

Čo výsledok obsahuje

API vráti výsledok v tele odpovede na registráciu dokladu.

Metóda RegisterReceiptAsync vráti objekt RegisterReceiptResult s vlastnosťami IsSuccessful, Request, Response a Error.

Vlastnosť Obsah Má hodnotu
isSuccessful Ako registrácia dopadla, pozri Tri možné výsledky. true, null alebo false
request Požiadavka odosielaná na systém eKasa: pôvodné údaje zaslané nadradenou aplikáciou a doplnené údaje, napríklad číslo dokladu (receiptNumber) a overovací kód podnikateľa (okp). vždy
response Výsledok spracovania dokladu s informáciami zo systému finančnej správy eKasa. len ak isSuccessful je true
error Chybový objekt s informáciami zo systému finančnej správy eKasa. len ak isSuccessful je false

Tri možné výsledky

isSuccessful Čo sa stalo response error
true Doklad bol úspešne zaregistrovaný v online režime. výsledok spracovania null
null Registrácia dokladu bola prijatá v offline režime. null null
false Registrácia bola vybavená v online režime, ale systém eKasa ju odmietol. null chyba

Príklady nižšie obsahujú len vybrané vlastnosti.

Online – doklad úspešne zaevidovaný v online režime:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
    }
  },
  "response": {
    "data": {
      "id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A"
    },
    "processDate": "2026-01-20T15:34:14+01:00"
  },
  "isSuccessful": true,
  "error": null,
  "$type": "Receipt"
}

Offline – doklad zaevidovaný v offline režime:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
    }
  },
  "response": null,
  "isSuccessful": null,
  "error": null,
  "$type": "Receipt"
}

Odmietnutý – požiadavka zamietnutá serverom finančnej správy:

{
  "request": {
    "data": {
      "receiptNumber": 2,
      "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0"
    }
  },
  "response": null,
  "isSuccessful": false,
  "error": {
    "message": "Chyba v podpise dátovej správy.",
    "code": -10
  },
  "$type": "Receipt"
}

Kde nájdete údaje dokladu

Údaj Vlastnosť Podrobnosti
Číslo dokladu request.data.receiptNumber Získanie čísla dokladu
Unikátny identifikátor (online) response.data.id Získanie unikátneho identifikátora
Overovací kód podnikateľa (offline) request.data.okp Získanie unikátneho identifikátora
Rekapitulácia DPH request.data.vatRatesTaxSummary Rekapitulácia DPH
Chyba zo systému eKasa error.code, error.message Tri možné výsledky
Údaj Vlastnosť Podrobnosti
Číslo dokladu result.Request.Data.ReceiptNumber Získanie čísla dokladu
Unikátny identifikátor (online) result.Response.Data.Id Získanie unikátneho identifikátora
Overovací kód podnikateľa (offline) result.Request.Data.OKP Získanie unikátneho identifikátora
Rekapitulácia DPH VatRatesTaxSummary.Create(result.Request.Data.Items) Rekapitulácia DPH
Chyba zo systému eKasa result.Error.Code, result.Error.Message Tri možné výsledky
RegisterReceiptResult result = await client.RegisterReceiptAsync(
    request, RegisterReceiptPrintContext.CreatePos(), cancellationToken);

ReceiptNumber receiptNumber = result.Request.Data.ReceiptNumber;

switch (result.IsSuccessful)
{
    case true:  // online: doklad zaregistrovaný v systéme eKasa
        EKasaReceiptId id = result.Response.Data.Id;
        break;
    case null:  // offline: registrácia prijatá v offline režime
        OKP okp = result.Request.Data.OKP;
        break;
    case false: // online, ale systém eKasa doklad odmietol
        int? code = result.Error.Code;
        string message = result.Error.Message;
        break;
}

VatRatesTaxSummary? vatSummary = result.Request.Data.Items is { } items
    ? VatRatesTaxSummary.Create(items)
    : null;

Príklad požiadavky a odpovede

Ukážka je nákup v kaviarni zaplatený v hotovosti. Obsahuje položky v sadzbách DPH 23 %, 19 % a 5 % a vratné obaly (nepodliehajú DPH). Doklad je vytlačený do PDF:

Vytlačený doklad z kaviarne s položkami v sadzbách 23 %, 19 % a 5 %, vratnými obalmi, zaokrúhlením, rekapituláciou DPH, UID a OKP

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

{
  "print": {
    "printerName": "pdf"
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "headerText": "https://ekasa.ninedigit.sk",
      "footerText": "Ďakujeme za nákup!",
      "items": [
        {
          "type": "Positive",
          "name": "Cappuccino",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 2.90,
          "price": 5.80,
          "vatRate": 19.00
        },
        {
          "type": "Positive",
          "name": "Croissant maslový (3 ks za 4 €)",
          "quantity": {
            "amount": 3.00,
            "unit": "ks"
          },
          "unitPrice": 1.333333,
          "price": 4.00,
          "vatRate": 5.00
        },
        {
          "type": "Positive",
          "name": "Minerálka 0,33 l (2 ks za 2,25 €)",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 1.125,
          "price": 2.25,
          "vatRate": 19.00
        },
        {
          "type": "Positive",
          "name": "Pohľadnica Bratislava",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 0.88,
          "price": 1.76,
          "vatRate": 23.00
        },
        {
          "type": "Positive",
          "name": "Záloha PET",
          "quantity": {
            "amount": 2.00,
            "unit": "ks"
          },
          "unitPrice": 0.15,
          "price": 0.30
        },
        {
          "type": "ReturnedContainer",
          "name": "Vrátenie zálohy PET",
          "quantity": {
            "amount": 3.00,
            "unit": "ks"
          },
          "unitPrice": -0.15,
          "price": -0.45
        }
      ],
      "roundingAmount": -0.01,
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 20.00
        },
        {
          "name": "Výdavok",
          "amount": -6.35
        }
      ]
    }
  }
}

Odpoveď, vybrané vlastnosti. Číslo dokladu 35 je na doklade v riadku Doklad, response.data.id v riadku UID a okp v riadku OKP:

{
  "request": {
    "data": {
      "receiptNumber": 35,
      "amount": 13.65,
      "okp": "C1E7A53E-6D1D48B0-801EE45D-6B67BF63-6C2AA5CF"
    }
  },
  "response": {
    "data": {
      "id": "O-488AE60F5DDC432E8AE60F5DDC7-TEST"
    },
    "processDate": "2026-11-19T02:08:43+01:00"
  },
  "isSuccessful": true,
  "error": null,
  "$type": "Receipt"
}
Celá odpoveď
{
  "request": {
    "data": {
      "receiptType": "CashRegister",
      "amount": 13.65,
      "roundingAmount": -0.01,
      "issueDate": "2026-11-19T02:08:43+01:00",
      "receiptNumber": 35,
      "invoiceNumber": null,
      "paragonNumber": null,
      "icdph": "SK1234567890",
      "ico": "76543210",
      "basicVatAmount": 0.33,
      "reducedVatAmount": 1.29,
      "secondReducedVatAmount": 0.19,
      "taxFreeAmount": null,
      "nonTaxableAmount": -0.15,
      "taxBaseBasic": 1.43,
      "taxBaseReduced": 6.76,
      "taxBaseSecondReduced": 3.81,
      "items": [
        {
          "type": "Positive",
          "name": "Cappuccino",
          "price": 5.80,
          "unitPrice": 2.900000,
          "quantity": {
            "amount": 2.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": 19.00,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        },
        {
          "type": "Positive",
          "name": "Croissant maslový (3 ks za 4 €)",
          "price": 4.00,
          "unitPrice": 1.333333,
          "quantity": {
            "amount": 3.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": 5.00,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        },
        {
          "type": "Positive",
          "name": "Minerálka 0,33 l (2 ks za 2,25 €)",
          "price": 2.25,
          "unitPrice": 1.125000,
          "quantity": {
            "amount": 2.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": 19.00,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        },
        {
          "type": "Positive",
          "name": "Pohľadnica Bratislava",
          "price": 1.76,
          "unitPrice": 0.880000,
          "quantity": {
            "amount": 2.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": 23.00,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        },
        {
          "type": "Positive",
          "name": "Záloha PET",
          "price": 0.30,
          "unitPrice": 0.150000,
          "quantity": {
            "amount": 2.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": null,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        },
        {
          "type": "ReturnedContainer",
          "name": "Vrátenie zálohy PET",
          "price": -0.45,
          "unitPrice": -0.150000,
          "quantity": {
            "amount": 3.0000,
            "unit": "ks"
          },
          "referenceReceiptId": null,
          "vatRate": null,
          "specialRegulation": null,
          "voucherNumber": null,
          "seller": null,
          "description": null
        }
      ],
      "vatRatesTaxSummary": {
        "totalVatBase": 12.00,
        "totalVatAmout": 1.81,
        "totalTaxableAmount": 13.81,
        "totalNonTaxableAmount": -0.15,
        "totalAmount": 13.66,
        "items": [
          {
            "vatRate": 19.00,
            "vatBase": 6.76,
            "vatAmount": 1.29,
            "totalAmount": 8.05
          },
          {
            "vatRate": 5.00,
            "vatBase": 3.81,
            "vatAmount": 0.19,
            "totalAmount": 4.00
          },
          {
            "vatRate": 23.00,
            "vatBase": 1.43,
            "vatAmount": 0.33,
            "totalAmount": 1.76
          },
          {
            "vatRate": null,
            "vatBase": -0.15,
            "vatAmount": 0.00,
            "totalAmount": -0.15
          }
        ]
      },
      "okp": "C1E7A53E-6D1D48B0-801EE45D-6B67BF63-6C2AA5CF",
      "pkp": "bRkmkbk9S/Kn9sylBgRQphmLLU/o+7gcao0q5TXJyb/ZHnQ27oVOERwQqUKqZeR0Q9J5j35fv1ucBn/TmT85yUfdmZ5a2c3rOdoB/h+z8YT+LFC0+5QCh9bbKkWu9TdXKMdPU4Exkl8bLY8rqpP80Ay/Uz/ACx7jEqdE5lPjIQoijyeYDEPkIWyAtr8vCql07x0c2oCP3fs0i1hcUz18uKcnYxpC08+60hpP1Rmj8FfAfd3S2Xqxo9W3Yn87lCs6n3LcbrNQbXLrHbCfKDuJa7yUyLY0Vh9i1zn5lFQBop9mWRyI+KUCYbWIQzBjIWUtJuz0fo/ofpHLhH54vyT9gQ==",
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 20.00
        },
        {
          "name": "Výdavok",
          "amount": -6.35
        }
      ],
      "headerText": "https://ekasa.ninedigit.sk",
      "footerText": "Ďakujeme za nákup!",
      "createDate": "2026-11-19T02:08:43+01:00",
      "dic": "1234567890",
      "cashRegisterCode": "88812345678900001"
    },
    "id": "9dc3e9ed-695c-4885-b96f-1ff8fa038a85",
    "externalId": null,
    "date": "2026-11-19T02:08:43+01:00",
    "sendingCount": 1
  },
  "response": {
    "data": {
      "id": "O-488AE60F5DDC432E8AE60F5DDC7-TEST"
    },
    "processDate": "2026-11-19T02:08:43+01:00"
  },
  "isSuccessful": true,
  "error": null,
  "$type": "Receipt"
}

Odpoveď na registráciu dokladu obsahuje aj sumárne informácie podľa kategórie DPH (základná vs. znížená), ktoré však v prípade kombinácie viacerých sadzieb v rovnakej kategórii (napríklad 23 % a 20 % pri dokladoch z prechodného obdobia, obe základné sadzby) môžu viesť k nejednoznačným výsledkom. Na získanie finančných ukazovateľov o obratoch DPH preto tieto vlastnosti nepoužívajte a uprednostnite vlastnosť vatRatesTaxSummary (rekapitulácia DPH). V budúcich verziách môžu byť tieto vlastnosti odstránené.

Vlastnosť Obsah V príklade
basicVatAmount DPH v základnej sadzbe (23 %) 0.33
taxBaseBasic základ dane v základnej sadzbe (23 %) 1.43
reducedVatAmount DPH v zníženej sadzbe (19 %) 1.29
taxBaseReduced základ dane v zníženej sadzbe (19 %) 6.76
secondReducedVatAmount DPH v druhej zníženej sadzbe (5 %) 0.19
taxBaseSecondReduced základ dane v druhej zníženej sadzbe (5 %) 3.81
taxFreeAmount suma oslobodená od DPH null
nonTaxableAmount suma položiek nepodliehajúcich DPH -0.15

Získanie čísla dokladu

Číslo dokladu je v poli request.data.receiptNumber. Je unikátne v rámci kalendárneho mesiaca a tvorí súvislú číselnú radu spoločnú pre všetky typy pokladničných dokladov.

Získanie unikátneho identifikátora dokladu

Unikátny identifikátor dokladu si v nadradenej aplikácii pamätajte pre prípadné dodatočné stornovanie dokladu alebo pre vrátenie tovaru (reklamácia, …). Kde ho nájdete, závisí od režimu, v ktorom bola požiadavka vybavená:

Režim isSuccessful Identifikátor Pole
online true unikátny identifikátor dokladu pridelený systémom eKasa response.data.id
offline null identifikátor systému eKasa nie je k dispozícii, namiesto neho sa používa overovací kód podnikateľa (OKP) request.data.okp

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

Doklad z integračného prostredia si overíte na stránke finančnej správy, pozri Príprava a test.

Rekapitulácia DPH

Od verzie 7.0.0 obsahuje odpoveď aj vlastnosť request.data.vatRatesTaxSummary: sumárne informácie rozdelené podľa sadzby DPH (tzv. rekapitulácia DPH). Je k dispozícii aj pre doklady vytvorené staršími verziami aplikácie (pred aktualizáciou na verziu 7.0.0). Ak doklad neobsahuje položky (vlastnosť items je null), aj vatRatesTaxSummary je null.

Vlastnosť Význam Príklad
totalVatBase Celková suma základov dane pre položky podliehajúce DPH 12.00
totalVatAmout Celková suma výšky dane (názov vlastnosti je naozaj takto) 1.81
totalTaxableAmount Celková suma položiek podliehajúcich DPH 13.81
totalNonTaxableAmount Celková suma položiek nepodliehajúcich DPH -0.15
totalAmount Celková suma všetkých položiek 13.66
items Zoznam sumárnych informácií podľa sadzby DPH. Obsahuje tie sadzby DPH (resp. položky nepodliehajúce DPH), ktoré sú zastúpené v zozname položiek dokladu (vlastnosť items).

Každý prvok zoznamu items:

Vlastnosť Význam Príklad
vatRate Sadzba DPH (23.00 znamená 23 %), alebo null pre položky nepodliehajúce DPH (napr. predaj alebo vrátenie vratných obalov) 23.00
vatBase Celková suma základu dane pre danú sadzbu DPH 1.43
vatAmount Suma DPH pre danú sadzbu DPH 0.33
totalAmount Celkový obrat pre danú sadzbu DPH 1.76

Pre každý prvok (vrátane sumáru pre položky nepodliehajúce DPH, tzn. vatRate je null) platí:

vatBase+vatAmount=totalAmount\text{vatBase} + \text{vatAmount} = \text{totalAmount}

Príklad

Rekapitulácia z príkladu vyššie. Na vytlačenom doklade jej zodpovedá tabuľka Sadzba – Základ – Daň – Obrat.

{
"totalVatBase": 12.00,
"totalVatAmout": 1.81,
"totalTaxableAmount": 13.81,
"totalNonTaxableAmount": -0.15,
"totalAmount": 13.66,
"items": [
  {
    "vatRate": 19.00,
    "vatBase": 6.76,
    "vatAmount": 1.29,
    "totalAmount": 8.05
  },
  {
    "vatRate": 5.00,
    "vatBase": 3.81,
    "vatAmount": 0.19,
    "totalAmount": 4.00
  },
  {
    "vatRate": 23.00,
    "vatBase": 1.43,
    "vatAmount": 0.33,
    "totalAmount": 1.76
  },
  {
    "vatRate": null,
    "vatBase": -0.15,
    "vatAmount": 0.00,
    "totalAmount": -0.15
  }
]
}

Kam ďalej

Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.