API Error codes (Chybové kódy)

Súčasťou chybových odpovedí HTTP WEB API služby Portos eKasa sú aj chybové kódy (vlastnosť code). Táto sekcia popisuje význam jednotlivých chybových kódov.

Príklad chybovej odpovede

{
    "traceId": "0HLMCMV49LEUT:00000001",
    "code": -8,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-104-receiptnotfound",
    "title": "Doklad sa nenašiel",
    "status": 403,
    "detail": "Dopytu nevyhovuje žiaden záznam.",
    "instance": "/api/v1/requests/receipts/print_copy"
}

V závislosti od chybového kódu (vlastnosť code) sa v chybovej odpovedi môžu nachádzať ďalšie parametre, bližšie popisujúce chybový stav.

Napríklad pole key v prípade -403: StorageDuplicateKey

Kategórie chybových kódov

Všeobecné -1XX

Chyby identifikačných údajov -2XX

Chyby autentifikačných údajov -3XX

Chyby úložiska -4XX

Chyby tlače -5XX

Chyby licencie -6XX

Chyby QR platieb -7XX

Validačné chyby

Popis chybových kódov

-100: GeneralError

Bližšie nešpecifikovaná chyba. Konkrétnú príčinu chyby popisujú vlastnosti chybovej odpovede title a detail.

-101: ClientLocked

Počas registrácie dátovej správy, došlo k chybe, ktorá zabraňuje spracovaniu takejto požiadavky v systéme finančnej správy eKasa. EKasa klient nemôže pokračovať v registrácii ďalších dátových správ.

Riešením je odstránenie príčiny, ktorá zabraňuje úspešnému odoslaniu dátovej správy a následné reštartovanie aplikácie. Takéto správanie eKasa klienta je vyžadované finančnou správou.

Príčina, pre ktorú eKasa server odmietol spracovať požiadavku, je spolu s identifikátorom požiadavky uvedená v odpovedi v poli registration.error.

Vzor poľa registration:

"registration": {
    "request": {
        "id": "0826db63-a26a-450f-8502-68543b4378be",
        "externalId": "id-provided-by-external-application",
        "originUUID": "f7f5e7c8-2598-4dfb-a0f1-d07e6207e53e"
    },
    "error": {
        "message": "Zlé vstupné hodnoty.",
        "code": -2
    }
}

Napríklad, pre chybu s kódom -10, "Chyba v podpise dátovej správy.", je potrebné nastaviť správne prostredie eKasa klienta (integračné vs. produkčné).

-102: InvalidTime

Čas počítača je neplatný. Táto chyba nastane, ak rozdiel medzi lokálnym časom počítača a eKasa serverom prekročí stanovenú hodnotu serverTimeThresholdSeconds, nastavenú v konfigurácií klienta.

Chybu možno odstrániť úpravou lokálneho času na počítači: odporúča sa synchronizácia s internetovým časom.

Úprava parametra serverTimeThresholdSeconds nie je odporúčaná.

-103: InvalidReceiptNumber

Číslo dokladu nie je platné. Chyba nastane v prípade, že systémový číselník dokladu nie je synchronizovaný s úložiskom a dokladu bolo systémom priradené číslo, ktoré sa už na úložisku nachádza. Dôvodom môže byť napr. zmazanie systémového súboru (ten je určený v konfiguračnom poli dataFilePath).

-104: ReceiptNotFound

Doklad nebol nájdený. Upravte potrebné parametre v predmetnom dopyte volania a akciu zopakujte.

-105: InvalidEKasaEnvironment

Vykonanie požiadavky vyžaduje e-Kasa prostredie, ktoré je iné, ako aktuálne prednastavené. Táto chyba môže nastať, ak napr. požiadavka na registráciu dokladu alebo polohy používa ORP kód viazaný na prostredie iné, ako prednastavené alebo ak sa nahrávané identifikačné údaje viažu na rozdielne e-Kasa prostredie.

-200: IdentityError

Rezervované pre budúce použitie.

-201: IdentityNotFound

Identita s kódom on-line registračnej pokladne, uvedenom v poli cashRegisterCode, nebola nájdená. Táto chyba nastane, ak sa v úložisku nenachádza žiaden záznam identity (identifikačný údaj) s daným kódom on-line registračnej pokladne - cashRegisterCode. Nahratie požadovaných identifikačných údajov do úložiska odstráni vzniknutý problém.

-300: CertificateError

Chyba certifikátu indikuje problém týkajúci sa certifikátu, ktorého presná príčina je uvedená v poli detail.

Príčiny:

  • nesprávne heslo uvedené v procese nahrávania nového certifikátu do úložiska
  • nesprávne alebo poškodené údaje certifikátu

Riešením je opakované nahratie certifikátu so správnym heslom, resp. so správnymi údajmi o certifikáte (pole data).

-301: CertificateNotFound

Nebol nájdený žiaden (platný) certifikát pre identitu, uvedenú v poli cashRegisterCode. Táto chyba nastane v prípade, že do úložiska nebol doposiaľ nahratý žiaden certifikát (autentifikačný údaj) alebo existujúci certifikát už vypršal.

V oboch prípadoch sa vyžaduje nahratie nového certifikátu.

-302: CertificateExpired

Certifikát, pre kód on-line registračnej pokladne s číslom uvedeným v cashRegisterCode chybovej odpovedi, exspiroval. Pred registráciou ďalšieho dokladu alebo polohy je nutné nahrať nový platný certifikát.

-400: StorageError

Bližšie nešpecifikovaná chyba, ktorá nastala v súvislosti s prácou s chráneným dátovým úložiskom (čítanie resp. zápis na dátové úložisko alebo čítanie resp. zápis do pomocnej tabuľky indexov dátového úložiska).

Najbežnejšie príčiny sú, že dátové úložisko nie je pripojené k systému, alebo je v konfigurácii uvedený nesprávny názov sériového portu.

-401: StorageInsufficientSpace

Zázam sa nepodarilo uložiť s dôvodu nedostatočnej voľnej kapacity dátového média chráneného dátového úložiska.

-402: StorageDICMismatch

Do úložiska bol vykonaný pokus o zápis záznamu s DIČ hodnotou inou, ako je DIČ hodnota úložiska.

Úložisko je viazané na jeden podnikateľský subjekt, identifikovaný pomocou DIČ.

Pokus o vloženie identifikačných alebo autentifikačných údajov, prípadne dátovej správy (dokladu alebo polohy), ktorá neprislúcha tomuto podnikateľskému subjektu bude zamietnutý touto chybou.

-403: StorageDuplicateKey

Zápis do úložiska zlyhal, nakoľko pre daný kód on-line registračnej pokladne už v úložisku existuje záznam s rovnakým identifikátorom a tieto záznamy sú po svojej obsahovej stránke rôzne.

Vzor odpovede:

{
    "key": {
        "name": "RegistrationRequestExternalId",
        "value": "0afa4ca5-26d5-41d8-a485-cf2ad0e7d6f0"
    },
    "cashRegisterCode": "88812345678900001",
    "traceId": "0HLMDGC781MUH:00000002",
    "code": -10,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-403-storageduplicatekey",
    "title": "Duplicitný identifikátor",
    "status": 500,
    "detail": "Záznam s externým identifikátorom '0afa4ca5-26d5-41d8-a485-cf2ad0e7d6f0' už existuje.",
    "instance": "/api/v1/requests/receipts"
}

Úložisko si pred zápisom požiadavky overí unikátnosť:

  • identifikátora požiadavky (id)
  • externého identifikátora požiadavky: (externalId)
  • v prípade registrácie dokladu aj unikátnosť čísla dokladu (receiptNumber)

Za účelom bližšej identifikácie indexu, ktorého unikátnosť je porušená, sa v tele odpovede nachádza pole key.

Pole key obsahuje názov indexu porušujúceho uniátnosť (name) a jeho hodnotu (value).

Pole name nadobúda v závislosti od typu indexu tieto hodnoty:

Index Hodnota key.name Riešenie
Interné id RegistrationRequestId Pravdepodobnosť duplicitnej hodnoty pre interný identifikátor (Id) je extrémne nízka. V prípade výskytu je riešením opakovanie požiadavky.
Externé id RegistrationRequestExternalId V prípade duplicitnej hodnoty pre externý identifikátor (ExternalId) je potrebné hľadať príčinu v nadradenej aplikácií. Riešením je zopakovať požiadavku s novou hodnotou externého identifikátora.
Číslo dokladu ReceiptRegistrationRequestReceiptId Zhoda ReceiptNumber indikuje nezosynchronizovaný číselník dokladov s úložiskom. V tomto prípade ide o zlyhanie eKasa aplikácie. Odporúča sa aktualizovať eKasa API na najnovšiu dostupnú verziu.

Konkrétnú príčinu chyby popisujú vlastnosti chybovej odpovede titlea detail.

-404: StorageNotFound

Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu StorageModel alebo ChduSerialPortName a zároveň nebolo k zariadeniu pripojené žiadne z kompatibilných dátových úložísk.

-405: StorageAmbiguity

Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu StorageModel alebo ChduSerialPortName a zároveň bolo k zariadeniu pripojených viacero kompatibilných dátových úložísk.

-406: StorageForbiddenEKasaEnvironment

Chyba nastane, ak úložisko bolo použité na nepodporované e-Kasa prostredie, napr. InMemory úložisko bolo použité na produkčné (Production) prostredie.

-407: StorageForbiddenDeviceModel

Táto chyba vznikne v prípade, že úložisko je použité na nepodporovanom modeli zariadenia. Najčastejšie sa týka úložiska SwissBit, ktorého použitie je povolené výhradne na zariadeniach, ktoré absolvovali certifikačné konanie v súvislosti s aplikáciou eKasa na Finančnej správe SR.

Použitie úložiska SwissBit na inom než certifikovanom modeli zariadenia nie je povolené a vedie k vzniku tejto chyby. Výnimku tvorí režim tzv. technického dema, kedy je aplikácia viazaná výhradne na integračné prostredie systému eKasa za účelom overenia kompatibility zariadenia.

-500: PrinterError

Všeobecná chyba tlače na tlačiarni s názvom uvedeným v poli printerName. Presné príčiny zlyhania tlače sú uvedené v poli detail chybovej odpovede.

-501: PrinterNotFound

Tlačiareň s názvom, uvedeným v premennej printerName chybovej odpovedi, nebola nájdená a doklad nemôže byť vytlačený. Riešením je použiť, v každej ďalšiej požiadavke o zaevidovanie dokladu alebo polohy, jeden z platných názvov tlačiarní a to buď pos, pdf alebo email.

-502: PrintReceiptError

Tlač dokladu zlyhala. Ak chyba nastala počas požiadavky evidencie dokladu, doklad možno považovať za zaevidovaný eKasa serverom. Zákazníkovi je v takomto prípade nutné vystaviť kópiu dokladu, pričom v požiadavke sa uvedie jeden z jeho identifikátorov, uvedený v chybovej odpovedi a to buď requestExternalId, ak bol uvedený, alebo receiptId.

Príklad chybovej odpovede zlyhanej požiadavky spracovania dokladu:

{
    "printerName": "email",
    "receiptId": {
        "cashRegisterCode": "88812345678900001",
        "year": 2019,
        "month": 6,
        "receiptNumber": 21
    },
    "requestExternalId": null,
    "traceId": "0HLNDFM9VMUHB:00000001",
    "code": -502,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-502-printreceiptererror",
    "title": "Tlač dokladu zlyhala",
    "status": 500,
    "detail": "Tlač dokladu č.21 z 6/2019 pokladne 88812345678900001 na tlačiarni 'email' zlyhala.",
    "instance": "/api/v1/requests/receipts"
}

Následná požiadavka o vytlačenie kópie dokladu môže vyzerať nasledovne: {{server_address}}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&year=2019&month=6&receiptNumber=21

-503: PrinterNotReady

Tlačiareň s názvom, uvedeným v premennej printerName chybovej odpovedi, nie je pripojená a akcia súvisiaca s tlačiarňou nemôže byť dokončená. Riešením je overiť, či je tlačiareň fyzicky pripojená k úložisku a zapnutá.

Niektoré modely chráneného dátového úložiska (napríklad CHDU-SK) však umožňujú vykonanie akcie súvisiacej s tlačou aj napriek nepripravenej tlačiarni. Z tohto dôvodu majú niektoré akcie (tlač nefiskálneho dokladu, tlač kópie dokladu, tlač neodoslaných dátových správ, otvorenie peňažnej zásuvky, ...) vo svojich návratových modeloch vlastnosť printed.

-600: LicenseError

Pridané od verzie eKasa API 7.0.0.

Chyba licencie indikuje problém týkajúci sa licencie, ktorého presná príčina je uvedená v poli detail.

-601: LicenseInvalidError

Licencia je neplatná. Táto chyba nastane, ak licencia pre úložisko nie je platná alebo ak niektoré z používaných rozšírení nie sú platné.

Príklad chybovej odpovede:

{
  "storage": {
    "isValid": true,
    "customerWarranty": {
      "start": "2023-10-01T00:00:00",
        "end": "2024-10-31T23:59:59"
    },
    "error": {
      "message": "Úložisko nie je v záruke",
      "code": -104
    }
  },
  "features": [
    {
      "sku": "ekasa",
      "isValid": false,
      "version": "6.10.4",
      "validity": {
        "start": "2023-10-01T00:00:00",
        "end": "2024-10-31T23:59:59"
      },
      "error": {
        "message": "Licencia pre balík 'ekasa' vo verzii '6.10.4' nie je pre toto úložisko platná",
        "code": -203
      }
    }],
  "traceId": "0HLNDIHB0GA61:00000001",
  "code": -601,
  "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#601-licenseinvaliderror",
  "title": "Validácia je neplatná",
  "status": 500
}

-602: LicenseNotActivated

API odmietlo obslúžiť požiadavku, pretože zariadenie nemá aktivovanú licenciu. Aktivácia licencie nastáva pri prvom spustení aplikácie a jej priebeh či inštrukcie možno sledovať na obrazovke zariadenia.

Volajúci by mal používateľa nasmerovať na dokončenie aktivačného procesu v samotnej aplikácii (QR kód alebo ručné zadanie kódu od technika).

Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-602-licensenotactivated",
  "title": "Licencia nie je aktivovaná",
  "status": 503,
  "detail": "Licencia nie je aktivovaná.",
  "code": -602,
  "traceId": null,
}

-603: LicenseVerificationInProgress

Lokálne API je dočasne nedostupné, pretože práve prebieha štartovacie overovanie stavu zariadenia voči onboarding backendu. Ide o prechodný stav, ktorý typicky trvá iba prvé sekundy po spustení aplikácie — kým sa dokončí kontrola licencie.

Volajúci by mal požiadavku po krátkej pauze zopakovať (napr. 3–5 sekúnd).

Po úspešnom overení API automaticky prejde do režimu obsluhy požiadaviek; pri neúspechu sa stav zmení na -602 LicenseNotActivated.

Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-603-licenseverificationinprogress",
  "title": "Prebieha overovanie licencie",
  "status": 503,
  "detail": "Prebieha overovanie licencie.",
  "code": -603,
  "traceId": null,
}

-700: QrPaymentError

Nastala chyba súvisiaca so spracovaním QR platby.

Bližšiu príčinu určuje správa v tele odpovede.

-701: QrPaymentInitializationError

Nastala chyba pri vytváraní QR platby.

Medzi možné príčiny patrí:

  • Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb
    • z dôvodu výpadku sieťového pripojenia na eKasa zariadení
    • z dôvodu výpadku služby finančnej správy
  • Nadviazanie zabezpečeného sietoťového spojenia bolo zamietnuté službou okamžitých platieb

Príklad chybovej odpovede:

{
    "traceId": "0HNGIPOQC63UF:00000002",
    "code": -701,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-701-qrpaymentinitializationerror",
    "title": "Chyba vytvorenia QR platby",
    "status": 500,
    "detail": "Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb.",
    "instance": "/api/v1/payments/qr",
    "extensions": {}
}

-702: QrPaymentNotFoundError

QR platba s daným identifikátorom nebola nájdená.

Medzi možné príčiny patrí:

  • eKasa aplikácia bola od momentu vytvorenia QR platby reštartovaná
  • QR platba exspirovala a po uplynutí časového limitu bola vyradená z evidencie.

HTTP kód odpovede je 404.

Príklad chybovej odpovede:

{
    "traceId": null,
    "code": -702,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-702-qrpaymentnotfoundnerror",
    "title": "QR platba nebola nájdená",
    "status": 404,
    "detail": null,
    "instance": null,
    "extensions": {}
}

-900: ValidationError

Validácia zlyhala. Sever nemôže spracovať požiadavku, nakoľko obsahuje neplatné dáta. Chybné polia a ich príčiny sú uvedené v poli errors.

Príklad chybovej odpovede požiadavky s neplatnými údajmi:

{
    "errors": {
        "Request.Data.CashRegisterCode": [
            "Pole 'Cash Register Code' nemá správný formát."
        ]
    },
    "traceId": "0HLNDIHB0GA61:00000001",
    "code": -900,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#900-validationerror",
    "title": "Validácia zlyhala",
    "status": 400
}

-1000: Unauthenticated

Pridané od verzie eKasa API 6.7.1.

Požiadavka nebola autentifikovaná. Táto chyba natane, ak

  • je zapnuté zabezpečenie a požiadavka obsahuje neplatné prihlasovacie údaje (hodnota authScheme v odpovedi má hodnotu Basic)
  • ak bola vykonaná požiadavka na eKasa API cez službu Expose s neplatným bezpečnostným kódom (hodnota authScheme v odpovedi má hodnotu AccessToken)
{
    "authScheme": "AccessToken",
    "traceId": "0HMVHH6PS1J6J:00000002",
    "code": -1000,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-1000-unauthenticated",
    "title": "Nie ste prihlásený",
    "status": 401,
    "detail": null,
    "instance": "/api/v1/product/info",
    "extensions": {}
}