Kontrola stavu upozorní obsluhu na problém skôr, než zastaví predaj: dochádzajúci papier, končiacu platnosť autentifikačných údajov, plné úložisko alebo doklady, ktoré čakajú na odoslanie. Odporúčame ju volať pri spustení vášho softvéru a potom pravidelne (pozri Rozsah integrácie).
Stav sa skladá zo šiestich oblastí a každú overíte samostatným volaním:
subjectIdentifikačné a autentifikačné údajeČi má pokladnica nahraný inicializačný balík.
subjectPlatnosť certifikátuUpozornenie 30 dní pred koncom platnosti.
storageÚložiskoStav a zaplnenie chráneného dátového úložiska.
printerTlačiareňPapier, kryt a pripravenosť tlačiarne.
networkSpojenieSpojenie so systémom eKasa.
queueFrontaDátové správy, ktoré čakajú na odoslanie.
Stav jedným volaním
V HTTP API zistíte stav všetkých oblastí naraz jedným volaním:
GET http://localhost:3010/api/v1/health
{
"status": "Degraded",
"totalDuration": 27,
"entries": [
{
"name": "queue",
"status": "Healthy",
"description": "Fronta neodoslaných správ je prázdna."
},
{
"name": "subject",
"status": "Healthy",
"description": "Identifikačné a autentifikačné údaje sú v poriadku."
},
{
"name": "printer",
"status": "Degraded",
"description": "Tlačiareň je pripravená. Papier v tlačiarni sa míňa."
},
{
"name": "storage",
"status": "Healthy",
"description": "Chránené dátové úložisko je v poriadku."
},
{
"name": "network",
"status": "Healthy",
"description": "Spojenie so serverom finančnej správy je v poriadku."
},
{
"name": "license",
"status": "Healthy",
"description": "Licencia je v poriadku."
}
]
}
Celkový status je najhorší stav zo všetkých kontrol:
| Stav | Význam | Čo urobiť |
|---|---|---|
Healthy |
všetko v poriadku | nič |
Degraded |
blíži sa problém, predaj zatiaľ funguje | upozornite obsluhu |
Unhealthy |
problém, ktorý treba riešiť hneď | upozornite obsluhu výrazne, predaj môže zlyhať |
Odpoveď má stavový kód HTTP 200 pri každom stave, rozhoduje pole status. Text v description je po slovensky
a môžete ho obsluhe rovno zobraziť. Pole data obsahuje podrobnosti danej kontroly, napríklad údaje o certifikáte.
Kontrola (name) |
Čo sleduje |
|---|---|
queue |
dátové správy čakajúce na odoslanie; podnikateľ ich musí odoslať do 96 hodín |
subject |
identifikačné a autentifikačné údaje a platnosť certifikátu |
printer |
pripravenosť tlačiarne a papier |
storage |
stav a zaplnenie úložiska |
network |
spojenie so systémom eKasa |
license |
licenciu eKasy |
Expose |
spojenie cez Expose, ak ho používate |
Od verzie 9.1:
- kontroly môžete obmedziť parametrom
tag, napríklad?tag=storage,queue(bez neho sa vykonajú všetky), - s parametrom
details=falsedostanete len stavy bez popisu a údajov, aj bez prihlásenia. Hodí sa na monitorovanie, či služba beží, - pribudli kontroly
indexTable(tabuľka indexov úložiska) ahosting(HTTP a HTTPS).
Úložisko SwissBit na Androide
Pri úložisku SwissBit v platobnom termináli môže kontrola storage vrátiť stav Degraded s akciou, ktorú musí
obsluha urobiť na zariadení. Aplikácia eKasa na ňu obsluhu upozorní aj sama.
data.storageAction |
Čo urobiť | Kde nastáva |
|---|---|---|
GrantStorageAccess |
povoliť aplikácii prístup ku všetkým súborom v nastaveniach zariadenia | Sunmi |
RebootDevice |
reštartovať zariadenie, aby sa dokončila príprava úložiska | PAX, pri prvom spustení |
{
"name": "storage",
"status": "Degraded",
"description": "Chránené dátové úložisko vyžaduje reštart zariadenia na dokončenie prípravy.",
"data": { "storageAction": "RebootDevice" }
}
Kontroly v knižnici
.NET knižnica jednotný stav jedným volaním nemá. Ten skladá služba eKasy z rovnakých metód, aké máte k dispozícii aj vy. Každú oblasť overíte vlastnou metódou a stav vyhodnotíte vo svojom softvéri:
Oblasť (name v HTTP API) |
Metóda knižnice | Podrobnosti |
|---|---|---|
subject |
client.IdentityManager.FindLatestIdentitiesAsync(), client.CertificateManager.FindLatestValidCertificateInfoAsync() |
údaje, certifikát |
storage |
client.GetStorageInfoAsync() |
úložisko |
printer |
client.GetPrinterStatusInfoAsync() |
tlačiareň |
network |
client.ConnectivityMonitor.GetStateAsync() |
spojenie |
queue |
client.InitializeQueueAsync(), client.Queue.Filter() |
fronta |
license |
client.VerifyLicenseAsync() |
|
indexTable |
client.GetIndexTableStatusAsync() |
Kompletný inicializačný balík
Aby bolo možné on-line pokladnicu (identifikovanú kódom pokladnice) používať, musí byť do eKasy vložený
inicializačný balík. Skladá sa z identifikačných údajov (v eKase Identity) a autentifikačných údajov
(Certificate).
Kompletnosť inicializačného balíka nie je nutné explicitne kontrolovať. Všetky funkcie eKasy, ktoré balík potrebujú,
preberajú kód pokladnice (cashRegisterCode) ako parameter a stav balíka si overia samy.
Ak potrebujete zo svojho softvéru získať zaregistrované identifikačné alebo autentifikačné údaje, použite volania nižšie.
Získanie identifikačných údajov
GET {server_address}/api/v1/identities
IReadOnlyList<Identity> identities = await client.IdentityManager.FindLatestIdentitiesAsync(cancellationToken);
Získanie autentifikačných údajov
GET {server_address}/api/v1/certificates
CertificateInfo? certificate = await client.CertificateManager.FindLatestCertificateInfoAsync(
"88812345678900001", cancellationToken);
Blížiaca sa exspirácia certifikátu
Každý certifikát má obmedzenú platnosť, preto kontrolujte aj dátum jeho exspirácie. Vlastnosť expirationDate
obsahuje dátum exspirácie, daysToExpire počet dní do exspirácie, isAboutToExpire je true 30 dní pred
exspiráciou a isExpired je true po exspirácii.
30 dní pred koncom
deň exspirácie
Na koniec platnosti musí pokladnica upozorniť najneskôr 30 dní vopred (§ 5 ods. 3 písm. q) zákona č. 384/2025 Z. z.). Nové autentifikačné údaje si podnikateľ vygeneruje na portáli finančnej správy a nahrá do eKasy ešte pred exspiráciou.
Overenie existencie platného certifikátu
GET {server_address}/api/v1/certificates/valid/latest?cashRegisterCode=88812345678900001
Ak pokladnica platný certifikát nemá, odpoveď je 404 Not Found.
CertificateInfo? certificate = await client.CertificateManager.FindLatestValidCertificateInfoAsync(
"88812345678900001", cancellationToken);
Ak pokladnica platný certifikát nemá, metóda vráti null.
Vzorový výstup s údajmi o certifikáte:
{
"alias": "88812345678900001",
"cashRegisterCode": "88812345678900001",
"issueDate": "2025-03-12T09:41:07+01:00",
"expirationDate": "2027-03-12T09:41:07+01:00",
"serialNumber": "2B0A",
"isNotYetValid": false,
"isValid": true,
"isAboutToExpire": false,
"daysToExpire": 113,
"isExpired": false
}
Kód pokladnice čítajte z poľa cashRegisterCode. Pole alias je pomenovanie certifikátu a dnes má rovnakú
hodnotu, na jeho formát sa však nespoliehajte. Certifikačná autorita ho môže v budúcnosti zmeniť.
Overenie stavu úložiska
Chránené dátové úložisko má obmedzenú kapacitu a po zaplnení ho treba vymeniť. Na blížiace sa zaplnenie upozornite obsluhu vopred, pri integrácii je to úloha vášho softvéru (pozri Rozsah integrácie).
Získanie informácie o úložisku
GET {server_address}/api/v1/storage/info
StorageInfo storageInfo = await client.GetStorageInfoAsync(cancellationToken);
Vzorový výstup informácie o úložisku:
{
"product": {
"vendorName": "Nine Digit, s.r.o.",
"name": "eKasa CHDÚ",
"version": "v1.0",
"serialNumber": "3A21D0E474C0"
},
"capacity": {
"total": 8589934592,
"used": 2173430
},
"isReadOnly": false
}
| Vlastnosť | Popis |
|---|---|
product |
dodávateľ (vendorName), názov (name), verzia (version) a sériové číslo (serialNumber) úložiska |
capacity |
celková (total) a použitá (used) kapacita úložiska v bajtoch |
isReadOnly |
true, ak je úložisko nevratne prepnuté do režimu iba na čítanie |
Podielom used a total vyčíslite obsadenosť úložiska a od určitej hranice (napríklad 80 %) zobrazte obsluhe
upozornenie o blížiacom sa zaplnení.
Režim iba na čítanie sa používa, keď bolo úložisko úmyselne vyradené z prevádzky. Údaje z neho sa dajú ďalej čítať.
Kontrola stavu tlačiarne
Získanie informácie o stave tlačiarne:
GET {server_address}/api/v1/printers/status
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);
Príklad stavu tlačiarne:
{
"state": "Ready",
"paperState": "Ready",
"errorState": "None"
}
Popis jednotlivých hodnôt, príklady pre konkrétne situácie, prehľad toho, čo ktoré zariadenie hlási, a správanie aplikácie pri nepripravenej tlačiarni nájdete v článku Stav tlačiarne.
Kontrola stavu internetového spojenia so systémom eKasa
Získanie informácie o stave internetového spojenia so systémom eKasa:
GET {server_address}/api/v1/connectivity/status
InternetConnectionStateInfo connection = await client.ConnectivityMonitor.GetStateAsync(cancellationToken);
Príklad stavu internetového pripojenia:
{
"requestDate": "2026-11-19T08:13:25Z",
"state": "Up"
}
Vlastnosť requestDate je čas zistenia stavu v UTC. Stav internetového pripojenia (vlastnosť state) nadobúda
niektorú z nasledovných hodnôt:
Up: internetové spojenie je dostupné,Down: internetové spojenie nie je dostupné,Unknown: neznámy stav.
eKasa sama sleduje stav spojenia so systémom eKasa. Ak sú vo fronte neodoslané dátové správy (napríklad doklady vyhotovené v offline režime), pokúsi sa ich odoslať hneď, ako zistí, že spojenie je opäť dostupné.
Kontrola obsahu fronty neodoslaných správ
Podnikateľ je povinný odoslať dátovú správu (doklad alebo registráciu polohy) do systému eKasa do 96 hodín od prvého pokusu o jej odoslanie (§ 3 ods. 1 zákona č. 384/2025 Z. z.). S povolením daňového úradu na odklad odosielania (predajné miesto bez internetového signálu) je lehota 30 dní (§ 4 ods. 3).
Preto je vhodné sledovať, či vo fronte nie sú dátové správy, ktoré sa nepodarilo odoslať.
Počet neodoslaných dátových správ pre konkrétny kód pokladnice (odporúčaný postup)
HEAD {server_address}/api/v1/queue/items/unprocessed?cashRegisterCode=88812345678900001
Odpoveď má stavový kód 204 a počet správ je v hlavičke Content-Range.
var filter = new RegisterTokenFilter
{
State = RegisterTokenFilterState.Unprocessed,
CashRegisterCode = "88812345678900001"
};
// fronta musí byť pred získaním jej položiek inicializovaná
await client.InitializeQueueAsync(cancellationToken);
int count = client.Queue.Filter(new RegisterTokenQuery(filter)).Count;
Počet neodoslaných dátových správ pre všetky kódy pokladníc
Alternatívne, no časovo náročnejšie, zistíte počet neodoslaných dátových správ pre všetky kódy pokladníc takto:
HEAD {server_address}/api/v1/requests?status=unprocessed
Počet správ je v hlavičke Content-Range.
var query = new RegistrationQuery();
query.Filter.ProcessStatus = RegistrationRecordProcessStatus.Unprocessed;
QueryCountResult result = await client.CountRegistrationsAsync(query, cancellationToken);