# Kontrola stavu systému

> Stav eKasy jedným volaním cez /api/v1/health aj jednotlivé kontroly: inicializačný balík, certifikát, úložisko, tlačiareň, spojenie a fronta.

Zdroj: https://ekasa.ninedigit.sk/docs/status

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](https://ekasa.ninedigit.sk/docs/integration-scope#optim%C3%A1lna-integr%C3%A1cia)).

Stav sa skladá zo šiestich oblastí a každú overíte samostatným volaním:

- [Identifikačné a autentifikačné údaje](#kompletný-inicializačný-balík) (`subject`): Či má pokladnica nahraný inicializačný balík.
- [Platnosť certifikátu](#blížiaca-sa-exspirácia-certifikátu) (`subject`): Upozornenie 30 dní pred koncom platnosti.
- [Úložisko](#overenie-stavu-úložiska) (`storage`): Stav a zaplnenie chráneného dátového úložiska.
- [Tlačiareň](#kontrola-stavu-tlačiarne) (`printer`): Papier, kryt a pripravenosť tlačiarne.
- [Spojenie](#kontrola-stavu-internetového-spojenia-so-systémom-ekasa) (`network`): Spojenie so systémom eKasa.
- [Fronta](#kontrola-obsahu-fronty-neodoslaných-správ) (`queue`): Dátové správy, ktoré čakajú na odoslanie.

**HTTP API:**

## Stav jedným volaním

V HTTP API zistíte stav všetkých oblastí naraz jedným volaním:

```http
GET http://localhost:3010/api/v1/health
```

```json
{
  "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í |

```json
{
  "name": "storage",
  "status": "Degraded",
  "description": "Chránené dátové úložisko vyžaduje reštart zariadenia na dokončenie prípravy.",
  "data": { "storageAction": "RebootDevice" }
}
```

**.NET knižnica:**

## 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](#kompletný-inicializačný-balík), [certifikát](#blížiaca-sa-exspirácia-certifikátu) |
| `storage` | `client.GetStorageInfoAsync()` | [úložisko](#overenie-stavu-úložiska) |
| `printer` | `client.GetPrinterStatusInfoAsync()` | [tlačiareň](#kontrola-stavu-tlačiarne) |
| `network` | `client.ConnectivityMonitor.GetStateAsync()` | [spojenie](#kontrola-stavu-internetového-spojenia-so-systémom-ekasa) |
| `queue` | `client.InitializeQueueAsync()`, `client.Queue.Filter()` | [fronta](#kontrola-obsahu-fronty-neodoslaných-správ) |
| `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

**HTTP API:**

```http
GET {server_address}/api/v1/identities
```

**.NET knižnica:**

```csharp
IReadOnlyList<Identity> identities = await client.IdentityManager.FindLatestIdentitiesAsync(cancellationToken);
```

### Získanie autentifikačných údajov

**HTTP API:**

```http
GET {server_address}/api/v1/certificates
```

**.NET knižnica:**

```csharp
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 koniec**: isAboutToExpire, 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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-q)). 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

**HTTP API:**

```http
GET {server_address}/api/v1/certificates/valid/latest?cashRegisterCode=88812345678900001
```

Ak pokladnica platný certifikát nemá, odpoveď je `404 Not Found`.

**.NET knižnica:**

```csharp
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:

```json
{
  "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](https://ekasa.ninedigit.sk/docs/integration-scope#optim%C3%A1lna-integr%C3%A1cia)).

### Získanie informácie o úložisku

**HTTP API:**

```http
GET {server_address}/api/v1/storage/info
```

**.NET knižnica:**

```csharp
StorageInfo storageInfo = await client.GetStorageInfoAsync(cancellationToken);
```

Vzorový výstup informácie o úložisku:

```json
{
  "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:

**HTTP API:**

```http
GET {server_address}/api/v1/printers/status
```

**.NET knižnica:**

```csharp
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);
```

Príklad stavu tlačiarne:

```json
{
  "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](https://ekasa.ninedigit.sk/docs/printer-status).

## Kontrola stavu internetového spojenia so systémom eKasa

Získanie informácie o stave internetového spojenia so systémom eKasa:

**HTTP API:**

```http
GET {server_address}/api/v1/connectivity/status
```

**.NET knižnica:**

```csharp
InternetConnectionStateInfo connection = await client.ConnectivityMonitor.GetStateAsync(cancellationToken);
```

Príklad stavu internetového pripojenia:

```json
{
  "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.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1)). S povolením daňového úradu na
odklad odosielania (predajné miesto bez internetového signálu) je lehota 30 dní
([§ 4 ods. 3](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-4.odsek-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)

**HTTP API:**

```http
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`.

**.NET knižnica:**

```csharp
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:

**HTTP API:**

```http
HEAD {server_address}/api/v1/requests?status=unprocessed
```

Počet správ je v hlavičke `Content-Range`.

**.NET knižnica:**

```csharp
var query = new RegistrationQuery();
query.Filter.ProcessStatus = RegistrationRecordProcessStatus.Unprocessed;

QueryCountResult result = await client.CountRegistrationsAsync(query, cancellationToken);
```

## Kam ďalej

- [Rozsah integrácie](https://ekasa.ninedigit.sk/docs/integration-scope): Kedy a ako často stav kontrolovať.
- [Stav tlačiarne](https://ekasa.ninedigit.sk/docs/printer-status): Hodnoty stavu a správanie pri nepripravenej tlačiarni.
- [Výsledok registrácie](https://ekasa.ninedigit.sk/docs/receipt-registration/result): Offline doklady a fronta neodoslaných správ.
