Integration scope

Integrating via

eKasa can do a lot, but you need little to start. This article splits the integration into four levels. The first is enough to record sales; each further level makes the cashier’s work easier or covers more situations at the business.

Feature Minimal Optimal Ideal
Duplicate protection (externalId) yes yes yes
Receipt registration and evaluating the result yes yes yes
Storing the receipt identifier yes yes yes
System status checks no yes yes
Warning about authentication data expiry no yes yes
Warning about storage running full no yes yes
Paragon registration no no yes
Location registration (portable cash register) no no yes

Each level includes everything from the previous one. Optional features, such as invoice payment, can be added to any level depending on what your customers, or your own shop, need.

Minimal integration

Your software sends cash register receipts to eKasa and evaluates the result. Nothing else is needed to record sales.

  1. An externalId with every receipt. This is essential: without it, eKasa cannot recognise a resend and records the sale twice when a response is lost. See Duplicate protection.
  2. Receipt registration for sales, returns and corrections. Items, payments and item types are described in Receipt registration.
  3. Evaluating the result by the isSuccessful field:
    • true: the receipt is registered and the sale is complete,
    • null: the receipt is registered in offline mode and printed. For the cashier this is a success too; eKasa sends it by itself,
    • false: the eKasa system rejected the receipt. Show the cashier the reason from the error field.
  4. Storing the receipt identifier with the sale in your system: the unique identifier, or the business verification code (OKP) until the receipt has one. You need it for returns, corrections and receipt lookups.
  5. Handling request errors, such as invalid data or a printer that is not ready, by the error code (see HTTP API).

One-off setup, including the initialization package and the cash register location, is done by the business or a service technician in the eKasa web interface.

With a minimal integration, the cashier learns about a problem only when a receipt fails. Yet eKasa can report unsent receipts in the queue, expiring authentication data or a storage running out of space in advance. That is why we recommend at least the optimal integration.

Optimal integration

Add system status checks to the minimal integration. Your software asks eKasa for its status at startup and then regularly, for example every few minutes or before a shift starts, and warns the cashier before a problem occurs.

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

From version 9.1 you can limit the checks with the tag parameter, for example ?tag=storage,queue. Without it, all checks run.

The response contains the overall status and the result of each check (shortened):

{
  "status": "Healthy",
  "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": "Healthy",
      "description": "Tlačiareň je pripravená."
    },
    {
      "name": "storage",
      "status": "Healthy"
    },
    {
      "name": "network",
      "status": "Healthy"
    }
  ]
}

Healthy means everything is fine, Degraded warns about an upcoming problem and Unhealthy about a problem that needs attention now. You can show the text from description (in Slovak) directly to the cashier.

The single-call status is provided by the eKasa service (HTTP API); the .NET library does not have it. You check the storage, printer, certificate, queue and connection with individual calls, see System status.

What to watch in particular:

Check Why
unsent message queue the business must send every data message within 96 hours of the first attempt (§ 3(1) of Act No. 384/2025, in Slovak)
identification and authentication data authentication data is valid for 2 years; the cash register must warn about the expiry at least 30 days in advance (§ 5(3)(q) of Act No. 384/2025, in Slovak)
printer missing paper or an open cover stops sales
storage a full storage has to be replaced; the cashier should be warned in advance (below)
connection to the eKasa system without a connection, receipts pile up in the queue

Warning about the storage running out of capacity is mandatory. On its page Výrobcovia eKasy (in Slovak), the Financial Administration states that the storage fills up in roughly 2 to 6 years, then it has to be replaced, and the cash register must warn about the running-out capacity in advance. With an integration via the HTTP API or the library, this is your software’s job.

The individual checks and their data are described in System status. With the .NET library you call the corresponding client methods listed in the same article.

Ideal integration

The ideal integration adds paragon registration and location registration.

Paragon registration

When the cash register does not work, the cashier writes paper receipts (paragons) and must register them within 10 days after the cash register is working again (§ 11(3) of Act No. 384/2025, in Slovak). A failure can affect any business, so your software should be able to register a paragon with the date and time it was written and its number. See Receipt types.

Location registration

A portable cash register, for example at markets, in a taxi or when selling from a van, must have the location where it sells registered. The location must be registered before sales start at a new place (§ 7(8) of Act No. 384/2025, in Slovak). If your software runs on a portable cash register, at a customer’s or in your own shop, the cashier must be able to enter the location directly in it. See Location registration.

Optional features

Add these features depending on what your customers, or your own shop, need:

  • Invoice payment: if the business accepts invoice payments in cash or by card at the point of sale, it must record them as an invoice payment receipt, not as a regular sale. See Receipt types.
  • Inserting the initialization package from your software (identification data via POST /api/v1/identities, authentication data via POST /api/v1/certificates). The business then does not have to open the eKasa web interface.
  • eKasa settings from your software via GET and PUT /api/v1/settings.
  • Non-fiscal receipt: an order, a bill before payment or other text on the printer.
  • Receipt copy and lookup.
  • QR payments without a payment terminal.
  • Cash drawer opened through eKasa.

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.