# Rozsah integrácie

> Čo musí váš softvér s eKasou vedieť: minimálna integrácia s registráciou dokladu, kontrola stavu, poloha pokladnice a voliteľné funkcie.

Zdroj: https://ekasa.ninedigit.sk/docs/integration-scope

eKasa vie veľa, no na začiatok stačí málo. Tento článok rozdeľuje integráciu do štyroch úrovní. Prvá stačí na
evidenciu tržieb, každá ďalšia uľahčí obsluhe prácu alebo pokryje ďalšie situácie u podnikateľa.

| Funkcia | Minimálna | Optimálna | Ideálna |
|---|:---:|:---:|:---:|
| Ochrana pred duplicitou (`externalId`) | áno | áno | áno |
| Registrácia dokladu a vyhodnotenie výsledku | áno | áno | áno |
| Uloženie identifikátora dokladu | áno | áno | áno |
| Kontrola stavu systému | nie | áno | áno |
| Upozornenie na koniec platnosti autentifikačných údajov | nie | áno | áno |
| Upozornenie na zaplnenie úložiska | nie | áno | áno |
| Evidencia paragónov | nie | nie | áno |
| Registrácia polohy (prenosná pokladnica) | nie | nie | áno |

Každá úroveň obsahuje všetko z predchádzajúcej. **Voliteľné funkcie**, napríklad úhradu faktúry, pridáte
k ktorejkoľvek úrovni podľa toho, čo potrebujú vaši zákazníci, prípadne vaša vlastná prevádzka.

## Minimálna integrácia

Váš softvér posiela eKase pokladničné doklady a vyhodnocuje výsledok. Nič iné na evidenciu tržieb nepotrebuje.

1. **`externalId` pri každom doklade.** Je to nevyhnutné: bez neho eKasa nerozozná opakované odoslanie a tržbu
   zaeviduje dvakrát, keď sa stratí odpoveď. Pozri [Ochrana pred duplicitou](https://ekasa.ninedigit.sk/docs/receipt-registration/external-id).
2. **Registrácia dokladu** pri predaji, vrátení tovaru aj oprave. Položky, platby a typy položiek popisuje článok
   [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration).
3. **Vyhodnotenie výsledku** podľa poľa `isSuccessful`:
   - `true`: doklad je zaevidovaný, predaj je hotový,
   - `null`: doklad je zaevidovaný v offline režime a vytlačený. Pre obsluhu je to tiež úspech, eKasa ho odošle sama,
   - `false`: systém eKasa doklad odmietol. Zobrazte obsluhe dôvod z poľa `error`.
4. **Uloženie identifikátora dokladu** k predaju vo vašom systéme: unikátny identifikátor, a kým ho doklad nemá,
   overovací kód podnikateľa (OKP). Potrebujete ho pri vrátení tovaru, oprave alebo vyhľadaní dokladu.
5. **Spracovanie chýb** požiadavky, napríklad neplatných údajov alebo nepripravenej tlačiarne, podľa kódu chyby
   (pozri [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api)).

Čo sa dá nastaviť jednorazovo, vrátane inicializačného balíka a polohy pokladnice, urobí podnikateľ alebo servisný
technik vo webovom rozhraní eKasy.

Pri minimálnej integrácii sa obsluha o probléme dozvie, až keď doklad zlyhá. Neodoslané doklady vo fronte,
končiaca platnosť autentifikačných údajov či dochádzajúce miesto v úložisku pritom eKasa vie ohlásiť vopred.
Preto odporúčame aspoň optimálnu integráciu.

## Optimálna integrácia

K minimálnej integrácii pridajte **kontrolu stavu systému**. Váš softvér sa eKasy pýta na stav pri spustení
a potom pravidelne, napríklad raz za pár minút alebo pred začiatkom zmeny, a upozorní obsluhu skôr, než nastane
problém.

**HTTP API:**

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

Od verzie 9.1 môžete kontroly obmedziť parametrom `tag`, napríklad `?tag=storage,queue`. Bez neho sa vykonajú
všetky.

Odpoveď obsahuje celkový stav a výsledok jednotlivých kontrol (skrátené):

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

Stav `Healthy` znamená, že je všetko v poriadku, `Degraded` upozorňuje na blížiaci sa problém a `Unhealthy`
na problém, ktorý treba riešiť hneď. Text z `description` môžete obsluhe rovno zobraziť.

**.NET knižnica:**

Jednotný stav jedným volaním poskytuje služba eKasy (HTTP API), .NET knižnica ho nemá. Úložisko, tlačiareň,
certifikát, frontu aj spojenie overíte jednotlivými volaniami, pozri [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status).

Na čo si dať pozor najmä:

| Kontrola | Prečo |
|---|---|
| fronta neodoslaných správ | podnikateľ musí každú dátovú správu odoslať do 96 hodín od prvého pokusu o 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)) |
| identifikačné a autentifikačné údaje | autentifikačné údaje platia 2 roky; 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)) |
| tlačiareň | chýbajúci papier alebo otvorený kryt zastaví predaj |
| úložisko | plné úložisko treba vymeniť, obsluha má byť upozornená vopred (nižšie) |
| spojenie so systémom eKasa | bez spojenia sa doklady hromadia vo fronte |

Upozornenie na dochádzajúcu kapacitu úložiska je povinné. Finančná správa na stránke
[Výrobcovia eKasy](https://www.financnasprava.sk/sk/podnikatelia/dane/ekasa/vyrobcovia-ekasa) uvádza, že úložisko sa zaplní približne za 2 až 6 rokov, potom ho treba vymeniť
a pokladnica musí na dochádzajúcu kapacitu upozorniť vopred. Pri integrácii cez HTTP API alebo knižnicu je to úloha
vášho softvéru.

Jednotlivé kontroly a ich údaje popisuje [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status). Pri .NET knižnici voláte
zodpovedajúce metódy klienta, ako uvádza ten istý článok.

## Ideálna integrácia

Ideálna integrácia pridáva **evidenciu paragónov** a **registráciu polohy**.

### Evidencia paragónov

Ak pokladnica nefunguje, obsluha vypisuje papierové paragóny a do 10 dní po obnovení prevádzky
pokladnice ich musí dodatočne zaevidovať ([§ 11 ods. 3 zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-11.odsek-3)).
Porucha môže postihnúť každého podnikateľa, preto by váš softvér mal vedieť zaevidovať paragón s dátumom a časom
jeho vyhotovenia a číslom paragónu. Postup je v článku [Typy dokladov](https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types).

### Registrácia polohy

Prenosná pokladnica, napríklad na trhoch, v taxíku alebo pri
predaji z auta, musí mať zaregistrovanú polohu, kde predáva. Polohu treba zaregistrovať pred začiatkom predaja
na novom mieste ([§ 7 ods. 8 zákona č. 384/2025 Z. z.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-7.odsek-8)).
Ak váš softvér beží na prenosnej pokladnici, u zákazníka alebo vo vašej vlastnej prevádzke, obsluha musí polohu
vedieť zadať priamo v ňom. Pozri
[Registrácia polohy](https://ekasa.ninedigit.sk/docs/location-registration).

## Voliteľné funkcie

Tieto funkcie pridajte podľa toho, čo potrebujú vaši zákazníci alebo vaša vlastná prevádzka:

- **Úhrada faktúry:** ak podnikateľ prijíma platby faktúr v hotovosti alebo kartou na predajnom mieste, musí ich
  zaevidovať ako doklad úhrady faktúry, nie ako bežný predaj. Pozri [Typy dokladov](https://ekasa.ninedigit.sk/docs/receipt-registration/receipt-types).
- **Vloženie inicializačného balíka z vášho softvéru** (identifikačné údaje cez `POST /api/v1/identities`,
  autentifikačné údaje cez `POST /api/v1/certificates`). Podnikateľ potom nemusí otvárať webové rozhranie eKasy.
- **Nastavenia eKasy** z vášho softvéru cez `GET` a `PUT /api/v1/settings`.
- **[Nefiškálny doklad](https://ekasa.ninedigit.sk/docs/nonfiscal-receipt):** objednávka, účet pred zaplatením alebo iný text na tlačiarni.
- **[Kópia a vyhľadanie dokladu](https://ekasa.ninedigit.sk/docs/receipt-lookup)**.
- **[QR platby](https://ekasa.ninedigit.sk/docs/qr-payments)** bez platobného terminálu.
- **[Peňažná zásuvka](https://ekasa.ninedigit.sk/docs/drawer)** otváraná cez eKasu.

## Kam ďalej

- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Kontrola stavu systému](https://ekasa.ninedigit.sk/docs/status): Úložisko, autentifikačné údaje, tlačiareň a spojenie.
- [Registrácia polohy](https://ekasa.ninedigit.sk/docs/location-registration): Kedy a ako zaregistrovať polohu prenosnej pokladnice.
