System status check

Integrating via

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

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

Status in one call

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

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

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
{
  "name": "storage",
  "status": "Degraded",
  "description": "Chránené dátové úložisko vyžaduje reštart zariadenia na dokončenie prípravy.",
  "data": { "storageAction": "RebootDevice" }
}

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, certificate
storage client.GetStorageInfoAsync() storage
printer client.GetPrinterStatusInfoAsync() printer
network client.ConnectivityMonitor.GetStateAsync() connection
queue client.InitializeQueueAsync(), client.Queue.Filter() queue
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

GET {server_address}/api/v1/identities
IReadOnlyList<Identity> identities = await client.IdentityManager.FindLatestIdentitiesAsync(cancellationToken);

Getting authentication data

GET {server_address}/api/v1/certificates
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.

Valid2 years from issue, status Healthy

30 days before the end

About to expireisAboutToExpire, status Degraded

expiry date

ExpiredisExpired, 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., 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

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

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

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:

{
  "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).

Getting storage information

GET {server_address}/api/v1/storage/info
StorageInfo storageInfo = await client.GetStorageInfoAsync(cancellationToken);

Sample storage information output:

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

GET {server_address}/api/v1/printers/status
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);

Sample printer status:

{
  "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.

Checking the internet connection to the eKasa system

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

GET {server_address}/api/v1/connectivity/status
InternetConnectionStateInfo connection = await client.ConnectivityMonitor.GetStateAsync(cancellationToken);

Sample internet connection state:

{
  "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.). With a tax office permission to postpone sending (a place of sale without internet signal), the deadline is 30 days (§ 4(3)).

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

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.

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:

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

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

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

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

Where next

Esc

↑↓ selectEnter openEsc close

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.