# System status check

> eKasa status in one call via /api/v1/health and the individual checks: initialization package, certificate, storage, printer, connection and queue.

Source: https://ekasa.ninedigit.sk/en/docs/status

A status check warns the operator about a problem before it stops sales: paper running out, authentication data about
to expire, a full storage or receipts waiting to be sent. We recommend calling it when your software starts and then
regularly (see [Integration scope](https://ekasa.ninedigit.sk/en/docs/integration-scope#optimal-integration)).

The status consists of six areas, and you check each of them with a separate call:

- [Identification and authentication data](#complete-initialization-package) (`subject`): Whether the cash register has the initialization package loaded.
- [Certificate validity](#approaching-certificate-expiry) (`subject`): A warning 30 days before the certificate expires.
- [Storage](#checking-the-storage-state) (`storage`): State and fill level of the protected data storage.
- [Printer](#checking-the-printer-status) (`printer`): Paper, cover and printer readiness.
- [Connection](#checking-the-internet-connection-to-the-ekasa-system) (`network`): Connection to the eKasa system.
- [Queue](#checking-the-queue-of-unsent-messages) (`queue`): Data messages waiting to be sent.

**HTTP API:**

## Status in one call

With the HTTP API, you get the status of all areas at once in one call:

```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."
    }
  ]
}
```

The overall `status` is the worst state of all the checks:

| State | Meaning | What to do |
|---|---|---|
| `Healthy` | everything is fine | nothing |
| `Degraded` | a problem is approaching, sales still work | warn the operator |
| `Unhealthy` | a problem that needs solving now | warn the operator prominently, sales may fail |

The response has HTTP status code `200` in every state; the `status` field decides. The text in `description` is in
Slovak and you can show it to the operator as is. The `data` field contains details of the check, for example the
certificate data.

| Check (`name`) | What it monitors |
|---|---|
| `queue` | data messages waiting to be sent; the business must send them within 96 hours |
| `subject` | identification and authentication data and certificate validity |
| `printer` | printer readiness and paper |
| `storage` | storage state and usage |
| `network` | connection to the eKasa system |
| `license` | the eKasa licence |
| `Expose` | the connection via Expose, if you use it |

From version 9.1:

- you can limit the checks with the `tag` parameter, for example `?tag=storage,queue` (without it, all checks run),
- with the `details=false` parameter you get only the states without description and data, even without logging in.
  This is useful for monitoring whether the service is running,
- the `indexTable` (storage index table) and `hosting` (HTTP and HTTPS) checks were added.

### SwissBit storage on Android

With a SwissBit storage in a payment terminal, the `storage` check can return the `Degraded` state with an action the
operator must take on the device. The eKasa application also warns the operator about it itself.

| `data.storageAction` | What to do | Where it occurs |
|---|---|---|
| `GrantStorageAccess` | allow the application access to all files in the device settings | Sunmi |
| `RebootDevice` | restart the device to finish preparing the storage | PAX, on first start |

```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 library:**

## Checks in the library

The .NET library has no single-call status. The eKasa service builds it from the same methods that are available
to you. You check each area with its own method and evaluate the status in your software:

| Area (`name` in the HTTP API) | Library method | Details |
|---|---|---|
| `subject` | `client.IdentityManager.FindLatestIdentitiesAsync()`, `client.CertificateManager.FindLatestValidCertificateInfoAsync()` | [data](#complete-initialization-package), [certificate](#approaching-certificate-expiry) |
| `storage` | `client.GetStorageInfoAsync()` | [storage](#checking-the-storage-state) |
| `printer` | `client.GetPrinterStatusInfoAsync()` | [printer](#checking-the-printer-status) |
| `network` | `client.ConnectivityMonitor.GetStateAsync()` | [connection](#checking-the-internet-connection-to-the-ekasa-system) |
| `queue` | `client.InitializeQueueAsync()`, `client.Queue.Filter()` | [queue](#checking-the-queue-of-unsent-messages) |
| `license` | `client.VerifyLicenseAsync()` | |
| `indexTable` | `client.GetIndexTableStatusAsync()` | |

## Complete initialization package

To use an on-line cash register (identified by its cash register code), an *initialization package* must be loaded
into eKasa. It consists of **identification** data (`Identity` in eKasa) and **authentication** data
(`Certificate`).

You do not need to check explicitly that the initialization package is complete. All eKasa functions that need the
package take the cash register code (`cashRegisterCode`) as a parameter and check the package state themselves.

If your software needs to get the registered identification or authentication data, use the calls below.

### Getting identification data

**HTTP API:**

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

**.NET library:**

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

### Getting authentication data

**HTTP API:**

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

**.NET library:**

```csharp
CertificateInfo? certificate = await client.CertificateManager.FindLatestCertificateInfoAsync(
    "88812345678900001", cancellationToken);
```

## Approaching certificate expiry

Every certificate has a limited validity, so check its expiry date as well. The `expirationDate` property holds the
expiry date, `daysToExpire` the number of days until expiry, `isAboutToExpire` is `true` 30 days before expiry and
`isExpired` is `true` after expiry.

**Valid**: 2 years from issue, status Healthy
→ 30 days before the end
**About to expire**: isAboutToExpire, status Degraded
→ expiry date
**Expired**: isExpired, status Unhealthy

The cash register must warn about the end of validity at least 30 days in advance
([§ 5(3)(q) of Act No. 384/2025 Coll.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-q), in Slovak). The business generates new authentication data on
the Financial Administration portal and loads it into eKasa before the expiry.

### Checking for a valid certificate

**HTTP API:**

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

If the cash register has no valid certificate, the response is `404 Not Found`.

**.NET library:**

```csharp
CertificateInfo? certificate = await client.CertificateManager.FindLatestValidCertificateInfoAsync(
    "88812345678900001", cancellationToken);
```

If the cash register has no valid certificate, the method returns `null`.

Sample output with certificate data:

```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
}
```

Read the cash register code from the `cashRegisterCode` field. The `alias` field is the name of the certificate and
has the same value today, but do not rely on its format. The certification authority may change it in the future.

## Checking the storage state

The protected data storage has a limited capacity and must be replaced once it is full. Warn the operator in advance
that the storage is getting full; with an integration, this is the job of your software
(see [Integration scope](https://ekasa.ninedigit.sk/en/docs/integration-scope#optimal-integration)).

### Getting storage information

**HTTP API:**

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

**.NET library:**

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

Sample storage information output:

```json
{
  "product": {
    "vendorName": "Nine Digit, s.r.o.",
    "name": "eKasa CHDÚ",
    "version": "v1.0",
    "serialNumber": "3A21D0E474C0"
  },
  "capacity": {
    "total": 8589934592,
    "used": 2173430
  },
  "isReadOnly": false
}
```

| Property | Description |
|---|---|
| `product` | vendor (`vendorName`), name (`name`), version (`version`) and serial number (`serialNumber`) of the storage |
| `capacity` | total (`total`) and used (`used`) storage capacity in bytes |
| `isReadOnly` | `true` if the storage has been irreversibly switched to read-only mode |

From the ratio of `used` to `total` you get the storage usage; from a certain threshold (for example 80 %), show the
operator a warning that the storage is getting full.

Read-only mode is used when the storage has been deliberately taken out of service. Its data can still be read.

## Checking the printer status

Getting the printer status:

**HTTP API:**

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

**.NET library:**

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

Sample printer status:

```json
{
  "state": "Ready",
  "paperState": "Ready",
  "errorState": "None"
}
```

The description of the values, examples for specific situations, an overview of what each device reports and the
application behaviour with a printer that is not ready are in the article [Printer status](https://ekasa.ninedigit.sk/en/docs/printer-status).

## Checking the internet connection to the eKasa system

Getting the state of the internet connection to the eKasa system:

**HTTP API:**

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

**.NET library:**

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

Sample internet connection state:

```json
{
  "requestDate": "2026-11-19T08:13:25Z",
  "state": "Up"
}
```

The `requestDate` property is the time the state was determined, in UTC. The internet connection state (the `state`
property) takes one of the following values:

- `Up`: the internet connection is available,
- `Down`: the internet connection is not available,
- `Unknown`: unknown state.

eKasa monitors the connection to the eKasa system itself. If there are unsent data messages in the queue (for example
receipts issued in offline mode), it tries to send them as soon as it detects that the connection is available again.

## Checking the queue of unsent messages

The business must send a data message (a receipt or a location registration) to the eKasa system within 96 hours of
the first attempt to send it ([§ 3(1) of Act No. 384/2025 Coll.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1)). With a tax office permission to postpone
sending (a place of sale without internet signal), the deadline is 30 days ([§ 4(3)](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-4.odsek-3)).

It is therefore advisable to monitor whether there are data messages in the queue that could not be sent.

### Number of unsent data messages for a specific cash register code (recommended)

**HTTP API:**

```http
HEAD {server_address}/api/v1/queue/items/unprocessed?cashRegisterCode=88812345678900001
```

The response has the status code `204` and the number of messages is in the `Content-Range` header.

**.NET library:**

```csharp
var filter = new RegisterTokenFilter
{
    State = RegisterTokenFilterState.Unprocessed,
    CashRegisterCode = "88812345678900001"
};

// the queue must be initialized before getting its items
await client.InitializeQueueAsync(cancellationToken);

int count = client.Queue.Filter(new RegisterTokenQuery(filter)).Count;
```

### Number of unsent data messages for all cash register codes

Alternatively, and more slowly, you get the number of unsent data messages for all cash register codes like this:

**HTTP API:**

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

The number of messages is in the `Content-Range` header.

**.NET library:**

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

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

## Where next

- [Integration scope](https://ekasa.ninedigit.sk/en/docs/integration-scope): When and how often to check the status.
- [Printer status](https://ekasa.ninedigit.sk/en/docs/printer-status): Status values and behaviour when the printer is not ready.
- [Registration result](https://ekasa.ninedigit.sk/en/docs/receipt-registration/result): Offline receipts and the queue of unsent messages.
