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
- -100: GeneralError
- -101: ClientLocked
- -102: InvalidTime
- -103: InvalidReceiptNumber
- -104: ReceiptNotFound
Chyby identifikačných údajov -2XX
- -200: IdentityError
- -201: IdentityNotFound
Chyby autentifikačných údajov -3XX
- -300: CertificateError
- -301: CertificateNotFound
- -302: CertificateExpired
Chyby úložiska -4XX
- -400: StorageError
- -401: StorageInsufficientSpace
- -402: StorageDICMismatch
- -403: StorageDuplicateKey
Chyby tlače -5XX
- -500: PrinterError
- -501: PrinterNotFound
- -502: PrintReceiptError
- -503: PrinterNotReady
Chyby licencie -6XX
- -600: LicenseError
- -601: LicenseInvalidError
Validačné chyby
- -900: ValidationError
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 úspšené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.
-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 nedosatoč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 title
a detail
.
-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
}
-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á hodnotuBasic
) - 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á hodnotuAccessToken
)
{
"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": {}
}