# Integration scope

> What your software needs to do with eKasa: minimal receipt registration, status checks, invoice payments, location and optional features.

Source: https://ekasa.ninedigit.sk/en/docs/integration-scope

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](https://ekasa.ninedigit.sk/en/docs/receipt-registration/external-id).
2. **Receipt registration** for sales, returns and corrections. Items, payments and item types are described in
   [Receipt registration](https://ekasa.ninedigit.sk/en/docs/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](https://ekasa.ninedigit.sk/en/docs/rest-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.

**HTTP API:**

```http
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):

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

**.NET library:**

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](https://ekasa.ninedigit.sk/en/docs/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](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1), 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](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-5.odsek-3.pismeno-q), 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](https://www.financnasprava.sk/sk/podnikatelia/dane/ekasa/vyrobcovia-ekasa) (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](https://ekasa.ninedigit.sk/en/docs/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](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-11.odsek-3), 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](https://ekasa.ninedigit.sk/en/docs/receipt-registration/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](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-7.odsek-8), 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](https://ekasa.ninedigit.sk/en/docs/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](https://ekasa.ninedigit.sk/en/docs/receipt-registration/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](https://ekasa.ninedigit.sk/en/docs/nonfiscal-receipt):** an order, a bill before payment or other text on the printer.
- **[Receipt copy and lookup](https://ekasa.ninedigit.sk/en/docs/receipt-lookup)**.
- **[QR payments](https://ekasa.ninedigit.sk/en/docs/qr-payments)** without a payment terminal.
- **[Cash drawer](https://ekasa.ninedigit.sk/en/docs/drawer)** opened through eKasa.

## Where next

- [Receipt registration](https://ekasa.ninedigit.sk/en/docs/receipt-registration): Receipt types, items, payments and the result.
- [System status](https://ekasa.ninedigit.sk/en/docs/status): Storage, authentication data, printer and connection.
- [Location registration](https://ekasa.ninedigit.sk/en/docs/location-registration): When and how to register the location of a portable cash register.
