Kontrola stavu systému

Integrujem cez

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:

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=false dostanete 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) a hosting (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.

Platný2 roky od vydania, stav Healthy

30 dní pred koncom

Blíži sa koniecisAboutToExpire, stav Degraded

deň exspirácie

ExspirovanýisExpired, stav Unhealthy

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);

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.